eddev 2.3.11-beta.8 → 2.3.13

package/skills/eddev/docs/graphql/query-hooks.mdx

@@ -0,0 +1,122 @@
+# Query Hooks (/docs/graphql/query-hooks)
+
+**Generate browser runtime query hooks from files in queries.**
+
+Query hooks are for data that should be fetched at runtime in the browser, such as search results, filters, live previews, and user-controlled lookups.
+
+They are generated from GraphQL query files in `queries/`. The generated hooks live in `hooks/queries.ts` and wrap TanStack Query.
+
+<Callout type="warning">
+  Query hooks are browser-side runtime fetches. They are not executed as part of the server-rendered route payload, unlike View, Block, and Global Data queries.
+
+  Once a query hook renders in the browser, it follows TanStack Query behavior and will run automatically unless you pass `enabled: false`.
+</Callout>
+
+## Naming Rules [#naming-rules]
+
+GraphQL query hook files have strict naming rules enforced by codegen:
+
+1. Files live under `queries/`, excluding `queries/fragments/`.
+2. The filename must start with `Use`.
+3. The GraphQL operation name must match the filename.
+4. Each file can contain only one operation.
+
+Subdirectories are fine. They affect the runtime query name, but not the hook name.
+
+```graphql filename="queries/posts/UsePostsSearch.graphql"
+query UsePostsSearch($q: String) {
+  posts(where: { search: $q }, first: 100) {
+    nodes {
+      title
+      uri
+    }
+  }
+}
+```
+
+This generates `usePostsSearch` in `hooks/queries.ts`.
+
+## Basic Usage [#basic-usage]
+
+```tsx
+import { Link } from "eddev/routing"
+import { useState } from "react"
+import { usePostsSearch } from "@hooks/queries"
+
+export function ExampleSearch() {
+  const [search, setSearch] = useState("")
+  const lookup = usePostsSearch(
+    { q: search },
+    { enabled: search.length >= 3 },
+  )
+
+  return (
+    <div>
+      <input type="search" value={search} onChange={(e) => setSearch(e.currentTarget.value)} />
+
+      {lookup.isLoading ? (
+        <p>Loading...</p>
+      ) : lookup.isError ? (
+        <p>{lookup.error.message}</p>
+      ) : lookup.data ? (
+        <ul>
+          {lookup.data.posts?.nodes?.map((node) => (
+            <li key={node.uri}>
+              <Link href={node.uri!}>{node.title}</Link>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+    </div>
+  )
+}
+```
+
+Use `enabled: false` or an expression like `enabled: search.length >= 3` when the query should wait for user input.
+
+## Hook API [#hook-api]
+
+Generated query hooks accept:
+
+1. Query variables, or `undefined` if the query has no variables.
+2. TanStack Query options, except `queryKey` and `queryFn`, which eddev manages.
+
+```ts
+const lookup = usePostsSearch(
+  { q: search },
+  {
+    enabled: search.length >= 3,
+    staleTime: 60_000,
+    refetchOnWindowFocus: false,
+  },
+)
+```
+
+The returned object is a TanStack `UseQueryResult`, including:
+
+```ts
+type QueryResult<T> = {
+  status: "pending" | "error" | "success"
+  isLoading: boolean
+  isSuccess: boolean
+  isError: boolean
+  error: QueryError | null
+  data: T | undefined
+  refetch: () => Promise<unknown>
+}
+```
+
+## Manual Fetching [#manual-fetching]
+
+Each generated query hook also has a static `.fetch()` method for rare non-hook usage.
+
+```ts
+import { usePostsSearch } from "@hooks/queries"
+
+async function loadPosts() {
+  const result = await usePostsSearch.fetch({ q: "festival" })
+  return result.posts?.nodes ?? []
+}
+```
+
+Prefer the hook in React components so loading, error, cache, and refetch states stay consistent.

package/skills/eddev/docs/graphql/tooling.mdx

