eddev 2.3.12 → 2.3.13

package/skills/eddev/docs/snippets/submitting-forms-to-rpc.mdx

@@ -0,0 +1,91 @@
+# Submitting Forms To RPC (/docs/snippets/submitting-forms-to-rpc)
+
+**Create a serverless mutation and call it from React**
+
+Use this when the frontend needs to submit to a third-party API or perform server-side work without exposing credentials in the browser.
+
+For the full API reference, see [RPC Functions](/docs/serverless/functions). For generated GraphQL mutations, see [Mutation Hooks](/docs/graphql/mutation-hooks).
+
+## Create A Mutation Route [#create-a-mutation-route]
+
+```ts filename="server/routes/api.newsletter.ts"
+import { rpc } from "eddev/server"
+import { z } from "zod"
+
+export default rpc.router({
+  signup: rpc.procedure
+    .input(
+      z.object({
+        email: z.string().email(),
+        lists: z.array(
+          z.object({
+            listId: z.string(),
+            title: z.string(),
+          }),
+        ),
+      }),
+    )
+    .mutation(async ({ input }) => {
+      const results = await Promise.all(
+        input.lists.map(async (list) => {
+          const params = new URLSearchParams()
+          params.append("EMAIL", input.email)
+          params.append("id", list.listId)
+
+          const response = await fetch(`https://example.com/subscribe?${params}`, {
+            method: "GET",
+          })
+
+          return response.ok
+        }),
+      )
+
+      if (results.every((ok) => !ok)) {
+        throw new Error("Failed to subscribe")
+      }
+
+      return { success: true }
+    }),
+})
+```
+
+## Call It From React [#call-it-from-react]
+
+```tsx filename="features/newsletter/NewsletterForm.tsx"
+import { useRPCMutation } from "eddev/hooks"
+import { useState } from "react"
+
+export function NewsletterForm() {
+  const [email, setEmail] = useState("")
+  const signup = useRPCMutation("api.newsletter.signup")
+
+  if (signup.isSuccess) {
+    return <p>Thank you for signing up.</p>
+  }
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault()
+        signup.mutate({
+          email,
+          lists: [{ listId: "abc123", title: "Newsletter" }],
+        })
+      }}
+    >
+      {signup.isError && <p>{signup.error.message}</p>}
+      <input
+        type="email"
+        value={email}
+        disabled={signup.isPending}
+        onChange={(event) => setEmail(event.currentTarget.value)}
+      />
+      <button type="submit" disabled={signup.isPending}>
+        Sign up
+      </button>
+    </form>
+  )
+}
+```
+
+RPC routes are part of the serverless frontend. Make sure `serverless.endpoints` is configured for WordPress-hosted SPA/admin usage. See [Serverless](/docs/serverless) for deployment setup.

package/skills/eddev/docs/snippets/svgs.mdx

@@ -0,0 +1,38 @@
+# SVGs (/docs/snippets/svgs)
+
+**Copy/paste SVG upload and GraphQL snippets**
+
+## Expose Raw SVG Content [#expose-raw-svg-content]
+
+Use a computed GraphQL field when the frontend needs the raw SVG string instead of a media URL.
+
+```php
+add_action('graphql_register_types', function () {
+  register_graphql_field('MediaItem', 'svgContent', [
+    'type' => 'String',
+    'description' => __('The raw SVG content of the media item', 'your-textdomain'),
+    'resolve' => function ($mediaItem) {
+      $filePath = get_attached_file($mediaItem->ID);
+
+      if (preg_match('/\.svg$/i', $filePath) && file_exists($filePath)) {
+        return file_get_contents($filePath);
+      }
+
+      return null;
+    },
+  ]);
+});
+```
+
+```graphql filename="blocks/content/icon.graphql"
+query IconBlock {
+  block {
+    content_icon {
+      icon {
+        svgContent
+        altText
+      }
+    }
+  }
+}
+```

package/skills/eddev/docs/snippets/type-safe-acf-dropdowns.mdx

@@ -0,0 +1,72 @@
+# Type-Safe ACF Dropdowns (/docs/snippets/type-safe-acf-dropdowns)
+
+**Register one enum field and use its generated TypeScript type**
+
+Use this when a CMS dropdown should become a narrow TypeScript type instead of a loose `string`.
+
+For the fundamentals, see [Custom Enums](/docs/acf/custom-enums). For broader color-theme usage, see [Color Schemes](/docs/guides/color-schemes). For schema extension context, see [Extending GraphQL](/docs/graphql/extending).
+
+## Register The Enum Field Type [#register-the-enum-field-type]
+
+Put enum field registrations in backend field files. For a page color selector, use:
+
+```php filename="backend/fields/page-color.php"
+<?php
+
+ED()->registerEnumFieldType("page-color", [
+  "label" => "Page Color",
+  "type" => "select",
+  "allow_null" => 1,
+  "options" => [
+    "silver" => "Silver",
+    "green" => "Green",
+    "blue" => "Blue",
+    "orange" => "Orange",
+    "yellow" => "Yellow",
+  ],
+]);
+```
+
+`type` controls the underlying ACF UI. eddev supports `select`, `button_group`, `radio`, and `checkbox`; use `select` unless the field needs a different editing control. `checkbox` returns multiple values.
+
+## Add It Anywhere ACF Fields Are Used [#add-it-anywhere-acf-fields-are-used]
+
+Once registered, `page-color` is available as an ACF field type. Add it to a block field group, post type field group, options page, taxonomy, or any other ACF location the same way you would add a normal ACF field.
+
+When that field is selected in GraphQL, codegen uses the enum field name to create a TypeScript type: `page-color` becomes `PageColor`. Current generated GraphQL exports include an `Option` suffix, so the import is `PageColorOption`.
+
+## Use The Generated Type In React [#use-the-generated-type-in-react]
+
+Keep the component API simple. Alias the generated type if the component wants the shorter `PageColor` name.
+
+```tsx filename="components/PageColorPanel.tsx"
+import type { PageColorOption } from "@generated-types"
+import type { ReactNode } from "react"
+
+type PageColor = PageColorOption
+
+type Props = {
+  color: PageColor
+  title: string
+  children: ReactNode
+}
+
+const colorClasses: Record<PageColor, string> = {
+  silver: "theme-silver",
+  green: "theme-green",
+  blue: "theme-blue",
+  orange: "theme-orange",
+  yellow: "theme-yellow",
+}
+
+export function PageColorPanel(props: Props) {
+  return (
+    <section className={colorClasses[props.color]}>
+      <h2>{props.title}</h2>
+      {props.children}
+    </section>
+  )
+}
+```
+
+Keep the PHP options and `colorClasses` in sync. If a new CMS option is added, TypeScript will force you to decide how it renders.

package/skills/eddev/docs/snippets.mdx

@@ -0,0 +1,19 @@
+# Overview (/docs/snippets)
+
+**Situation-based recipes from real eddev themes**
+
+Snippets are short recipes for specific situations. Use them when you know the problem you are solving and want a source-backed starting point to paste into a theme.
+
+These examples are simplified from Sol People and SFF-style project patterns. Each page links back to the deeper docs for the underlying API.
+
+| Recipe                                                 | Use It When                                                                         |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| [Querying Specific Blocks](./querying-specific-blocks) | You need one block, a subset of blocks, or blocks from another post/template part.  |
+| [Type-Safe ACF Dropdowns](./type-safe-acf-dropdowns)   | A CMS dropdown should become a generated TypeScript union.                          |
+| [Multiple Editable Zones](./multiple-editable-zones)   | One block needs more than one independent editable child area.                      |
+| [Automated Block Layouts](./automated-block-layouts)   | Layout wrappers should be driven by block flags instead of repeated in every block. |
+| [Submitting Forms To RPC](./submitting-forms-to-rpc)   | A React form needs to call server-side code or a third-party API.                   |
+| [Custom Routes And URLs](./custom-routes-and-urls)     | A fixed URL should map to a view, or generated WordPress links need remapping.      |
+| [SVGs](./svgs)                                         | SVG uploads or raw SVG GraphQL fields are needed.                                   |
+
+If a pattern already has a focused docs page, this section should link to it instead of duplicating it. For example, reusable GraphQL fragments are covered in [GraphQL Fragments](/docs/graphql/fragments).

package/skills/eddev/docs/software.mdx

@@ -0,0 +1,19 @@
+# Software and Tooling (/docs/software)
+
+**Tools we use to build, edit, and run eddev projects.**
+
+## Local [#local]
+
+[Local](https://localwp.com/) is how we run WordPress locally on our machines, and connects with Flywheel/WP Engine — allowing us to push and pull entire websites to Staging and Production environments (database and all files).
+
+<Cards>
+  <Card title="How we use Local" href="/docs/infra/local">
+    Run WordPress locally and move site data between environments.
+  </Card>
+</Cards>
+
+## VSCode [#vscode]
+
+[VSCode](https://code.visualstudio.com/) is the industry-default code editor for web development, and you should use it when working on ED. projects.
+
+The starter theme includes a `.vscode/extensions.json` file with a list of recommended plugins — you should ensure these are installed.

package/skills/eddev/docs/stack/how-it-works.mdx

@@ -0,0 +1,50 @@
+# How It Works (/docs/stack/how-it-works)
+
+**Follow the end-to-end request flow for an eddev page.**
+
+Every eddev page starts with WordPress. Even when the public frontend runs on Vercel, WordPress decides which route has been requested and which view should render it.
+
+## Route Resolution [#route-resolution]
+
+For a normal page request, WordPress resolves the URL using its template hierarchy. Instead of ending at a PHP template, eddev can resolve that template to a React view such as `front-page`, `page`, `single`, `single-{post-type}`, `archive-{post-type}`, or `404`.
+
+After the view is known, the PHP runtime builds route data:
+
+1. It runs the paired view GraphQL file when one exists.
+2. It runs global app data when the request needs it.
+3. It adds the matched view name, admin context, metadata, and query debug information when available.
+4. It returns either JSON route data or an HTML response containing that route data.
+
+The JSON shape is the contract between WordPress and the React app. React does not independently decide what URL maps to what content.
+
+## SSR Request Flow [#ssr-request-flow]
+
+In the usual production setup, public traffic goes to Vercel and WordPress lives on the WP Engine origin.
+
+When Vercel receives a page request:
+
+1. The eddev serverless app asks WordPress for the matching route payload.
+2. WordPress resolves the route, runs the relevant GraphQL files, and returns the payload.
+3. The serverless app renders the active React view inside the app shell.
+4. The browser receives HTML with the page content already rendered.
+5. React hydrates the page so routing, blocks, query hooks, and interactive components can run in the browser.
+
+This keeps WordPress as the content and routing source of truth while giving the public site server-rendered HTML.
+
+## SPA Request Flow [#spa-request-flow]
+
+SPA mode is what happens when the browser accesses the WordPress origin directly, such as a Local site or a WP Engine origin frontend.
+
+In that mode, WordPress still resolves the same route and builds the same route payload. The difference is that the HTML response is an app shell with the route payload embedded for the browser. The browser loads the frontend bundle, reads the payload, loads the matching React view, and renders the page client-side.
+
+SPA mode is useful for origin previews and WordPress-hosted fallback behavior, but it is not the preferred public production path for current projects.
+
+## Client Navigation And Data [#client-navigation-and-data]
+
+After the first page load, eddev navigation fetches route payloads instead of full HTML pages.
+
+In serverless mode, browser navigation asks the JavaScript frontend for route data, and the serverless app fetches or caches the matching WordPress payload. In WordPress-hosted SPA mode, the browser asks WordPress for the route payload directly.
+
+Runtime GraphQL hooks use named data endpoints rather than exposing arbitrary GraphQL text from the browser. View, block, and app GraphQL files are part of route rendering; runtime query and mutation hooks are for browser-triggered data after the page is running.
+
+For the details behind each part of this flow, see [Views](/docs/views), [Routing](/docs/routing), [GraphQL](/docs/graphql), and [Serverless](/docs/serverless).

package/skills/eddev/docs/stack/overview.mdx

@@ -0,0 +1,56 @@
+# Overview (/docs/stack/overview)
+
+**Understand the main technologies and hosting shape behind eddev sites.**
+
+eddev is ED.'s WordPress + React/TypeScript stack for building content-managed websites. WordPress remains the CMS and routing authority, while the theme is mostly authored as React views, React blocks, GraphQL files, and TypeScript server routes.
+
+The usual production shape is a WordPress origin on WP Engine and a public server-rendered frontend on Vercel. Vercel renders the public site, but it still asks WordPress what each URL means and what data should be shown.
+
+## Core Pieces [#core-pieces]
+
+| Piece                 | Role In The Stack                                                                                                                              |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| WordPress and PHP     | Owns routing, admin, content editing, custom post types, ACF fields, REST endpoints, and the route payload generated for each request.         |
+| React and TypeScript  | Author the frontend views, blocks, app shell, interactive components, and project-specific server routes.                                      |
+| GraphQL and WPGraphQL | Select exactly what WordPress data is exposed to views, blocks, global app data, and runtime query hooks.                                      |
+| Composer              | Installs the PHP-side WordPress dependencies used by the theme, including WPGraphQL packages in the starter theme.                             |
+| eddev CLI             | Discovers views, blocks, routes, and GraphQL files, generates TypeScript outputs, runs local dev servers, and builds SPA or serverless output. |
+| Local                 | Runs the WordPress origin during local development.                                                                                            |
+| WP Engine             | Hosts the WordPress origin for staging and production.                                                                                         |
+| Vercel                | Hosts the public JavaScript frontend and serverless routes for normal production traffic.                                                      |
+
+## How The Pieces Fit [#how-the-pieces-fit]
+
+When someone visits a page, WordPress resolves the URL through the normal template hierarchy. eddev maps that result to a React view in `views/`, runs the paired GraphQL file if one exists, and builds a payload containing the matched view, view data, app data, metadata, and admin context.
+
+In SSR mode, the JavaScript server receives the public request, asks WordPress for that payload, renders the matching React view to HTML, and sends the hydrated page to the browser. In SPA mode, WordPress serves the app shell and page payload directly, then the browser renders the React view.
+
+Blocks follow the same split. WordPress and ACF own the editor data, block GraphQL files select the public props, and React block components render the frontend output.
+
+## Where To Go Next [#where-to-go-next]
+
+<Cards>
+  <Card title="How It Works" href="/docs/stack/how-it-works">
+    Follow the request and data flow from URL to rendered page.
+  </Card>
+
+  <Card title="SPA vs SSR" href="/docs/stack/spa-vs-ssr">
+    Compare WordPress-hosted SPA mode with serverless SSR mode.
+  </Card>
+
+  <Card title="Views" href="/docs/views">
+    Learn how WordPress templates map to React views.
+  </Card>
+
+  <Card title="GraphQL" href="/docs/graphql">
+    Learn where data queries live and what generated files they produce.
+  </Card>
+
+  <Card title="Serverless" href="/docs/serverless">
+    Set up the Vercel frontend in front of the WordPress origin.
+  </Card>
+
+  <Card title="eddev CLI" href="/docs/devtool/cli">
+    Run local development, builds, codegen, and diagnostics.
+  </Card>
+</Cards>

package/skills/eddev/docs/stack/spa-vs-ssr.mdx

@@ -0,0 +1,52 @@
+# SPA vs SSR (/docs/stack/spa-vs-ssr)
+
+**Compare WordPress-hosted SPA mode with serverless SSR mode.**
+
+eddev can render the same site in two modes. The route authority does not change: WordPress still decides what each URL means. The difference is where the React view is rendered for the first response.
+
+## Quick Comparison [#quick-comparison]
+
+| Topic                    | SPA Mode                                                                   | SSR Mode                                                             |
+| ------------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| First request handled by | WordPress origin, such as Local or WP Engine                               | JavaScript server, usually Vercel in production                      |
+| Initial HTML             | App shell plus embedded route data                                         | Server-rendered page HTML plus hydration data                        |
+| React rendering          | Browser renders the page after JavaScript loads                            | Server renders first, browser hydrates after load                    |
+| WordPress role           | CMS, admin, routing, GraphQL execution, route payloads                     | Same role: CMS, admin, routing, GraphQL execution, route payloads    |
+| Best use                 | Origin previews, fallback behavior, direct Local/WP Engine frontend checks | Normal public frontend and day-to-day local development              |
+| Production host          | WP Engine can serve it directly, but this is not the preferred public path | Vercel serves the public site while WP Engine remains the CMS origin |
+
+## Local Development [#local-development]
+
+When working locally with Local, the two modes usually appear as two nearby URLs:
+
+| URL                          | What You Are Seeing                                                         |
+| ---------------------------- | --------------------------------------------------------------------------- |
+| `https://my-site.local`      | The WordPress-hosted SPA frontend from Local.                               |
+| `https://my-site.local:8080` | The local eddev serverless dev server, using Local as the WordPress origin. |
+
+Use the `:8080` serverless dev URL for normal frontend work. It is closer to the Vercel production path and catches SSR-specific issues earlier.
+
+The direct `.local` URL is still useful when you need to inspect the WordPress origin, confirm the fallback SPA bundle, or work with admin/editor behavior that depends on WordPress-hosted assets.
+
+## Production Hosting [#production-hosting]
+
+The common production setup is:
+
+| Host                                         | Purpose                                                                                           |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| WP Engine origin, often on a `cms.` hostname | WordPress admin, content editing, route payloads, GraphQL, uploads, REST endpoints, and previews. |
+| Vercel public frontend                       | Server-rendered public pages, client navigation, serverless routes, and public domains.           |
+
+Vercel is not replacing WordPress routing. It renders the public response after asking WordPress what the route is and what data belongs to it.
+
+## Build Paths [#build-paths]
+
+SPA and SSR also have different build paths:
+
+| Build Path                 | Output                                                               |
+| -------------------------- | -------------------------------------------------------------------- |
+| `eddev build`              | WordPress-hosted frontend and admin bundles for SPA mode.            |
+| `eddev build --serverless` | Serverless output for SSR mode. Vercel uses this path automatically. |
+| `eddev dev --fast`         | Local GraphQL codegen plus the serverless dev server on port `8080`. |
+
+For command details, see [eddev CLI](/docs/devtool/cli). For deployment configuration, `SITE_URL`, `SITE_API_KEY`, and origin protection, see [Serverless](/docs/serverless).

