eddev 2.3.12 → 2.3.13

package/skills/eddev/docs/blocks/nested-blocks.mdx

@@ -0,0 +1,129 @@
+# Nested Blocks (/docs/blocks/nested-blocks)
+
+**Blocks within blocks**
+
+Nested blocks let a block contain other blocks. Use them for layouts like sections, cards, accordions, button rows, reusable rich-text areas, and template-part slots.
+
+The `<InnerBlocks />` component is the child block container.
+
+```tsx filename="blocks/content/section.tsx"
+import { defineBlock, EditableText, InnerBlocks } from "eddev/blocks"
+
+export const meta: BlockMeta = {
+  title: "Section",
+  tags: ["#root"],
+}
+
+export default defineBlock("content/section", () => {
+  return (
+    <section className="grid-auto">
+      <EditableText as="h2" store="title" defaultValue="Enter a title" />
+      <InnerBlocks allowedBlocks={["#inline"]} />
+    </section>
+  )
+})
+```
+
+You can only have one `InnerBlocks` in a block. This is a WordPress/Gutenberg limitation. If a block needs multiple editable zones, see `SlotBlocks` below.
+
+## Allowed Blocks [#allowed-blocks]
+
+Use `allowedBlocks` to control what can be inserted inside the container.
+
+```tsx
+<InnerBlocks allowedBlocks={["core/paragraph", "core/list", "content/button-row"]} />
+```
+
+Entries can be specific block names or tags. Tags are usually cleaner when several blocks should be allowed in the same context.
+
+```tsx filename="blocks/content/button-row.tsx"
+export const meta: BlockMeta = {
+  title: "Button Row",
+  tags: ["#inline"],
+}
+
+export default defineBlock("content/button-row", () => {
+  return <InnerBlocks allowedBlocks={["#buttons"]} />
+})
+```
+
+```tsx filename="blocks/content/button.tsx"
+export const meta: BlockMeta = {
+  title: "Button",
+  tags: ["#buttons"],
+}
+```
+
+WordPress core blocks can also be tagged and allowed this way. See [Core Blocks](./core-blocks) for the PHP-side setup.
+
+The unprefixed `root` tag is the framework default, but our examples use explicit `#root` and set `rootBlocks` in `blocks/_editor.tsx`.
+
+## Templates And Locking [#templates-and-locking]
+
+`InnerBlocks` can insert default child blocks and control how much authors can change the list.
+
+```tsx
+<InnerBlocks
+  allowedBlocks={["content/card-grid-item"]}
+  defaultBlocks={[["content/card-grid-item", {}]]}
+  templateLock="insert"
+/>
+```
+
+* `defaultBlocks` are inserted when the container is empty.
+* `headerTemplate` and `footerTemplate` keep blocks pinned to the start or end.
+* `template` defines the whole child block list.
+* `templateLock="all"` prevents moving, inserting, or deleting.
+* `templateLock="insert"` prevents inserting or removing, but allows moving existing blocks.
+* `templateLock="contentOnly"` locks structure but allows rich text editing.
+* `templateLock="none"` or `false` leaves the list editable.
+
+Use these sparingly. A good rule is to lock structural wrapper blocks, but keep content blocks flexible.
+
+## Appenders And Editor Classes [#appenders-and-editor-classes]
+
+`adminClassName` adds a class to the editor-only wrapper. `appender` changes the inserter UI.
+
+```tsx
+<InnerBlocks
+  allowedBlocks={["content/card-grid-item"]}
+  adminClassName="grid grid-cols-3 gap-4"
+  appender={{ type: "simple" }}
+/>
+```
+
+Supported appender types are `default`, `button`, `button2`, `simple`, or a custom appender created with `createAppender`.
+
+## Rendering Children Yourself [#rendering-children-yourself]
+
+Most blocks can render `<InnerBlocks />` directly. If the parent needs to inspect child blocks, use `useInnerBlocks()`.
+
+```tsx
+import { defineBlock, InnerBlocks, useInnerBlocks } from "eddev/blocks"
+
+export default defineBlock("content/card-grid", () => {
+  const blocks = useInnerBlocks()
+  const columns = blocks.length === 3 ? "grid-cols-3" : "grid-cols-2"
+
+  return (
+    <div className={columns}>
+      <InnerBlocks allowedBlocks={["content/card-grid-item"]} />
+    </div>
+  )
+})
+```
+
+`useInnerBlocks()` returns block data with metadata added, including `slug`, `tags`, and `flags`.
+
+## Multiple Editable Zones [#multiple-editable-zones]
+
+Use `SlotBlocks` only when a block genuinely needs multiple independent editable zones.
+
+```tsx
+import { SlotBlocks } from "eddev/blocks"
+
+<SlotBlocks id="primary" allowedBlocks={["#menu"]} />
+<SlotBlocks id="cta" template={[["content/button", {}]]} templateLock="insert" />
+```
+
+`SlotBlocks` stores hidden `core/slot-group` blocks inside the parent and renders each slot separately. It is useful for complex headers, mega menus, or app-like layouts, but it is more complex than a normal `InnerBlocks` container.

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