@@ -0,0 +1,50 @@
+# GraphQL Tooling (/docs/graphql/tooling)
+
+**Use generated schema files with editor tooling and GraphiQL.**
+
+eddev generates enough local GraphQL metadata for editor tooling to understand
+the current WordPress schema and the project's `.graphql` files.
+
+## Generated Tooling Files [#generated-tooling-files]
+
+When `yarn dev` is running, eddev keeps the local GraphQL tooling files up to
+date:
+
+* `schema.json` is written by the TypeScript GraphQL codegen process.
+* `.graphqlrc.json` is written by the PHP dev bootstrap. It points tooling at
+  `schema.json`, the `/graphql` endpoint, and the fragment document glob.
+
+These files are development artifacts. They let your editor validate fields,
+variables, fragments, and operation names against the same schema used by the
+site.
+
+## VS Code [#vs-code]
+
+Install these extensions:
+
+* [GraphQL Language Feature Support](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql)
+* [GraphQL Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql-syntax)
+
+With the generated config in place, VS Code can autocomplete fields and report
+invalid selections directly in `.graphql` files.
+
+[GraphQL Inline Operation Execution](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql-execution)
+also works with the same config, but the built-in GraphiQL IDE is usually a
+better place to run exploratory queries.
+
+## GraphiQL IDE [#graphiql-ide]
+
+WPGraphQL includes a GraphiQL IDE in WordPress admin. Use it to inspect type
+names, test schema extensions, and build selections before moving them into
+project files.
+
+Fragments under `queries/fragments/**/*.graphql` are available to project query
+files without adding `#import` lines. In GraphiQL, paste the fragment definition
+alongside the query when you want to execute the same selection manually.
+
+<Callout type="info">
+  If editor autocomplete looks stale, restart `yarn dev` so eddev can regenerate
+  the schema and GraphQL config from the current WordPress environment.
+</Callout>
+
+<img alt="GraphQL IDE" src="__img0" />

package/skills/eddev/docs/graphql.mdx

@@ -0,0 +1,97 @@
+# Overview (/docs/graphql)
+
+**Working with GraphQL in eddev**
+
+eddev uses GraphQL as the data layer between WordPress and React. WPGraphQL exposes the schema, project `.graphql` files define exactly what data is public, and eddev generates TypeScript types and hooks from those files.
+
+Most of the time, you write GraphQL files rather than fetch data manually.
+
+## File Locations [#file-locations]
+
+| Location                         | What It Does                                                            |
+| -------------------------------- | ----------------------------------------------------------------------- |
+| `views/_app.graphql`             | Global app data, available through `_app.tsx` props and `useAppData()`  |
+| `views/*.graphql`                | Data for the paired view, passed as view props before the route renders |
+| `blocks/**/*.graphql`            | Data for the paired block, passed as block props                        |
+| `queries/fragments/**/*.graphql` | Reusable selections and generated fragment types                        |
+| `queries/**/*.graphql`           | Runtime query and mutation hooks generated into `hooks/queries.ts`      |
+
+<Cards>
+  <Card icon="<Lightbulb />" title="Global Data" href="/docs/graphql/global-data">
+    Fetch shared site shell data through `views/_app.graphql`.
+  </Card>
+
+  <Card icon="<Lightbulb />" title="View Data" href="/docs/views/queries">
+    Pair view templates with GraphQL files for route props.
+  </Card>
+
+  <Card icon="<Lightbulb />" title="Block Data" href="/docs/blocks/data-and-editing">
+    Select ACF and block fields before blocks render.
+  </Card>
+
+  <Card icon="<Lightbulb />" title="Fragments" href="/docs/graphql/fragments">
+    Reuse GraphQL selections and generated fragment types.
+  </Card>
+</Cards>
+
+## Generated Files [#generated-files]
+
+The dev process generates:
+
+* `types.graphql.ts` - operation, fragment, enum, scalar, and schema-derived TypeScript types
+* `types.views.ts` - the `ViewProps` map used by `defineView`
+* `types.blocks.ts` - the `BlockProps` map used by `defineBlock`
+* `types.util.ts` - helper global types such as post types, page templates, block tags, and post meta types
+* `hooks/queries.ts` - runtime query and mutation hooks for files under `queries/`
+* `schema.json` - the local schema file used by editor tooling
+
+These files are generated output. Do not edit them directly.
+
+## Automatic Versus Runtime Queries [#automatic-versus-runtime-queries]
+
+View, Block, and Global Data queries are executed as part of rendering route data. They are available before the relevant view or block renders.
+
+Runtime hooks from `queries/*.graphql` are different. They are browser-side runtime fetches, useful for search, filters, pagination, user-triggered data loading, and mutations. They are not part of the server-rendered route payload.
+
+<Cards>
+  <Card icon="<Lightbulb />" title="Query Hooks" href="/docs/graphql/query-hooks">
+    Fetch runtime browser data through generated TanStack Query hooks.
+  </Card>
+
+  <Card icon="<Lightbulb />" title="Infinite Queries" href="/docs/graphql/infinite-queries">
+    Build load-more interfaces on WPGraphQL cursor connections.
+  </Card>
+
+  <Card icon="<Lightbulb />" title="Mutation Hooks" href="/docs/graphql/mutation-hooks">
+    Call named runtime mutations through generated hooks.
+  </Card>
+</Cards>
+
+## Runtime Endpoints [#runtime-endpoints]
+
+Runtime hooks do not send arbitrary GraphQL text to the public `/graphql` endpoint. eddev exposes named REST endpoints instead:
+
+* `GET /wp-json/ed/v1/query/{queryName}?params={...}` for query hooks
+* `POST /wp-json/ed/v1/mutation/{mutationName}` for mutation hooks
+
+The `{queryName}` or `{mutationName}` maps to a file under `queries/`. For example, `queries/search/UseSearchResults.graphql` is requested by name as `search/UseSearchResults`.
+
+This keeps public runtime access limited to query files committed in the theme, while still using WPGraphQL internally.
+
+## Caching [#caching]
+
+View, app, and runtime query data use the cache settings from `ed.config.json`. Individual query files can override the cache duration with a leading comment:
+
+```graphql
+# ttl: 300
+query UseRecentPosts {
+  posts(first: 3) {
+    nodes {
+      title
+      uri
+    }
+  }
+}
+```
+
+Use `# nocache` when a query should never be cached.

