Content Listing & Discovery

# A list query fetches only the metadata fields needed for a list view -
# displayName, published date, and URL. No per-page content is fetched.
# This keeps list-page responses small regardless of how much body copy
# each article contains.

query GetArticles($limit: Int) {
  ArticlePage(
    limit: $limit
    orderBy: { _metadata: { published: DESC } }
    where: { _metadata: { url: { default: { exist: true } } } }
  ) {
    total
    cursor
    items {
      _metadata {
        displayName    # page title
        published      # ISO 8601 date
        url { default }
      }
      summary          # short description field on ArticlePage
      heroImage {
        _metadata { url { default } }
      }
    }
  }
}

// _metadata fields are available on every content type - no fragment needed.
// They are the minimum data required to render a list item without fetching full content.

type ListItem = {
  _metadata: {
    displayName: string;      // page title (always set)
    published:   string;      // ISO 8601 - use for sort order and "Published on" labels
    url: { default: string }; // the canonical public URL - href for the link
    __typename: string;       // "ArticlePage", "LandingPage", etc. - use for type badges
    locale: string;           // "en", "fr" - use when serving multi-locale lists
  };
  // plus whatever custom fields you include in your query (summary, heroImage, etc.)
};

# Cursor pagination - Graph returns an opaque cursor string.
# Pass it back on the next request to get the next page.
# Cursors remain valid even if new content is published between requests.

const PAGE_SIZE = 12;

// Page 1 - no cursor
const res1 = await graphqlFetch(GET_ARTICLES_QUERY, { limit: PAGE_SIZE });
const { items, cursor, total } = res1.data.ArticlePage;
// cursor = "eyJza2lwIjoxMn0="  (opaque - never parse it)

// Page 2 - add cursor to the query variable
const GET_ARTICLES_WITH_CURSOR = `
  query GetArticles($limit: Int, $cursor: String) {
    ArticlePage(limit: $limit, cursor: $cursor, ...) {
      total
      cursor     # ← cursor for the NEXT page after this one
      items { ... }
    }
  }
`;

const res2 = await graphqlFetch(GET_ARTICLES_WITH_CURSOR, {
  limit: PAGE_SIZE,
  cursor: cursor,   // ← cursor from page 1 response
});

# Why NOT offset pagination with Graph

# ❌ Offset (skip) - fragile under concurrent writes
# If 3 articles are published between page 1 and page 2 requests,
# skip: 12 will repeat 3 items already shown (or skip 3 unseen items).
query GetArticlesOffset($skip: Int) {
  ArticlePage(limit: 12) {  # Graph doesn't expose a native skip param
    items { ... }            # you'd have to slice results in app code
  }
}

# ✅ Cursor - stable pointer into the result set
# New publishes don't affect the cursor position - next page is always
# relative to the last item you saw, not an absolute row number.
query GetArticlesCursor($cursor: String) {
  ArticlePage(limit: 12, cursor: $cursor) {
    cursor   # the next page cursor - null when there are no more pages
    items { ... }
  }
}