eddev 2.3.12 → 2.3.14

package/skills/eddev/docs/blocks/block-definition.mdx

@@ -0,0 +1,189 @@
+# Defining a block (/docs/blocks/block-definition)
+
+**How to create a new block type**
+
+Block types are automatically registered when `.tsx` files are created in the `blocks` folder.
+
+Most block files have two exports: a `meta` object for Gutenberg/editor metadata, and a default export created with `defineBlock`.
+
+```tsx filename="blocks/content/hello-world.tsx"
+import { defineBlock } from "eddev/blocks"
+
+export const meta: BlockMeta = {
+  title: "Hello World",
+  icon: "welcome-write-blog",
+  tags: ["#root"],
+}
+
+export default defineBlock("content/hello-world", (props) => {
+  return <div>Hello!</div>
+})
+```
+
+## `defineBlock` [#defineblock]
+
+`defineBlock` returns the component you pass in, but its first argument matters for TypeScript. The name should match the file path under `blocks/`, without the extension.
+
+For `blocks/content/hello-world.tsx`, use:
+
+```tsx
+defineBlock("content/hello-world", (props) => {
+  return null
+})
+```
+
+That name connects the component to generated `BlockProps`, which are built from the paired GraphQL query in `types.blocks.ts`.
+
+## Block Meta [#block-meta]
+
+Exporting `meta`, typed with the global `BlockMeta` type, gives eddev enough information to register the block with ACF/Gutenberg and to expose lightweight metadata at runtime.
+
+### Everyday Fields [#everyday-fields]
+
+* `title: string{:ts}` — The title of this block, shown in the editor.
+* `description?: string{:ts}` — Short helper text shown in the editor.
+* `category?: "text" | "media" | "design" | "widgets" | "theme" | "embed" | "layouts"{:ts}` — The inserter category.
+* `icon?: BlockIcon{:ts}` — WordPress icon name for the inserter.
+* `keywords?: string[] | string{:ts}` — Extra search terms for authors.
+* `tags?: string[]{:ts}` — eddev placement tags such as `#root`, `#inline`, or a site-specific tag.
+* `flags?: Record<string, any>{:ts}` — Small runtime hints used by wrappers, spacing, or editor styling.
+* `conditions?: object{:ts}` — Limits availability by post type, template, parent, or ancestor.
+* `editMode?: "preview" | "edit" | "both"{:ts}` — Controls whether ACF fields show as sidebar-only, edit-only, or toggleable.
+* `blockStyles?: { name: string; label: string; isDefault?: boolean }[]{:ts}` — Gutenberg style variants for a block.
+
+### Conditions [#conditions]
+
+Use `conditions` when a block should only be available in specific places:
+
+```tsx filename="blocks/content/card-grid.tsx"
+export const meta: BlockMeta = {
+  title: "Card Grid",
+  icon: "grid-view",
+  tags: ["#subpage"],
+  conditions: {
+    postTypes: ["page"],
+    templates: ["default"],
+  },
+}
+```
+
+`postTypes` limits the block by WordPress post type. `templates` limits it by page template and implies the `page` post type. `parents` and `ancestors` are available for stricter nested-block constraints, but prefer `InnerBlocks allowedBlocks` for simple parent-child relationships.
+
+## Block Tags [#block-tags]
+
+Since different blocks have different contexts, and are sometimes specific to certain page templates, post types, or sections of a page — it can be helpful to give these contexts some kind of nickname. This is where tags come in. Note that this is not a WordPress thing, but rather something specific to the eddev stack.
+
+The tagging system accepts any string, but our convention is to prefix authoring-context tags with `#`. You may still see older unprefixed tags in existing projects.
+
+We typically use a couple of tags by default:
+
+* `#inline` for basic WYSIWYG blocks, like core headings/paragraphs/lists
+* `#root` for blocks that can be added at a top level for a page
+
+For a hypothetical content-heavy site, with homepages, landing pages, subpages, and a blog, you might have a set of tags like:
+
+* `#homepage-root` — blocks that can only be added to the homepage
+* `#landing-root` — full-bleed blocks that can be added the root of a landing page
+* `#subpage-root` — blocks that work within the subpage grid (eg, 9 cols on desktop, 12 cols on mobile)
+* `#article-root` — blocks that can be used on an article page
+
+We might also have additional tags for nested blocks, like a `#button` tag that can be attached to a 'Button Link' block, as well as an 'Add to Cart' button block.
+
+These tags will be referenced:
+
+* In the `allowedBlocks` prop of `InnerBlocks`
+* In the `rootBlocks` parameter when [configuring the editor](./editor-config) for a template or post type
+
+## Block Flags [#block-flags]
+
+*Flags* (not to be confused with *Tags*) allow you to set arbitrary key/values, which can be consumed by other parts of your frontend/editor code.
+
+You set flags by passing an object, with arbitrary key/values, like so:
+
+```ts
+export const meta: BlockMeta = {
+  title: "My Block",
+  flags: {
+    myFlag: true,
+    somethingElse: "green"
+  }
+}
+```
+
+Then, when using `InnerBlocks` or `ContentBlocks`, you can use the flags in `wrapBlock` and `spacer` props — or inside your editor config — to intelligently wrap, style or filter blocks based on these values, rather than by name.
+
+Use cases for this system:
+
+* Applying class names to the wrapper element in the editor
+* Deciding which blocks to wrap in animation components on the frontend, and which to exclude.
+* Deciding which blocks to wrap in layout classes in a page template
+
+Keep flags small. They are copied into the block payload that React receives.
+
+## Post Meta Blocks [#post-meta-blocks]
+
+Most ACF fields attached to a block are saved against that block instance. `postMetaBlock` changes that relationship: the fields attached to the block are also registered against a WordPress post type.
+
+This is useful for template-controlled blocks that represent the main metadata for a post, such as a film header, strand header, team member header, or product summary. It works best when the block is inserted by a template and hidden from the inserter, rather than added randomly by authors.
+
+```tsx filename="blocks/strand/strand-header.tsx"
+import { defineBlock, EditableText, usePostExcerptEditor, usePostTitleEditor } from "eddev/blocks"
+
+export const meta: BlockMeta = {
+  title: "Program Strand",
+  icon: "tag",
+  inserter: false,
+  postMetaBlock: {
+    postTypes: ["strand"],
+    fieldName: "info",
+  },
+}
+
+export default defineBlock("strand/strand-header", (props) => {
+  return (
+    <header>
+      <EditableText as="h1" store={usePostTitleEditor(props.strand?.title!)} />
+      <EditableText as="p" store={usePostExcerptEditor(props.strand?.excerpt!)} />
+      {props.category?.name && <p>{props.category.name}</p>}
+    </header>
+  )
+})
+```
+
+```graphql filename="blocks/strand/strand-header.graphql"
+query StrandHeader($postId: ID!) {
+  block {
+    strand_strand_header {
+      category {
+        name
+      }
+    }
+  }
+  strand(id: $postId, idType: DATABASE_ID) {
+    title
+    excerpt
+  }
+}
+```
+
+In this example, ACF fields assigned to `strand/strand-header` can be edited through the block, and are also made available on the `strand` post type under the `info` GraphQL field. eddev also limits the block to one instance per post and applies the configured post types.
+
+For this pattern, usually combine:
+
+* `postMetaBlock` to attach fields to the post type
+* `inserter: false` so authors do not add extra copies manually
+* an editor template, `headerTemplate`, or `template` so the block is always present
+
+## Advanced Fields [#advanced-fields]
+
+These are useful, but should not be the first thing you reach for:
+
+* `inserter: false{:ts}` hides blocks that are only inserted by templates or code.
+* `lazyLoad: false{:ts}` disables dynamic loading for blocks that are small or almost always visible.
+* `frontendMode: "hidden" | "childrenOnly" | "default"{:ts}` hides utility wrapper blocks or replaces them with their children on the frontend.
+* `templatePart` marks a block as a reusable [template part](./template-parts) such as a header, footer, or sidebar.
+* `cache` and `transforms` exist for specialized cases. Check the current `BlockMeta` type before using them.
+
+<Callout type="info">
+  Older projects may still use the legacy metadata format. New docs and new blocks should use `export const meta`.
+</Callout>

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

