eddev 2.3.11-beta.8 → 2.3.13

package/skills/eddev/docs/getting-started.mdx

@@ -0,0 +1,53 @@
+# Getting Started (/docs/getting-started)
+
+**Set up a new eddev project from the starter theme.**
+
+## Initial Setup [#initial-setup]
+
+All new sites should use the following process when setting up a new site:
+
+1. [Create a new repo on Github](https://github.com/new)
+   1. Set `Owner` to `ed-digital`, and name your repo like `some-client-name`.
+   2. Set `Repository Template` to `ed-digital/eddev-starter-theme`
+   3. Hit `Create repository`
+2. Create a new site in [Local](/docs/infra/local), on your computer.
+   1. Use the default settings
+   2. Be sure to use `ed_admin` as the username, and generate a secure password using 1Password or similar, and the email address should be `web@ed.com.au`
+   3. Save the username and password to 1Pass.
+3. Install the following plugins:
+   1. Advanced Custom Fields Pro ([download](https://www.advancedcustomfields.com/my-account/view-licenses/)) (login details in 1Password)
+   2. Add the licence key as the key for ACF Pro under 'Custom Fields > Updates'. The licence key is also in 1Password for convenience.
+   3. Slim SEO — install from plugins dashboard
+   4. Nested Pages — install from plugins dashboard
+4. Under Settings -> General, set Timezone to Sydney (or the appropriate timezone).
+5. Make sure that all the installed plugins have been activated.
+6. Clone your newly created theme to `wp-content/themes/`, making sure that the repo name and the theme folder name are identical.
+7. Run the following commands inside the theme folder
+   1. `composer update`
+   2. `yarn`
+   3. `yarn add --dev eddev@latest`
+   4. `yarn setup`
+8. Activate the theme under Appearance > Themes
+9. Run `yarn dev`
+10. Add, Commit and Push all code changes back to Github.
+
+## Initial WP Engine Setup [#initial-wp-engine-setup]
+
+After you've followed the steps above, and the site is running correctly locally, you can create a site on WP Engine:
+
+1. [Log into WP Engine](https://my.wpengine.com/sites)
+2. Navigate through **Add Site → Build a new site → Get Started**
+3. Ensure 'ED.' is selected under the account picker.
+4. Select 'I will own it'
+5. Once complete, restart Local, run `yarn build` once, and do an initial push to the new site, with all files and the database.
+
+## Initial Vercel Setup [#initial-vercel-setup]
+
+Once the WP Engine site is up and running, you can create the Vercel project:
+
+1. Log into [Vercel](https://vercel.com/)
+2. On the 'Overview' tab, navigate to **Add New\... → Project**
+3. Select our team from the dropdown, and choose the site repo, then hit 'Import'.
+4. Ensure the project name looks nice
+5. Add an Environment Variable with `Key: SITE_URL`, `Value: https://{staging-site-url}`
+6. Hit `Deploy`

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

@@ -0,0 +1,186 @@
+# Extending the GraphQL Schema (/docs/graphql/extending)
+
+**Extend WPGraphQL when frontend data needs custom schema fields.**
+
+Most projects only need fields that come from WordPress, ACF, registered post
+types, and blocks. When the frontend needs a value that does not naturally exist
+in the schema, extend WPGraphQL in the WordPress theme or plugin code.
+
+Use the GraphiQL IDE while writing schema extensions. It is the quickest way to
+check the type names you are extending, the fields you have registered, and the
+shape returned by your resolver.
+
+## Add A Field [#add-a-field]
+
+Use `register_graphql_field` when you need to add a computed field to an
+existing schema type.
+
+```php
+add_action('graphql_register_types', function () {
+  register_graphql_field('Film', 'totalSessions', [
+    'type' => 'Int',
+    'description' => 'The number of sessions for this film.',
+    'resolve' => function ($root) {
+      $sessions = get_post_meta($root->ID, 'total_sessions', true);
+      return $sessions ? (int)$sessions : null;
+    },
+  ]);
+});
+```
+
+The resolver receives the current GraphQL root object first. For post types this
+usually gives you access to `$root->ID`, which can be used with `get_post_meta`,
+ACF, or project model helpers.
+
+## Return Posts [#return-posts]
+
+When a resolver returns a WordPress post and you want GraphQL subfields to keep
+working, wrap the post in `WPGraphQL\Model\Post`.
+
+```php
+add_action('graphql_register_types', function () {
+  register_graphql_field('RootQuery', 'currentProgram', [
+    'type' => 'Program',
+    'resolve' => function () {
+      $program = get_field('current_program', 'option');
+
+      if ($program) {
+        return new WPGraphQL\Model\Post($program);
+      }
+
+      return null;
+    },
+  ]);
+});
+```
+
+The same applies to lists of posts:
+
+```php
+register_graphql_field('Film', 'guests', [
+  'type' => ['list_of' => 'Guest'],
+  'resolve' => function ($root) {
+    $guests = Film::fromPost($root->ID)->getGuests();
+
+    return array_map(function ($id) {
+      return new WPGraphQL\Model\Post(get_post($id));
+    }, $guests);
+  },
+]);
+```
+
+## Add A Root Query [#add-a-root-query]
+
+Root fields are useful when the frontend needs a named project-level entry
+point, such as the current programme, search results, or a custom data system.
+
+```php
+add_action('graphql_register_types', function () {
+  register_graphql_field('RootQuery', 'siteSearch', [
+    'type' => ['list_of' => 'ContentNode'],
+    'args' => [
+      'search' => ['type' => 'String'],
+    ],
+    'resolve' => function ($root, $args) {
+      $query = new WP_Query([
+        's' => $args['search'] ?? '',
+        'post_type' => ['page', 'post'],
+      ]);
+
+      return array_map(function ($post) {
+        return new WPGraphQL\Model\Post($post);
+      }, $query->posts);
+    },
+  ]);
+});
+```
+
+Keep root fields narrow and intentional. If a field starts to behave like a
+feature API, consider whether it should be a query hook, a serverless function,
+or a dedicated WordPress endpoint instead.
+
+## Add Object Types [#add-object-types]
+
+Use `register_graphql_object_type` when the field returns structured data that
+does not already have a GraphQL type.
+
+```php
+class FilmAssetProgram {
+  public function __construct(public WP_Post $program) {}
+
+  static function registerType() {
+    register_graphql_object_type('FilmAssetProgram', [
+      'fields' => [
+        'program' => [
+          'type' => 'Program',
+          'resolve' => function (FilmAssetProgram $program) {
+            return new WPGraphQL\Model\Post($program->program);
+          },
+        ],
+        'buckets' => [
+          'type' => ['list_of' => 'FilmAssetBucket'],
+          'resolve' => function (FilmAssetProgram $program) {
+            return $program->getBuckets();
+          },
+        ],
+      ],
+    ]);
+  }
+}
+```
+
+Then return that object type from a field:
+
+```php
+add_action('graphql_register_types', function () {
+  FilmAssetProgram::registerType();
+  FilmAssetBucket::registerType();
+
+  register_graphql_field('RootQuery', 'assetBuckets', [
+    'type' => 'FilmAssetProgram',
+    'args' => [
+      'programId' => ['type' => 'ID'],
+    ],
+    'resolve' => function ($root, $args) {
+      $program = get_post($args['programId']);
+
+      if (!$program) {
+        throw new \GraphQL\Error\UserError('Program not found');
+      }
+
+      return new FilmAssetProgram($program);
+    },
+  ]);
+});
+```
+
+## Add Enums [#add-enums]
+
+Enums are useful when a field has a small, known set of values.
+
+```php
+enum EventType: string {
+  case Film = 'Film';
+  case Event = 'Event';
+  case Short = 'Short';
+  case Subscription = 'Subscription';
+}
+
+add_action('graphql_register_types', function () {
+  register_graphql_enum_type('EventType', [
+    'description' => 'Standard event types',
+    'values' => php_enum_cases_to_graphql_cases(EventType::cases()),
+  ]);
+});
+```
+
+Enums make the generated TypeScript types more useful than a loose `string`.
+
+## Keep Extensions Small [#keep-extensions-small]
+
+Schema extensions are easiest to maintain when they sit close to the model they
+describe. Prefer small fields on the relevant type over one large root field
+that returns unrelated data.
+
+When a resolver is expensive, cache the underlying data in WordPress or expose a
+runtime query with an explicit `# ttl` comment in the `.graphql` file.

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

@@ -0,0 +1,107 @@
+# GraphQL Fragments (/docs/graphql/fragments)
+
+**Share GraphQL selections and generated fragment types across queries.**
+
+[GraphQL fragments](https://graphql.org/learn/queries/#fragments) are reusable selections. Use them when the same object shape appears in multiple view, block, or runtime queries.
+
+Fragments live in `queries/fragments/**/*.graphql`.
+
+```graphql filename="queries/fragments/ResponsiveImage.graphql"
+fragment ResponsiveImage on MediaItem {
+  mediaItemUrl
+  caption
+  srcSet
+  altText
+  mediaDetails {
+    width
+    height
+  }
+}
+```
+
+Then spread the fragment anywhere the schema returns that type:
+
+```graphql filename="views/single.graphql"
+query Single($postId: ID!) {
+  post(id: $postId, idType: DATABASE_ID) {
+    title
+    featuredImage {
+      node {
+        ...ResponsiveImage
+      }
+    }
+  }
+}
+```
+
+eddev automatically includes fragment files during codegen, so the fragment type is available in the generated `/types.graphql.ts` file.
+
+## Fragment Types [#fragment-types]
+
+Import generated fragment types from `@generated-types`. This is a project alias for the generated `/types.graphql.ts` file.
+
+```tsx filename="components/atoms/ResponsiveImage.tsx"
+import { ResponsiveImageFragment } from "@generated-types"
+
+type Props = Partial<ResponsiveImageFragment>
+```
+
+## Tiles And Repeated Shapes [#tiles-and-repeated-shapes]
+
+Fragments are especially useful for cards, tiles, and reusable listing components.
+
+```graphql filename="queries/fragments/CaseStudyTile.graphql"
+fragment CaseStudyTile on CaseStudy {
+  uri
+  title
+  subtitle
+  info {
+    heroImage {
+      ...ResponsiveImage
+    }
+    categories {
+      name
+      slug
+      uri
+    }
+  }
+}
+```
+
+Then an archive view can select a list of tiles without repeating the fields:
+
+```graphql filename="views/archive-case-study.graphql"
+query ArchiveCaseStudies {
+  caseStudies(first: 100) {
+    nodes {
+      ...CaseStudyTile
+    }
+  }
+}
+```
+
+The matching component can use the generated fragment type as its prop shape:
+
+```tsx filename="components/tiles/CaseStudyTile.tsx"
+import { CaseStudyTileFragment } from "@generated-types"
+import { Link } from "eddev/routing"
+
+type Props = {
+  caseStudy: CaseStudyTileFragment
+}
+
+export function CaseStudyTile(props: Props) {
+  const { caseStudy } = props
+
+  return (
+    <article>
+      <h2>
+        <Link href={caseStudy.uri!}>{caseStudy.title}</Link>
+      </h2>
+      {caseStudy.subtitle && <p>{caseStudy.subtitle}</p>}
+    </article>
+  )
+}
+```
+
+Prefer one fragment per reusable display shape, not one fragment per database table. A `CaseStudyTile` fragment is more useful than a generic fragment that tries to include every case-study field.

package/skills/eddev/docs/graphql/global-data.mdx

@@ -0,0 +1,47 @@
+# Global Data (/docs/graphql/global-data)
+
+**Fetch shared site shell data through views/_app.graphql.**
+
+`views/_app.graphql` fetches data needed by the site shell and shared systems. Typical examples are menus, settings, trackers, global callouts, and template parts.
+
+```graphql filename="views/_app.graphql"
+query CommonData {
+  menus {
+    nodes {
+      locations
+      slug
+      name
+      menuItems {
+        nodes {
+          label
+          title
+          url
+          parentId
+        }
+      }
+    }
+  }
+  templateParts {
+    siteFooter {
+      contentBlocks
+    }
+  }
+}
+```
+
+The result is available to `views/_app.tsx` as props and anywhere in React through `useAppData()`.
+
+```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} />
+}
+```
+
+App data is loaded with the initial route payload and reused during normal client-side navigation. Do not put per-page content in `_app.graphql`; use a paired [view query](/docs/views/queries) instead.
+
+For the layout side of `_app.tsx`, see [`_app.tsx` Layout](/docs/views/app-view).

package/skills/eddev/docs/graphql/infinite-queries.mdx

@@ -0,0 +1,95 @@
+# Infinite Queries (/docs/graphql/infinite-queries)
+
+**Build load-more interfaces with generated infinite query hooks.**
+
+Infinite queries are runtime query hooks for "load more" interfaces. They build on normal [Query Hooks](/docs/graphql/query-hooks), but codegen adds pagination handling around a WPGraphQL connection.
+
+<Callout type="info">
+  WPGraphQL uses cursor pagination. Instead of asking for page 2, you ask for the next items after the last `endCursor`.
+</Callout>
+
+## Codegen Requirements [#codegen-requirements]
+
+Codegen treats a query as infinite when the operation name contains `Infinite`, for example `UseInfinitePosts`.
+
+The query must:
+
+* live under `queries/`
+* follow the normal `Use*` filename and operation-name rules
+* define `$limit: Int` with a default value
+* define `$cursor: String` with no default value
+* use `first: $limit` and `after: $cursor` on the connection
+* select one `pageInfo` object
+* select `pageInfo { endCursor hasNextPage }`
+* select `nodes` next to that `pageInfo`
+
+```graphql filename="queries/UseInfinitePosts.graphql"
+query UseInfinitePosts($limit: Int = 6, $cursor: String) {
+  posts(first: $limit, after: $cursor) {
+    pageInfo {
+      endCursor
+      hasNextPage
+    }
+    nodes {
+      uri
+      title
+    }
+  }
+}
+```
+
+## Hook API [#hook-api]
+
+The generated hook returns a TanStack infinite-query result, with the page data flattened for normal rendering.
+
+```ts
+type InfiniteResult<TNode> = {
+  data?: {
+    nodes: TNode[]
+    total?: number | null
+  }
+  hasNextPage: boolean
+  isFetchingNextPage: boolean
+  fetchNextPage: () => Promise<unknown>
+}
+```
+
+Use `fetchNextPage()` to load the next page.
+
+## Example Usage [#example-usage]
+
+```tsx filename="components/LatestPosts.tsx"
+import { useInfinitePosts } from "@hooks/queries"
+
+export function LatestPosts() {
+  const lookup = useInfinitePosts(undefined, {
+    refetchOnWindowFocus: false,
+  })
+
+  return (
+    <div>
+      {lookup.isLoading && <p>Loading...</p>}
+
+      {lookup.data?.nodes?.length ? (
+        <ul>
+          {lookup.data.nodes.map((post) => (
+            <li key={post.uri}>{post.title}</li>
+          ))}
+        </ul>
+      ) : null}
+
+      {lookup.hasNextPage && (
+        <button disabled={lookup.isFetchingNextPage} onClick={() => lookup.fetchNextPage()}>
+          {lookup.isFetchingNextPage ? "Loading..." : "Load more"}
+        </button>
+      )}
+    </div>
+  )
+}
+```
+
+## Initial Data [#initial-data]
+
+Infinite hooks accept `initialData`, but it must match the original GraphQL query structure, including the selected `nodes`, `pageInfo.hasNextPage`, and `pageInfo.endCursor` fields.
+
+Only use `initialData` when you already have a matching connection result from a view, block, or app query. Otherwise, let the hook load normally in the browser.

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

@@ -0,0 +1,111 @@
+# Mutation Hooks (/docs/graphql/mutation-hooks)
+
+**Generate mutation hooks for runtime GraphQL operations with side effects.**
+
+Mutations are GraphQL operations with side effects, such as submitting a form, creating a shared planner, saving user data, or sending an enquiry.
+
+Mutation files live under `queries/` and follow the same filename rules as query hooks: the file and operation should start with `Use`, and the operation name should match the filename.
+
+```graphql filename="queries/shared-planner/UseCreateSharedPlanner.graphql"
+mutation UseCreateSharedPlanner($ids: [Int!], $name: String, $userId: String) {
+  createSharedPlanner(input: { ferveIds: $ids, name: $name, ferveUserId: $userId }) {
+    planner {
+      id
+      name
+    }
+  }
+}
+```
+
+This generates `useCreateSharedPlanner` in `hooks/queries.ts`.
+
+Unlike query hooks, mutation hooks do not run when rendered. You call `mutate()` or `mutateAsync()` from an event handler.
+
+## Hook Usage [#hook-usage]
+
+```tsx
+import { useState } from "react"
+import { useCreateSharedPlanner } from "@hooks/queries"
+
+export function CreateSharedPlanner() {
+  const [name, setName] = useState("")
+  const create = useCreateSharedPlanner()
+
+  if (create.isSuccess) {
+    return <p>Planner created: {create.data.createSharedPlanner?.planner?.id}</p>
+  }
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault()
+        if (create.isPending) return
+
+        create.mutate({
+          name,
+          ids: [123, 456],
+        })
+      }}
+    >
+      {create.isError && <p>{create.error.message}</p>}
+      <input disabled={create.isPending} value={name} onChange={(e) => setName(e.currentTarget.value)} />
+      <button disabled={create.isPending} type="submit">Create Planner</button>
+    </form>
+  )
+}
+```
+
+<Callout>
+  Many built-in WPGraphQL mutations require WordPress admin privileges. Public-facing mutations usually need to be registered by the project. See [Extending GraphQL](./extending).
+</Callout>
+
+## Hook API [#hook-api]
+
+The generated hook returns a TanStack mutation result:
+
+```ts
+const mutation = useCreateSharedPlanner({
+  onSuccess(data) {
+    // Optional success handler
+  },
+  onError(error) {
+    // Optional error handler
+  },
+})
+```
+
+Useful returned properties include:
+
+```ts
+type MutationResult<TData, TVars> = {
+  status: "idle" | "pending" | "error" | "success"
+  isPending: boolean
+  isSuccess: boolean
+  isError: boolean
+  error: QueryError | null
+  data: TData | undefined
+  mutate: (variables: TVars, options?: MutationOptions<TData>) => void
+  mutateAsync: (variables: TVars, options?: MutationOptions<TData>) => Promise<TData>
+}
+```
+
+You can pass mutation options to the hook itself, or to `mutate()` / `mutateAsync()`.
+
+## Manual Mutation [#manual-mutation]
+
+Each generated mutation hook also has a static `.mutate()` method for non-hook usage.
+
+```ts
+import { useCreateSharedPlanner } from "@hooks/queries"
+
+async function createPlanner() {
+  const result = await useCreateSharedPlanner.mutate({
+    name: "Weekend picks",
+    ids: [123, 456],
+  })
+
+  return result.createSharedPlanner?.planner
+}
+```
+
+Prefer the hook in React components so loading and error states stay tied to the UI.