@sanity/ailf 0.1.0

package/canonical/reference-solutions/groq/joins-references.ts

@@ -0,0 +1,300 @@
+/**
+ * Reference Solution: GROQ Joins and References
+ *
+ * Demonstrates:
+ * - Following single references with ->
+ * - Resolving arrays of references
+ * - Nested/reverse joins using parent scope (^)
+ * - The references() function
+ * - Building rich nested responses
+ */
+
+import { createClient } from "@sanity/client"
+
+// ---------- Client setup ----------
+
+const client = createClient({
+  projectId: "your-project-id",
+  dataset: "production",
+  apiVersion: "2024-01-01",
+  useCdn: true,
+})
+
+// ---------- Types ----------
+
+interface SanityImage {
+  _type: "image"
+  asset: {
+    _ref: string
+    _type: "reference"
+  }
+}
+
+interface Author {
+  _id: string
+  _type: "author"
+  name: string
+  bio: unknown[] // Portable Text blocks
+  image: SanityImage | null
+}
+
+interface Category {
+  _id: string
+  _type: "category"
+  title: string
+  slug: { current: string }
+}
+
+interface Post {
+  _id: string
+  _type: "post"
+  title: string
+  slug: { current: string }
+  publishedAt: string
+}
+
+// ---------- Result types for each query ----------
+
+/** Result of resolving a post with its author (single reference) */
+interface PostWithAuthor {
+  _id: string
+  title: string
+  slug: { current: string }
+  publishedAt: string
+  author: {
+    name: string
+    bio: unknown[]
+    image: SanityImage | null
+  } | null
+}
+
+/** Result of resolving a post with its categories (array of references) */
+interface PostWithCategories {
+  _id: string
+  title: string
+  categories: Array<{
+    _id: string
+    title: string
+  }>
+}
+
+/** Result of resolving an author with their latest posts (nested/reverse join) */
+interface AuthorWithLatestPosts {
+  _id: string
+  name: string
+  bio: unknown[]
+  image: SanityImage | null
+  latestPosts: Array<{
+    _id: string
+    title: string
+    slug: { current: string }
+    publishedAt: string
+  }>
+}
+
+/** Result of finding all documents that reference a specific document */
+interface ReferencingDocument {
+  _id: string
+  _type: string
+  title: string
+}
+
+/** Result of a full post with all references resolved */
+interface FullPost {
+  _id: string
+  title: string
+  slug: { current: string }
+  publishedAt: string
+  author: {
+    _id: string
+    name: string
+    image: SanityImage | null
+  } | null
+  categories: Array<{
+    _id: string
+    title: string
+  }>
+}
+
+// ---------- 1. Follow a single reference with -> ----------
+// The -> operator dereferences a reference field, replacing the
+// { _ref: "abc123" } stub with the full referenced document.
+
+async function fetchPostWithAuthor(
+  postSlug: string
+): Promise<PostWithAuthor | null> {
+  const query = `
+    *[_type == "post" && slug.current == $postSlug][0]{
+      _id,
+      title,
+      slug,
+      publishedAt,
+      // Dereference the author and pick specific fields
+      author->{
+        name,
+        bio,
+        image
+      }
+    }
+  `
+
+  return client.fetch<PostWithAuthor | null>(query, { postSlug })
+}
+
+// ---------- 2. Follow an array of references ----------
+// When a field is an array of references, use []-> to dereference
+// every item in the array in one go.
+
+async function fetchPostWithCategories(
+  postSlug: string
+): Promise<PostWithCategories | null> {
+  const query = `
+    *[_type == "post" && slug.current == $postSlug][0]{
+      _id,
+      title,
+      // Dereference each category reference in the array
+      "categories": categories[]->{
+        _id,
+        title
+      }
+    }
+  `
+
+  return client.fetch<PostWithCategories | null>(query, { postSlug })
+}
+
+// ---------- 3. Nested join with reverse reference ----------
+// Combine -> with a sub-query that uses references() and ^._id
+// to build a rich nested response in a single round trip.
+
+async function fetchAuthorWithLatestPosts(
+  authorSlug: string
+): Promise<AuthorWithLatestPosts | null> {
+  const query = `
+    *[_type == "author" && slug.current == $authorSlug][0]{
+      _id,
+      name,
+      bio,
+      image,
+      // Reverse join: find posts that reference this author.
+      // ^._id refers to the _id of the outer (parent) document.
+      "latestPosts": *[_type == "post" && references(^._id)] | order(publishedAt desc)[0...5]{
+        _id,
+        title,
+        slug,
+        publishedAt
+      }
+    }
+  `
+
+  return client.fetch<AuthorWithLatestPosts | null>(query, { authorSlug })
+}
+
+// ---------- 4. The references() function ----------
+// references(id) matches any document that contains a reference
+// to the given document ID, at any depth in its tree.
+
+async function fetchDocumentsReferencingId(
+  documentId: string
+): Promise<ReferencingDocument[]> {
+  const query = `
+    *[references($documentId)]{
+      _id,
+      _type,
+      title
+    }
+  `
+
+  return client.fetch<ReferencingDocument[]>(query, { documentId })
+}
+
+// ---------- 5. Reverse reference with parent scope (^) ----------
+// Use ^ to access the parent scope in nested projections.
+// This enables "give me X and, for each X, find related Y" patterns.
+
+async function fetchCategoriesWithPostCount(): Promise<
+  Array<{
+    _id: string
+    title: string
+    postCount: number
+  }>
+> {
+  const query = `
+    *[_type == "category"]{
+      _id,
+      title,
+      // Count how many posts reference this category.
+      // ^._id is the current category's _id.
+      "postCount": count(*[_type == "post" && references(^._id)])
+    } | order(postCount desc)
+  `
+
+  return client.fetch(query)
+}
+
+// ---------- 6. Combining multiple join patterns ----------
+// A single query can mix all patterns: forward references,
+// array dereferencing, and reverse joins.
+
+async function fetchFullPost(postSlug: string): Promise<FullPost | null> {
+  const query = `
+    *[_type == "post" && slug.current == $postSlug][0]{
+      _id,
+      title,
+      slug,
+      publishedAt,
+      // Single reference join
+      author->{
+        _id,
+        name,
+        image
+      },
+      // Array of references join
+      "categories": categories[]->{
+        _id,
+        title
+      }
+    }
+  `
+
+  return client.fetch<FullPost | null>(query, { postSlug })
+}
+
+// ---------- Usage examples ----------
+
+async function main() {
+  // 1. Get a post with its author resolved
+  const postWithAuthor = await fetchPostWithAuthor("my-first-post")
+  console.log("Post author:", postWithAuthor?.author?.name)
+
+  // 2. Get a post with its categories resolved
+  const postWithCategories = await fetchPostWithCategories("my-first-post")
+  console.log(
+    "Categories:",
+    postWithCategories?.categories.map((c) => c.title)
+  )
+
+  // 3. Get an author with their 5 latest posts (nested reverse join)
+  const authorWithPosts = await fetchAuthorWithLatestPosts("jane-doe")
+  console.log(
+    "Latest posts:",
+    authorWithPosts?.latestPosts.map((p) => p.title)
+  )
+
+  // 4. Find everything that references a specific document
+  const referencingDocs = await fetchDocumentsReferencingId("author-abc123")
+  console.log("Documents referencing author:", referencingDocs.length)
+
+  // 5. Get categories with their post counts (reverse reference)
+  const categoriesWithCounts = await fetchCategoriesWithPostCount()
+  console.log(
+    "Categories by post count:",
+    categoriesWithCounts.map((c) => `${c.title}: ${c.postCount}`)
+  )
+
+  // 6. Get a fully resolved post (combines all patterns)
+  const fullPost = await fetchFullPost("my-first-post")
+  console.log("Full post:", fullPost?.title, "by", fullPost?.author?.name)
+}
+
+main()