@@ -0,0 +1,86 @@
+# Core Blocks (/docs/blocks/core-blocks)
+
+**Working with WordPress core blocks in eddev**
+
+WordPress core blocks are blocks like paragraphs, headings, lists, embeds, and tables. eddev can render them as HTML, tag them for editor rules, or group them into synthetic blocks before React receives them.
+
+Keep core block behavior simple. Most sites only need to tag a small set of rich-text blocks and optionally provide React wrappers for their rendered HTML.
+
+## Rendering Core Blocks [#rendering-core-blocks]
+
+By default, WordPress can render core blocks into `innerHTML`. If a site needs custom React wrappers, add mappings in `blocks/_core.tsx`.
+
+```tsx filename="blocks/_core.tsx"
+import { ContentBlock } from "eddev/blocks"
+
+const HTMLParagraph = (props: ContentBlock) => {
+  if (!props.innerHTML) return null
+  return <div className="block-p" dangerouslySetInnerHTML={{ __html: props.innerHTML }} />
+}
+
+const HTMLList = (props: ContentBlock) => {
+  if (!props.innerHTML) return null
+  return <div className="block-list" dangerouslySetInnerHTML={{ __html: props.innerHTML }} />
+}
+
+export default {
+  "core/paragraph": HTMLParagraph,
+  "core/list": HTMLList,
+}
+```
+
+Use this when the frontend needs consistent wrappers, layout classes, or design-system typography around WordPress-rendered HTML.
+
+## Tagging Core Blocks [#tagging-core-blocks]
+
+Block tags can be used in `rootBlocks` and `InnerBlocks allowedBlocks`. Your own blocks get tags from `export const meta`; core blocks get tags from PHP.
+
+```php filename="backend/blocks.php"
+<?php
+
+ED()->tagCoreBlocks("#inline", [
+  "core/paragraph",
+  "core/list",
+  "core/heading",
+]);
+```
+
+After that, React code can allow all tagged core blocks with one entry:
+
+```tsx
+<InnerBlocks allowedBlocks={["#inline"]} />
+```
+
+Core blocks can have more than one tag, so it is fine to define broad tags like `#inline` and narrower layout tags for specific templates.
+
+## Grouping Core Blocks [#grouping-core-blocks]
+
+Some sites group consecutive core blocks into a synthetic block before React receives them.
+
+```php filename="backend/blocks.php"
+<?php
+
+ED()->groupCoreBlocks("core/rich-text", [
+  "core/heading",
+  "core/paragraph",
+  "core/list",
+  "core/table",
+]);
+```
+
+This converts adjacent matching core blocks into one block with `blockName: "core/rich-text"` and combined `innerHTML`. It is useful when the frontend wants one rich-text wrapper instead of separate heading, paragraph, list, and table blocks.
+
+If you group core blocks, add a matching `_core.tsx` renderer:
+
+```tsx filename="blocks/_core.tsx"
+import { ContentBlock } from "eddev/blocks"
+
+export default {
+  "core/rich-text": (props: ContentBlock) => {
+    if (!props.innerHTML) return null
+    return <div className="wysiwyg" dangerouslySetInnerHTML={{ __html: props.innerHTML }} />
+  },
+}
+```
+
+Only group core blocks when the layout benefits from it. If a site needs individual block-level spacing or wrappers, keep the blocks separate.