@@ -0,0 +1,58 @@
+# Overview (/docs/blocks/overview)
+
+**The basics of creating Gutenberg blocks**
+
+Blocks are the main editing unit for page content. In an eddev theme, a block is usually a React component in `blocks/**/*.tsx`, with optional metadata and a paired GraphQL query.
+
+Most sites only need a small set of block conventions:
+
+* `blocks/content/section.tsx` defines a block component.
+* `blocks/content/section.graphql` selects the ACF or WordPress data passed to that component.
+* `blocks/_editor.tsx` controls which blocks authors can add for each post type or template.
+* `blocks/_core.tsx` optionally replaces the frontend rendering of WordPress core blocks.
+* Views render block content with `<ContentBlocks blocks={props.page?.contentBlocks} />`.
+
+## The Short Version [#the-short-version]
+
+```tsx filename="blocks/content/section.tsx"
+import { defineBlock, EditableText, InnerBlocks } from "eddev/blocks"
+
+export const meta: BlockMeta = {
+  title: "Section",
+  tags: ["#root"],
+}
+
+export default defineBlock("content/section", () => {
+  return (
+    <section className="grid-auto">
+      <div className="col-span-12 md:col-span-3">
+        <EditableText as="h2" store="title" defaultValue="Enter a title" />
+      </div>
+      <div className="col-span-12 md:col-span-9">
+        <InnerBlocks allowedBlocks={["#inline"]} />
+      </div>
+    </section>
+  )
+})
+```
+
+`defineBlock("content/section", ...)` should match the file path without `blocks/` or `.tsx`. This is what lets generated block props line up with the right component.
+
+## Data Flow [#data-flow]
+
+Block data is not passed straight from ACF into React. eddev parses Gutenberg content in WordPress, runs the matching `blocks/**/*.graphql` query for each ACF block, and sends the selected data to React as typed props.
+
+That extra query step is useful: a block can select exactly the fields it needs, follow relationships like post objects or media fields, and reuse fragments from `queries/fragments`.
+
+## Editor Flow [#editor-flow]
+
+The editor is configured separately from individual blocks. Use block `tags` for broad authoring contexts like `#root`, `#inline`, or `#card-grid-item`, then use `blocks/_editor.tsx` to decide which tags or block names are available for a given post type or template.
+
+Keep the first pass simple:
+
+* define the block component
+* add ACF fields only when inline editing is not enough
+* add a GraphQL file only for data the component needs
+* constrain where it appears with tags and editor config
+
+The rest of this section covers those pieces in that order.

package/skills/eddev/docs/blocks/template-parts.mdx