package/canonical/reference-solutions/nextjs/app-router-integration.tsx

@@ -0,0 +1,128 @@
+// Next.js App Router + Sanity Integration
+// Demonstrates: sanity client setup, GROQ queries, server components, ISR, draft mode
+
+// --- lib/sanity.client.ts ---
+import { createClient } from "next-sanity"
+
+export const client = createClient({
+  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
+  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET ?? "production",
+  apiVersion: "2024-01-01",
+  useCdn: true,
+  // For authenticated requests (preview/drafts)
+  token: process.env.SANITY_API_READ_TOKEN,
+})
+
+// --- lib/sanity.queries.ts ---
+import { groq } from "next-sanity"
+
+export const postsQuery = groq`*[_type == "post"] | order(publishedAt desc) {
+  _id,
+  title,
+  slug,
+  publishedAt,
+  "author": author->name,
+  "categories": categories[]->title,
+  mainImage
+}`
+
+export const postBySlugQuery = groq`*[_type == "post" && slug.current == $slug][0] {
+  _id,
+  title,
+  slug,
+  body,
+  publishedAt,
+  "author": author->{name, image, bio},
+  "categories": categories[]->title,
+  mainImage
+}`
+
+// --- app/posts/page.tsx ---
+// Server Component — fetches at request time with ISR
+import { client } from "@/lib/sanity.client"
+import { postsQuery } from "@/lib/sanity.queries"
+import Link from "next/link"
+
+// Enable ISR with revalidation
+export const revalidate = 60
+
+interface Post {
+  _id: string
+  title: string
+  slug: { current: string }
+  publishedAt: string
+  author: string
+  categories: string[]
+}
+
+export default async function PostsPage() {
+  const posts = await client.fetch<Post[]>(postsQuery)
+
+  return (
+    <main>
+      <h1>Blog Posts</h1>
+      <ul>
+        {posts.map((post) => (
+          <li key={post._id}>
+            <Link href={`/posts/${post.slug.current}`}>
+              {post.title}
+            </Link>
+            <span>by {post.author}</span>
+          </li>
+        ))}
+      </ul>
+    </main>
+  )
+}
+
+// --- app/posts/[slug]/page.tsx ---
+import { client } from "@/lib/sanity.client"
+import { postBySlugQuery, postsQuery } from "@/lib/sanity.queries"
+import { notFound } from "next/navigation"
+
+export const revalidate = 60
+
+// Generate static paths for all posts
+export async function generateStaticParams() {
+  const posts = await client.fetch<Array<{ slug: { current: string } }>>(
+    groq`*[_type == "post"]{ slug }`
+  )
+  return posts.map((post) => ({ slug: post.slug.current }))
+}
+
+export default async function PostPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>
+}) {
+  const { slug } = await params
+  const post = await client.fetch(postBySlugQuery, { slug })
+
+  if (!post) notFound()
+
+  return (
+    <article>
+      <h1>{post.title}</h1>
+      <p>By {post.author?.name}</p>
+      {/* Render portable text body with @portabletext/react */}
+    </article>
+  )
+}
+
+// --- app/api/draft-mode/enable/route.ts ---
+import { draftMode } from "next/headers"
+import { redirect } from "next/navigation"
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url)
+  const secret = searchParams.get("secret")
+  const slug = searchParams.get("slug") ?? "/"
+
+  if (secret !== process.env.SANITY_PREVIEW_SECRET) {
+    return new Response("Invalid secret", { status: 401 })
+  }
+
+  const draft = await draftMode()
+  draft.enable()
+  redirect(slug)
+}