package/skills/eddev/docs/views/app-view.mdx

@@ -0,0 +1,97 @@
+# _app.tsx Layout (/docs/views/app-view)
+
+**Common site layout**
+
+`views/_app.tsx` is the site shell. It wraps every active view, so it is the right place for global providers, headers, footers, scroll restoration, tracking systems, and route-level UI.
+
+```tsx filename="views/_app.tsx"
+import { Footer } from "@components/site/Footer"
+import { Header } from "@components/site/Header"
+import { ScrollRestoration } from "eddev/routing"
+import { defineView } from "eddev/views"
+
+export default defineView("_app", (props) => {
+  return (
+    <>
+      <ScrollRestoration />
+      <Header />
+      {props.children}
+      <Footer />
+    </>
+  )
+})
+```
+
+The `children` prop is the current route view. Do not query the current page in `_app.tsx`; that belongs in the view's own `.graphql` file.
+
+## App Data [#app-data]
+
+Add `views/_app.graphql` for data needed across the whole frontend, such as menus, settings, trackers, or template parts.
+
+```graphql filename="views/_app.graphql"
+query CommonData {
+  menus {
+    nodes {
+      locations
+      menuItems {
+        nodes {
+          label
+          url
+          parentId
+        }
+      }
+    }
+  }
+  templateParts {
+    siteFooter {
+      contentBlocks
+    }
+  }
+}
+```
+
+The result is available in `_app.tsx` as props, and also through `useAppData()` anywhere inside the app.
+
+```tsx filename="features/site/Footer.tsx"
+import { ContentBlocks } from "eddev/blocks"
+import { useAppData } from "eddev/hooks"
+
+export function Footer() {
+  const footer = useAppData((data) => data.templateParts?.siteFooter)
+
+  return <ContentBlocks blocks={footer?.contentBlocks} />
+}
+```
+
+On the initial page request, app data is included with the route payload. During normal client-side navigation it is reused, so avoid putting per-page data in `_app.graphql`.
+
+## Manual Route Display [#manual-route-display]
+
+Most projects only need `{props.children}`. More complex sites can render routes manually with `RouteDisplay` when they need page transitions, modal routes, drawers, or background routes.
+
+```tsx filename="views/_app.tsx"
+import { Footer } from "@components/site/Footer"
+import { Header } from "@components/site/Header"
+import { RouteDisplay, useRoute } from "eddev/routing"
+import { defineView } from "eddev/views"
+
+export default defineView("_app", () => {
+  const route = useRoute()
+
+  return (
+    <>
+      <Header />
+      <RouteDisplay route={route} />
+      <Footer />
+    </>
+  )
+})
+```
+
+Only reach for this when the shell needs control over how the active route is displayed. For normal site layouts, keep `_app.tsx` boring.
+
+## App Data Versus View Data [#app-data-versus-view-data]
+
+* Use `_app.graphql` for global data shared by many routes.
+* Use `views/name.graphql` for data needed by one view.
+* Use `queries/*.graphql` and generated hooks for interactive data that changes after the route has rendered.