package/skills/eddev/docs/blocks/data-and-editing.mdx

@@ -0,0 +1,219 @@
+# Data and Editing (/docs/blocks/data-and-editing)
+
+**GraphQL props, inline content, and core block rendering**
+
+Blocks usually combine three kinds of data:
+
+* ACF or WordPress data selected by a paired GraphQL file
+* inline editor values stored directly on the block
+* nested content from `InnerBlocks`
+
+Use the smallest tool that fits. Inline text is usually better as `EditableText`. Structured data, relationships, media, or repeated fields are usually better as ACF fields selected through GraphQL.
+
+## Paired GraphQL Files [#paired-graphql-files]
+
+Place a `.graphql` file beside the block component when the block needs CMS data.
+
+```txt filename="blocks/content/image.graphql"
+query {
+  block {
+    content_image {
+      image {
+        ...ResponsiveImage
+      }
+    }
+  }
+}
+```
+
+For a block named `content/image`, eddev exposes its attached ACF fields under `block.content_image`. The field name is generated from the block path by camel-casing each path segment and joining them with an underscore.
+
+The query result becomes the component props:
+
+```tsx filename="blocks/content/image.tsx"
+import { defineBlock } from "eddev/blocks"
+
+export const meta: BlockMeta = {
+  title: "Image",
+  category: "media",
+  tags: ["#root"],
+}
+
+export default defineBlock("content/image", (props) => {
+  if (!props.image) return null
+  return <ResponsiveImage {...props.image} />
+})
+```
+
+Block queries can also fetch data that is not inside `block { ... }`. For example, a listing block can query posts directly, and a post-specific header block can use `$postId`.
+
+```graphql filename="blocks/team/team-listing.graphql"
+query {
+  teamMembers(first: 999) {
+    nodes {
+      title
+      uri
+    }
+  }
+}
+```
+
+```graphql filename="blocks/film/film-header.graphql"
+query FilmHeader($postId: ID!) {
+  film(id: $postId, idType: DATABASE_ID) {
+    title
+    uri
+  }
+}
+```
+
+## Querying Blocks From Views [#querying-blocks-from-views]
+
+Views select page blocks with `contentBlocks`.
+
+```graphql filename="views/page.graphql"
+query Page($postId: ID!) {
+  page(id: $postId, idType: DATABASE_ID) {
+    title
+    contentBlocks
+  }
+}
+```
+
+Then the view renders them with `ContentBlocks`.
+
+```tsx filename="views/page.tsx"
+import { ContentBlocks } from "eddev/blocks"
+import { defineView } from "eddev/views"
+
+export default defineView("page", (props) => {
+  return <ContentBlocks blocks={props.page?.contentBlocks} />
+})
+```
+
+`contentBlocks` also accepts a few useful filters:
+
+* `include` returns only matching block names, tags, flags, or wildcards.
+* `exclude` removes matching blocks.
+* `flattenExcluded` replaces excluded wrapper blocks with their children.
+* `maxDepth` limits nested block depth.
+* `limit` limits top-level blocks.
+
+This is useful when a view needs to render different subsets of the same page content in different layout regions:
+
+```graphql filename="views/page.graphql"
+query Page($postId: ID!) {
+  page(id: $postId, idType: DATABASE_ID) {
+    title
+    contentBlocks
+    introBlocks: contentBlocks(include: ["content/intro"], limit: 1)
+    bodyBlocks: contentBlocks(exclude: ["content/intro"], flattenExcluded: true)
+  }
+}
+```
+
+This keeps the data local to the page view. In React, you can render `introBlocks` and `bodyBlocks` in different layout regions without creating a separate runtime query.
+
+## Inline Editing [#inline-editing]
+
+Use `EditableText` for text authors should edit directly in the preview.
+
+```tsx
+import { defineBlock, EditableText } from "eddev/blocks"
+
+export default defineBlock("content/quote", () => {
+  return (
+    <figure>
+      <EditableText as="blockquote" store="quote" placeholder="Enter a quote" />
+      <EditableText as="figcaption" store="citation" placeholder="Citation" plainText />
+    </figure>
+  )
+})
+```
+
+The important props are:
+
+* `store` is required. Pass a string key like `"title"`, or a tuple from `useInlineEditableValue`, `usePostTitleEditor`, `usePostExcerptEditor`, `usePostMetaEditor`, or `useState`.
+* `as` changes the rendered element or component.
+* `placeholder` is editor-only helper text.
+* `defaultValue` is used on the frontend when no value has been entered. It also becomes the editor placeholder when `placeholder` is not provided.
+* `plainText` disables rich-text formatting for labels, buttons, and short UI copy.
+* `disableLineBreaks` prevents multiline editing.
+* `allowedFormats` limits rich-text formats. Use `allowedFormats={[]}` to disable formatting without using `plainText`.
+
+`appendOnEnter` and `removeOnDelete` are less common, but useful for text-like block flows. `appendOnEnter` inserts a new paragraph, or a specified block name, when the author presses Enter. `removeOnDelete` removes the current block when the author presses Backspace at the start of the text.
+
+## Inline Value Stores [#inline-value-stores]
+
+`useInlineEditableValue` reads and writes values in the current block's inline data. It behaves like a scoped `useState`.
+
+```ts
+function useInlineEditableValue<T>(
+  key: string,
+  defaultValue?: T,
+): [value: T | undefined, setValue: (value: T) => void]
+```
+
+When `defaultValue` is supplied, that value is returned until the author edits the field.
+
+Use it when the component needs the current value for rendering, attributes, tracking, conditional UI, or non-text controls.
+
+```tsx
+import { defineBlock, EditableText, useInlineEditableValue } from "eddev/blocks"
+
+export default defineBlock("content/cta-button", (props) => {
+  const [title] = useInlineEditableValue<string>("title")
+
+  return (
+    <div data-mixpanel-cta-title={title}>
+      <EditableText store="title" defaultValue={props.link?.title} placeholder="Enter a title" />
+    </div>
+  )
+})
+```
+
+You can also pass the tuple directly to `EditableText` so the editable field and the rest of the component share the same value.
+
+```tsx
+const titleStore = useInlineEditableValue("title", "Read more")
+const [title] = titleStore
+
+return (
+  <a aria-label={title}>
+    <EditableText store={titleStore} plainText disableLineBreaks />
+  </a>
+)
+```
+
+The value does not need to be consumed by `EditableText`. For example, an inspector setting can use the same store pattern for booleans or objects.
+
+```tsx
+import { InspectorControls, useInlineEditableValue } from "eddev/blocks"
+
+function DisplayOptions() {
+  const [shown, setShown] = useInlineEditableValue<Record<string, boolean>>("shown", {})
+
+  return (
+    <>
+      {env.admin && (
+        <InspectorControls>
+          <label>
+            <input
+              type="checkbox"
+              checked={shown.summary ?? true}
+              onChange={(event) => setShown({ ...shown, summary: event.currentTarget.checked })}
+            />
+            Show summary
+          </label>
+        </InspectorControls>
+      )}
+    </>
+  )
+}
+```
+
+`InspectorControls` is a good place for small per-block controls where ACF would be too heavy. Wrap it in `env.admin` so editor-only controls are not bundled for the frontend.
+
+## Core Blocks [#core-blocks]
+
+WordPress core blocks can be rendered as HTML, tagged for editor rules, or grouped into synthetic blocks. See [Core Blocks](./core-blocks) for those patterns.