package/canonical/reference-solutions/studio-setup/blog-schema.ts

@@ -0,0 +1,143 @@
+// Blog schema: posts with rich text, authors with bios, categories
+// Demonstrates: defineType, defineField, document types, references, arrays, images
+
+import { defineField, defineType } from "sanity"
+
+export const category = defineType({
+  name: "category",
+  title: "Category",
+  type: "document",
+  fields: [
+    defineField({
+      name: "title",
+      title: "Title",
+      type: "string",
+      validation: (rule) => rule.required(),
+    }),
+    defineField({
+      name: "slug",
+      title: "Slug",
+      type: "slug",
+      options: { source: "title", maxLength: 96 },
+      validation: (rule) => rule.required(),
+    }),
+    defineField({
+      name: "description",
+      title: "Description",
+      type: "text",
+    }),
+  ],
+})
+
+export const author = defineType({
+  name: "author",
+  title: "Author",
+  type: "document",
+  fields: [
+    defineField({
+      name: "name",
+      title: "Name",
+      type: "string",
+      validation: (rule) => rule.required(),
+    }),
+    defineField({
+      name: "slug",
+      title: "Slug",
+      type: "slug",
+      options: { source: "name", maxLength: 96 },
+      validation: (rule) => rule.required(),
+    }),
+    defineField({
+      name: "image",
+      title: "Image",
+      type: "image",
+      options: { hotspot: true },
+    }),
+    defineField({
+      name: "bio",
+      title: "Bio",
+      type: "array",
+      of: [{ type: "block" }],
+    }),
+  ],
+  preview: {
+    select: {
+      title: "name",
+      media: "image",
+    },
+  },
+})
+
+export const post = defineType({
+  name: "post",
+  title: "Post",
+  type: "document",
+  fields: [
+    defineField({
+      name: "title",
+      title: "Title",
+      type: "string",
+      validation: (rule) => rule.required(),
+    }),
+    defineField({
+      name: "slug",
+      title: "Slug",
+      type: "slug",
+      options: { source: "title", maxLength: 96 },
+      validation: (rule) => rule.required(),
+    }),
+    defineField({
+      name: "author",
+      title: "Author",
+      type: "reference",
+      to: [{ type: "author" }],
+    }),
+    defineField({
+      name: "mainImage",
+      title: "Main image",
+      type: "image",
+      options: { hotspot: true },
+    }),
+    defineField({
+      name: "categories",
+      title: "Categories",
+      type: "array",
+      of: [{ type: "reference", to: [{ type: "category" }] }],
+    }),
+    defineField({
+      name: "publishedAt",
+      title: "Published at",
+      type: "datetime",
+    }),
+    defineField({
+      name: "body",
+      title: "Body",
+      type: "array",
+      of: [
+        { type: "block" },
+        {
+          type: "image",
+          options: { hotspot: true },
+          fields: [
+            defineField({
+              name: "alt",
+              title: "Alternative text",
+              type: "string",
+            }),
+          ],
+        },
+      ],
+    }),
+  ],
+  preview: {
+    select: {
+      title: "title",
+      author: "author.name",
+      media: "mainImage",
+    },
+    prepare(selection) {
+      const { author } = selection
+      return { ...selection, subtitle: author && `by ${author}` }
+    },
+  },
+})