@@ -0,0 +1,131 @@
+# Template Parts (/docs/blocks/template-parts)
+
+**Reusable site sections powered by blocks**
+
+Template parts are reusable block-backed sections of a theme, such as a site footer, site header, menu, or global callout. They are edited in WordPress, queried as app data, and rendered anywhere in React with `ContentBlocks`.
+
+Use template parts for content that belongs to the site shell rather than one page.
+
+## Define A Template Part Block [#define-a-template-part-block]
+
+Set `templatePart` on the block metadata.
+
+```tsx filename="blocks/parts/footer.tsx"
+import { defineBlock, EditableText } from "eddev/blocks"
+import { Link } from "eddev/routing"
+
+export const meta: BlockMeta = {
+  title: "Site Footer",
+  inserter: false,
+  templatePart: {
+    area: "footer",
+    slug: "siteFooter",
+  },
+}
+
+export default defineBlock("parts/footer", (props) => {
+  return (
+    <footer>
+      <Link href={props.contactLink ?? "/contact"}>
+        <EditableText store="contactLink" defaultValue="Let's have a chat" />
+      </Link>
+    </footer>
+  )
+})
+```
+
+`slug` becomes the field name under `templateParts` in GraphQL. `area` tells WordPress what kind of template part this is. `inserter: false` is usually right, because authors should edit the template part itself rather than adding this block manually to pages.
+
+## Add A Block Query [#add-a-block-query]
+
+Template part blocks can have their own paired GraphQL files, just like normal blocks.
+
+```graphql filename="blocks/parts/footer.graphql"
+query {
+  block {
+    parts_footer {
+      contactLink
+    }
+  }
+}
+```
+
+## Query The Template Part [#query-the-template-part]
+
+Template parts can be queried anywhere a normal GraphQL file can select `templateParts`.
+
+For site shell content, select the template part from app data so it is available around every route:
+
+```graphql filename="views/_app.graphql"
+query CommonData {
+  templateParts {
+    siteFooter {
+      contentBlocks
+    }
+  }
+}
+```
+
+Then render it with `ContentBlocks`.
+
+```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} />
+}
+```
+
+Finally, include the component in `_app.tsx` so it appears around every route.
+
+```tsx filename="views/_app.tsx"
+import { Footer } from "@features/site/Footer"
+import { RouteDisplay, useRoute } from "eddev/routing"
+import { defineView } from "eddev/views"
+
+export default defineView("_app", () => {
+  const route = useRoute()
+
+  return (
+    <>
+      <RouteDisplay route={route} />
+      <Footer />
+    </>
+  )
+})
+```
+
+You do not have to use `_app.graphql` or `useAppData`. Blocks and views can query template parts directly when they need globally-defined content in a specific place.
+
+```graphql filename="blocks/content/callout.graphql"
+query CalloutBlock {
+  block {
+    content_callout {
+      heading
+    }
+  }
+  templateParts {
+    siteFooter {
+      contentBlocks
+    }
+  }
+}
+```
+
+That pattern is useful for callouts, reusable panels, or other blocks that need shared content without making it global app data.
+
+eddev automatically constrains the matching template-part editor to the block declared in `templatePart`, so the editing surface stays focused.
+
+## When To Use This [#when-to-use-this]
+
+Template parts are a good fit for:
+
+* site headers and footers
+* global navigation or mega menus
+* reusable site-wide panels
+* shared error page content
+* content that should be edited once and rendered on many routes
+
+Do not use template parts for ordinary per-page blocks. If content belongs to a page or post, keep it in that page or post's `contentBlocks`.

package/skills/eddev/docs/config.mdx