package/skills/eddev/docs/views/page-templates.mdx

@@ -0,0 +1,82 @@
+# Page Templates (/docs/views/page-templates)
+
+**Selectable templates for pages and post types**
+
+Most views are chosen automatically by the WordPress template hierarchy. A page template is different: it is a selectable template shown in the WordPress editor.
+
+Use page templates for pages with a specific layout or purpose, such as a homepage, landing page, program page, or custom index page.
+
+## Define A Template [#define-a-template]
+
+Create a view and export `meta: ViewMeta` with `templateName`.
+
+```tsx filename="views/template-home.tsx"
+import { ContentBlocks } from "eddev/blocks"
+import { defineView } from "eddev/views"
+
+export const meta: ViewMeta = {
+  templateName: "Homepage",
+}
+
+export default defineView("template-home", (props) => {
+  return <ContentBlocks blocks={props.page?.contentBlocks} />
+})
+```
+
+Then pair it with a normal view query:
+
+```graphql filename="views/template-home.graphql"
+query Homepage($postId: ID!) {
+  page(id: $postId, idType: DATABASE_ID) {
+    contentBlocks
+  }
+}
+```
+
+The filename still matters. `views/template-home.tsx` should call `defineView("template-home", ...)`.
+
+## Naming [#naming]
+
+Prefer `template-*` for selectable page templates. It keeps them visually separate from WordPress hierarchy views like `page`, `single`, and `archive-case-study`.
+
+`front-page.tsx` is still useful when WordPress should choose the site front page automatically. Use `template-home.tsx` when authors need to pick a homepage-style template from the editor.
+
+## Post Types [#post-types]
+
+By default, a `templateName` view is available for pages. Set `postType` when the template should be selectable on another post type.
+
+```tsx filename="views/template-editorial.tsx"
+import { defineView } from "eddev/views"
+
+export const meta: ViewMeta = {
+  templateName: "Editorial",
+  postType: "article",
+}
+
+export default defineView("template-editorial", (props) => {
+  return <main>{props.article?.title}</main>
+})
+```
+
+Use an array when the same template applies to several post types:
+
+```ts
+export const meta: ViewMeta = {
+  templateName: "Landing Page",
+  postType: ["page", "campaign"],
+}
+```
+
+## View Metadata [#view-metadata]
+
+The public `ViewMeta` fields are intentionally small:
+
+* `templateName` - the label shown in the WordPress template dropdown
+* `postType` - the post type or post types where the template is available
+* `cache` - whether the view query can be cached
+
+Most templates only need `templateName`.
+
+## Custom Routes [#custom-routes]
+
+Page templates are selected on WordPress posts. If the URL does not represent a WordPress post, use a [custom route](/docs/routing/custom) that points to a view instead.