package/skills/eddev/docs/blocks/editor-config.mdx

@@ -0,0 +1,157 @@
+# Configuring the Editor (/docs/blocks/editor-config)
+
+**Control which blocks authors can use**
+
+The editor config lives in `blocks/_editor.tsx`. It decides which blocks are available at the root of a post, which template blocks should be inserted automatically, and how block wrappers should be styled in the WordPress editor.
+
+```tsx filename="blocks/_editor.tsx"
+import { defineEditorConfig } from "eddev/blocks"
+
+export default defineEditorConfig({
+  matchers: [
+    {
+      match: (post) => post.type === "page" && post.template === "default",
+      config: {
+        rootBlocks: ["#root"],
+      },
+    },
+  ],
+})
+```
+
+Each matcher receives information about the current editor document. Return `true` from `match` when that config should apply.
+
+## Root Blocks [#root-blocks]
+
+`rootBlocks` controls which blocks can be added at the top level of the post content.
+
+```tsx
+export default defineEditorConfig({
+  matchers: [
+    {
+      match: (post) => post.type === "page" && post.template === "front-page",
+      config: {
+        rootBlocks: ["#homepage-root", "content/hero"],
+      },
+    },
+  ],
+})
+```
+
+Entries can be eddev block names, WordPress core block names, or block tags. The framework default is `["root"]`, but our docs and new examples use explicit `#` tags such as `["#root"]`. Core block tags are configured separately; see [Core Blocks](./core-blocks).
+
+## Templates [#templates]
+
+Templates let you insert blocks automatically.
+
+```tsx
+export default defineEditorConfig({
+  matchers: [
+    {
+      match: (post) => post.type === "case-study",
+      config: {
+        hideTitle: true,
+        rootBlocks: ["#root"],
+        headerTemplate: [["case-study/header", {}]],
+        defaultBlocks: [["core/paragraph", {}]],
+      },
+    },
+  ],
+})
+```
+
+* `defaultBlocks` are inserted when the post has no editable blocks.
+* `headerTemplate` keeps blocks at the top of the editor.
+* `footerTemplate` keeps blocks at the bottom of the editor.
+* `template` replaces the whole page with a locked block template.
+* `hideTitle` hides the standard WordPress title field when a block edits the title instead.
+
+Template entries use eddev block names like `page/page-header`, not ACF names like `acf/page-page-header`.
+
+Use `template` when the entire editing surface is fixed. Do not combine it with `headerTemplate` or `footerTemplate`.
+
+## Editor Wrapper Classes [#editor-wrapper-classes]
+
+Use `generateBlockClassName` to add classes around blocks in the WordPress editor. This does not change frontend markup.
+
+```tsx
+import { BlockWrapperClassGenerator, defineEditorConfig } from "eddev/blocks"
+
+const subpageClasses: BlockWrapperClassGenerator = (block) => {
+  if (!block.isRootBlock) return
+
+  if (block.flags?.sideRail) {
+    return "admin-subpage-siderail"
+  }
+
+  if (!block.flags?.fullWidth) {
+    return "col-subpage-content"
+  }
+}
+
+export default defineEditorConfig({
+  matchers: [
+    {
+      match: (post) => post.type === "page" && post.template === "default",
+      config: {
+        rootBlocks: ["#root", "#inline"],
+        generateBlockClassName: subpageClasses,
+      },
+    },
+  ],
+})
+```
+
+The `block` object includes the block name, slug, tags, flags, parent lookup, root status, and selection/move/remove state. Flags are often the most maintainable way to make layout decisions without checking a long list of block names.
+
+## Patterns And Template Parts [#patterns-and-template-parts]
+
+Matchers can also target reusable WordPress patterns and template parts:
+
+```tsx
+export default defineEditorConfig({
+  matchers: [
+    {
+      match: (post) => post.isPattern,
+      config: {
+        rootBlocks: ["#inline"],
+      },
+    },
+    {
+      match: (post) => post.isTemplatePart && post.slug === "site-header",
+      config: {
+        rootBlocks: ["parts/part-site-header"],
+      },
+    },
+  ],
+})
+```
+
+For most projects, keep this limited to shared headers, footers, menus, and content patterns. See [Template Parts](./template-parts) for the current `templatePart` block metadata pattern.
+
+## Custom Rich Text Formats [#custom-rich-text-formats]
+
+`customRichTextFormats` registers extra formatting buttons for `EditableText`.
+
+```tsx
+export default defineEditorConfig({
+  customRichTextFormats: [
+    {
+      id: "site/label",
+      title: "Label",
+      className: "type-label",
+      icon: "editor-textcolor",
+      tagName: "span",
+      disabledByDefault: true,
+    },
+  ],
+})
+```
+
+If `disabledByDefault` is true, enable the format on individual fields:
+
+```tsx
+<EditableText store="eyebrow" allowedFormats={["site/label"]} />
+```
+
+This is an advanced editor polish tool. Most block text should use the default formatting options, `plainText`, or `allowedFormats={[]}`.