@@ -0,0 +1,200 @@
+# Configuration (/docs/config)
+
+**Configure eddev projects with theme-level JSON settings.**
+
+eddev projects are configured with `ed.config.json` in the theme root. The file is read by the JavaScript build/server process and, for some options, by the WordPress PHP runtime.
+
+The generated `.ed.config.schema.json` file gives editor autocomplete and validation. It is generated from the Zod schema in eddev, so treat that schema as the source of truth when an option changes.
+
+```json filename="ed.config.json"
+{
+  "$schema": ".ed.config.schema.json",
+  "version": "2",
+  "legacyStitches": false,
+  "favicon": {
+    "mode": "svg"
+  },
+  "serverless": {
+    "enabled": true,
+    "uploads": "remote",
+    "plugins": "remote",
+    "admin": "hide",
+    "themeAssets": ["assets/**/*"],
+    "originProtection": {
+      "requireLogin": false
+    },
+    "endpoints": {
+      "cms.website.com": "website.com"
+    }
+  },
+  "cache": {
+    "*": {
+      "pageDataTTL": 300,
+      "appDataTTL": 300,
+      "queryHooksTTL": 300,
+      "serverless": {
+        "isr": true,
+        "dataCache": "in-memory"
+      },
+      "wordpress": {
+        "cacheHeaders": true,
+        "transients": true
+      }
+    }
+  },
+  "devUI": "enabled"
+}
+```
+
+<Callout type="info">
+  Keep `cache` and `serverless.endpoints` explicit on production projects. The JavaScript side applies schema defaults, but the WordPress PHP side also reads parts of the raw JSON file.
+</Callout>
+
+## Where To Go Next [#where-to-go-next]
+
+<Cards>
+  <Card icon="<CogIcon />" title="Serverless" href="/docs/serverless">
+    Configure the JavaScript host that renders the public frontend.
+  </Card>
+
+  <Card icon="<CogIcon />" title="RPC Functions" href="/docs/serverless/functions">
+    Add TypeScript server routes for project-specific APIs.
+  </Card>
+
+  <Card icon="<CogIcon />" title="Favicons" href="/docs/design/favicons">
+    Choose how eddev prepares favicon files for the theme.
+  </Card>
+
+  <Card icon="<CogIcon />" title="GraphQL Caching" href="/docs/graphql#caching">
+    Tune cache behavior for view, app, and runtime query data.
+  </Card>
+</Cards>
+
+## Top-Level Options [#top-level-options]
+
+| Option           | What It Does                                                                                                                                                   |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `$schema`        | Points editors at `.ed.config.schema.json` for autocomplete and validation.                                                                                    |
+| `version`        | Config format version. Current projects should use `"2"`.                                                                                                      |
+| `favicon`        | Controls favicon generation. See [Favicons](/docs/design/favicons).                                                                                            |
+| `legacyMetadata` | Enables older comment-based metadata parsing for projects that still need it. New projects should use exported metadata.                                       |
+| `legacyStitches` | Marks the project as using the old Stitches styling setup. New projects should leave this as `false`.                                                          |
+| `trackers`       | Adds standard tracking snippets such as GA4 or GTM.                                                                                                            |
+| `serverless`     | Controls serverless deployment, proxied assets, admin URL behavior, endpoint mappings, CORS, and CSP. See [Serverless](/docs/serverless).                      |
+| `cache`          | Controls WordPress and serverless data/response caching. See [Serverless cache settings](/docs/serverless#cache) and [GraphQL caching](/docs/graphql#caching). |
+| `devUI`          | Enables or disables the eddev development UI. Use `"enabled"` for normal development.                                                                          |
+
+## `favicon` [#favicon]
+
+`favicon` controls how eddev prepares favicon assets during the build.
+
+| Mode   | Use When                                                                              |
+| ------ | ------------------------------------------------------------------------------------- |
+| `auto` | WordPress Site Icon should handle favicons. No `.ico` is generated by eddev.          |
+| `svg`  | The project has a single SVG favicon source, optionally with light and dark variants. |
+| `pngs` | The project has multiple PNG favicon source files.                                    |
+
+The favicon page should carry the asset naming and export details once it is filled out: [Favicons](/docs/design/favicons).
+
+## `serverless` [#serverless]
+
+Most current projects deploy the public frontend to Vercel and keep WordPress as the CMS and route authority. `serverless` controls that deployment shape.
+
+| Option                          | What It Does                                                                                           |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `enabled`                       | Enables serverless deployment support.                                                                 |
+| `uploads`                       | Chooses whether upload URLs are remote origin URLs or proxied through the serverless deployment.       |
+| `plugins`                       | Chooses whether plugin asset URLs are remote origin URLs or proxied through the serverless deployment. |
+| `admin`                         | Controls whether WordPress admin/API URLs are proxied or hidden on the serverless deployment.          |
+| `originProtection.requireLogin` | Forces eddev Access Control for the WordPress origin.                                                  |
+| `themeAssets`                   | Lists theme asset folders to include in the serverless deployment.                                     |
+| `endpoints`                     | Maps WordPress hostnames to serverless hostnames for RPC and SPA/admin calls.                          |
+| `cors.origins`                  | Adds extra CORS origins beyond hosts inferred from `endpoints`.                                        |
+| `csp`                           | Configures Content Security Policy for the serverless app.                                             |
+
+Use the serverless overview for deployment flow, `SITE_URL`, `SITE_API_KEY`, Access Control, endpoint mappings, and cache behavior: [Serverless](/docs/serverless).
+
+## `cache` [#cache]
+
+`cache` is a map of WordPress origin hostnames to cache settings. Use `"*"` as the default, and add exact or wildcard host entries when staging and production need different behavior.
+
+```json filename="ed.config.json"
+{
+  "cache": {
+    "*.staging.website.com": {
+      "pageDataTTL": 60,
+      "appDataTTL": 60,
+      "queryHooksTTL": 60,
+      "serverless": {
+        "isr": false,
+        "dataCache": "none"
+      },
+      "wordpress": {
+        "cacheHeaders": false,
+        "transients": false
+      }
+    },
+    "*": {
+      "pageDataTTL": 300,
+      "appDataTTL": 300,
+      "queryHooksTTL": 300,
+      "serverless": {
+        "isr": true,
+        "dataCache": "in-memory"
+      },
+      "wordpress": {
+        "cacheHeaders": true,
+        "transients": true
+      }
+    }
+  }
+}
+```
+
+Cache host keys are matched as hostnames. Ports are ignored, exact hostnames win over wildcard patterns, and `"*"` is the fallback.
+
+| Option                   | What It Does                                                                             |
+| ------------------------ | ---------------------------------------------------------------------------------------- |
+| `pageDataTTL`            | Seconds to cache route data and rendered page responses.                                 |
+| `appDataTTL`             | Seconds to cache global app data from `views/_app.graphql`.                              |
+| `queryHooksTTL`          | Seconds to cache named runtime GraphQL query hook responses.                             |
+| `serverless.isr`         | Enables serverless response caching/ISR for pages and data routes.                       |
+| `serverless.dataCache`   | `in-memory` uses the serverless LRU/SWR data cache. `none` fetches WordPress every time. |
+| `wordpress.cacheHeaders` | Allows WordPress data responses to emit cache headers.                                   |
+| `wordpress.transients`   | Allows WordPress to cache GraphQL results in transients.                                 |
+
+Individual GraphQL files can still override the duration with `# ttl: 300` or disable caching with `# nocache`; see [GraphQL caching](/docs/graphql#caching).
+
+## `trackers` [#trackers]
+
+`trackers` embeds standard tracking snippets collected by eddev.
+
+```json filename="ed.config.json"
+{
+  "trackers": [
+    {
+      "provider": "ga4",
+      "id": "G-XXXXXXXXXX"
+    },
+    {
+      "provider": "gtm",
+      "id": "GTM-XXXXXXX"
+    }
+  ]
+}
+```
+
+Supported providers are `ga4` and `gtm`. Serverless CSP can auto-detect common tracker origins when CSP is enabled.
+
+<Callout>
+  If you've got Slim SEO installed, you can just put them in Settings -> Slim SEO -> Code.
+</Callout>
+
+## Legacy Flags [#legacy-flags]
+
+`legacyMetadata` and `legacyStitches` are compatibility switches for older projects. Leave them off unless the project already depends on those older conventions.
+
+* `legacyMetadata` keeps support for older metadata extraction.
+* `legacyStitches` marks the site as using the old Stitches styling path.
+
+New projects should use exported block/view metadata and the current CSS/Tailwind setup.