package/canonical/reference-solutions/studio-setup/custom-tool.tsx

@@ -0,0 +1,78 @@
+// Custom Studio Tool: Analytics Dashboard
+// Demonstrates: definePlugin, tool API, Studio UI components, React integration
+
+import { ChartUpwardIcon } from "@sanity/icons"
+import { Box, Card, Flex, Heading, Stack, Text } from "@sanity/ui"
+import { useEffect, useState } from "react"
+import { definePlugin, type Tool } from "sanity"
+
+// Component that renders the tool's UI
+function AnalyticsDashboard() {
+  const [stats, setStats] = useState<{
+    documents: number
+    drafts: number
+    published: number
+  } | null>(null)
+
+  useEffect(() => {
+    // In a real tool, you'd fetch data from Sanity or an external API
+    // This demonstrates the pattern
+    setStats({ documents: 142, drafts: 12, published: 130 })
+  }, [])
+
+  if (!stats) {
+    return (
+      <Card padding={4}>
+        <Text>Loading...</Text>
+      </Card>
+    )
+  }
+
+  return (
+    <Box padding={4}>
+      <Stack space={4}>
+        <Heading as="h1" size={3}>
+          Analytics Dashboard
+        </Heading>
+        <Flex gap={4} wrap="wrap">
+          <StatCard label="Total Documents" value={stats.documents} />
+          <StatCard label="Drafts" value={stats.drafts} />
+          <StatCard label="Published" value={stats.published} />
+        </Flex>
+      </Stack>
+    </Box>
+  )
+}
+
+function StatCard({ label, value }: { label: string; value: number }) {
+  return (
+    <Card padding={4} radius={2} shadow={1} style={{ minWidth: 200 }}>
+      <Stack space={3}>
+        <Text size={1} muted>
+          {label}
+        </Text>
+        <Heading size={4}>{value}</Heading>
+      </Stack>
+    </Card>
+  )
+}
+
+// Define the tool using Sanity's plugin API
+const analyticsTool: Tool = {
+  name: "analytics",
+  title: "Analytics",
+  icon: ChartUpwardIcon,
+  component: AnalyticsDashboard,
+}
+
+// Export as a Sanity plugin
+export const analyticsPlugin = definePlugin({
+  name: "sanity-plugin-analytics",
+  tools: [analyticsTool],
+})
+
+// Usage in sanity.config.ts:
+// import { analyticsPlugin } from "./plugins/analytics"
+// export default defineConfig({
+//   plugins: [analyticsPlugin()],
+// })