package/skills/eddev/docs/guides/color-schemes.mdx

@@ -0,0 +1,204 @@
+# Colour Schemes (/docs/guides/color-schemes)
+
+**Define named visual schemes with Tailwind semantic tokens.**
+
+Use colour schemes when a section, card, page, or route needs to switch the
+same component between named visual themes. The Tailwind helper implements this
+with `subthemes`: a scheme class changes semantic CSS variables, while
+component code keeps using `bg-bg`, `text-fg`, `border-bg-low`, and similar
+semantic classes.
+
+## Define Schemes [#define-schemes]
+
+Define the possible scheme classes in `tailwind.config.ts`.
+
+```ts filename="tailwind.config.ts"
+responsiveTheme({
+  colors: {
+    base: {
+      black: "#202020",
+      white: "#ffffff",
+      silver: {
+        DEFAULT: "#d8d8d8",
+        light: "#f1f1f1",
+        dark: "#aaaaaa",
+      },
+      orange: "#ea5e42",
+      blue: "#2f99d4",
+      green: "#4a9f62",
+      card: "#dec99c",
+      yellow: "#f8d44f",
+    },
+    semantic: {
+      bg: "silver.light",
+      fg: "black",
+      "bg-low": "silver",
+    },
+    subthemes: {
+      "theme-black": {
+        bg: "black",
+        fg: "silver.light",
+        "bg-low": "silver.dark",
+      },
+      "theme-orange": {
+        bg: "orange",
+        fg: "black",
+        "bg-low": "white",
+      },
+      "theme-blue": {
+        bg: "blue",
+        fg: "black",
+        "bg-low": "white",
+      },
+      "theme-green": {
+        bg: "green",
+        fg: "black",
+        "bg-low": "white",
+      },
+      "theme-card": {
+        bg: "card",
+        fg: "black",
+        "bg-low": "white",
+      },
+      "theme-yellow": {
+        bg: "yellow",
+        fg: "black",
+        "bg-low": "white",
+      },
+    },
+  },
+})
+```
+
+The key is the class name. Use a `theme-*` prefix for scheme classes unless a
+project has already established different naming.
+
+## Apply A Scheme [#apply-a-scheme]
+
+Apply the class at the smallest useful boundary. A whole page can set a scheme:
+
+```tsx filename="views/single-case-study.tsx"
+import { pageColorClass } from "@features/brand/usePageColor"
+import { cn } from "@utils/tw"
+import { defineView } from "eddev/views"
+
+export default defineView("single-case-study", (props) => {
+  return (
+    <div className={cn(pageColorClass(props.caseStudy?.info?.pageColor))}>
+      <SubpageContentBlocks blocks={props.caseStudy?.contentBlocks} />
+    </div>
+  )
+})
+```
+
+A single block or card can set its own scheme:
+
+```tsx filename="components/Card.tsx"
+const SCHEME_CLASSES = {
+  black: "theme-black",
+  orange: "theme-orange",
+  blue: "theme-blue",
+} as const
+
+export function Card(props: {
+  color?: keyof typeof SCHEME_CLASSES
+  children: React.ReactNode
+}) {
+  return (
+    <article className={`${SCHEME_CLASSES[props.color ?? "black"]} bg-bg text-fg p-4 rounded-md`}>
+      {props.children}
+    </article>
+  )
+}
+```
+
+Use generated variants when a component needs to adjust itself based on an
+ancestor theme:
+
+```tsx
+<div className="bg-orange text-fg is-theme-black:theme-orange">
+  ...
+</div>
+```
+
+The helper creates `is-${themeName}:` variants for every configured subtheme.
+
+## Let Editors Choose [#let-editors-choose]
+
+For editor-controlled schemes, register a small enum field in PHP and select it
+in the block or view GraphQL file.
+
+```php filename="backend/fields/page-scheme.php"
+<?php
+
+ED()->registerEnumFieldType("page-scheme", [
+  "label" => "Page Scheme",
+  "type" => "select",
+  "allow_null" => 1,
+  "options" => [
+    "silver" => "Silver",
+    "green" => "Green",
+    "orange" => "Orange",
+    "blue" => "Blue",
+    "card" => "Card",
+    "yellow" => "Yellow",
+  ],
+]);
+```
+
+```graphql filename="blocks/pages/highlight-section.graphql"
+query {
+  block {
+    pages_highlight_section {
+      theme
+    }
+  }
+}
+```
+
+Map the generated enum values to classes in one helper:
+
+```tsx filename="features/brand/pageColor.ts"
+import { PageSchemeOption, SectionSchemeOption } from "@generated-types"
+
+const SCHEME_CLASSES: Record<PageSchemeOption, string> = {
+  silver: "theme-silver",
+  green: "theme-green",
+  orange: "theme-orange",
+  blue: "theme-blue",
+  card: "theme-card",
+  yellow: "theme-yellow",
+}
+
+export function pageColorClass(
+  color: PageSchemeOption | SectionSchemeOption | null | undefined,
+) {
+  return SCHEME_CLASSES[color || "silver"] || SCHEME_CLASSES.silver
+}
+```
+
+Keep the enum small. Most projects only need page-level schemes and a shorter
+section-level set for blocks.
+
+## Route-Level Themes [#route-level-themes]
+
+For route-driven themes, derive the current theme from `RouteState` and apply
+the scheme around `RouteDisplay`.
+
+```tsx filename="features/routes/ThemedRouteDisplay.tsx"
+import { RouteDisplay, RouteState } from "eddev/routing"
+
+export function ThemedRouteDisplay(props: { route: RouteState }) {
+  const dark = props.route.view === "template-home"
+
+  return (
+    <div className={dark ? "theme-dark bg-bg text-fg" : "theme-light bg-bg text-fg"}>
+      <RouteDisplay route={props.route} />
+    </div>
+  )
+}
+```
+
+Use route-level themes for global surfaces such as headers, drawers, page
+transitions, and footers. Use block fields for author-controlled content
+sections.

package/skills/eddev/docs/guides/integrations.mdx

@@ -0,0 +1,3 @@
+# Integrations (/docs/guides/integrations)
+
+**A placeholder for third-party integration guidance.**

package/skills/eddev/docs/guides/page-transitions.mdx

@@ -0,0 +1,5 @@
+# Page Transitions (/docs/guides/page-transitions)
+
+**A placeholder for page transition patterns in eddev sites.**
+
+TODO

package/skills/eddev/docs/guides/seo.mdx

@@ -0,0 +1,5 @@
+# SEO (/docs/guides/seo)
+
+**A placeholder for SEO patterns in eddev sites.**
+
+TODO

package/skills/eddev/docs/guides/state-management.mdx

@@ -0,0 +1,5 @@
+# State Management (/docs/guides/state-management)
+
+**A placeholder for state management guidance in eddev sites.**
+
+TODO

package/skills/eddev/docs/infra/caching.mdx

@@ -0,0 +1,9 @@
+# Caching (/docs/infra/caching)
+
+**A placeholder for eddev cache configuration and deployment layers.**
+
+TODO:
+
+* [ ] Cache configuration
+* [ ] Layers of caching
+* [ ] High-traffic sites

package/skills/eddev/docs/infra/deployment.mdx

@@ -0,0 +1,13 @@
+# Deployment (/docs/infra/deployment)
+
+**A placeholder for deployment workflows across GitHub, Vercel, and Cloudflare.**
+
+TODO: Overview of Github actions, Vercel, CloudFlare
+
+## Github Actions [#github-actions]
+
+TODO: Github actions info
+
+## Vercel [#vercel]
+
+TODO: Vercel deployment info for serverless

package/skills/eddev/docs/infra/local.mdx

@@ -0,0 +1,5 @@
+# Local (/docs/infra/local)
+
+**A placeholder for Local setup and push-pull workflow guidance.**
+
+TODO: Info on best practice for push/pull with Local

package/skills/eddev/docs/infra/security.mdx

@@ -0,0 +1,11 @@
+# Security (/docs/infra/security)
+
+**A placeholder for origin protection and secret management guidance.**
+
+## Preventing WordPress Access [#preventing-wordpress-access]
+
+TODO: Section on using `SITE_API_KEY` and password protection to prevent public access to the WordPress server.
+
+## Environment Variables [#environment-variables]
+
+TODO: Section on local + production secret management