@sanity/ailf 1.0.0 → 2.0.1

package/README.md

@@ -17,5 +17,4 @@ for installation, quick start, configuration, and usage guides.
 
 | Package                                                                    | Description                                        |
 | -------------------------------------------------------------------------- | -------------------------------------------------- |
-| [`@sanity/ailf-tasks`](https://www.npmjs.com/package/@sanity/ailf-tasks)   | Lightweight task validator — schemas + YAML parser |
 | [`@sanity/ailf-studio`](https://www.npmjs.com/package/@sanity/ailf-studio) | Sanity Studio dashboard plugin for viewing reports |

package/canonical/grader-references/README.md

@@ -83,6 +83,6 @@ discrimination power across the full scale.
 
 ## Related
 
-- [Grader Reliability Plan](../../../docs/exec-plans/grader-reliability.md) —
-  Phase 2
+- [Grader Reliability Plan](../../../docs/archive/exec-plans/grader-reliability.md)
+  — Phase 2
 - [Rubric Templates](../../config/rubrics.yaml) — the rubrics used for grading

package/canonical/reference-solutions/content-lake/mutations.ts

@@ -0,0 +1,160 @@
+/**
+ * Reference Solution: Content Lake CRUD Operations
+ *
+ * Demonstrates:
+ * - Creating documents with client.create()
+ * - Patching documents with set, unset, inc
+ * - Deleting documents with client.delete()
+ * - Atomic transactions for multiple mutations
+ * - TypeScript types for document shapes
+ */
+
+import { createClient, type SanityDocument } from "@sanity/client"
+
+// === Client Setup ===
+
+const client = createClient({
+  projectId: "your-project-id",
+  dataset: "production",
+  apiVersion: "2024-01-01",
+  token: process.env.SANITY_API_TOKEN,
+  useCdn: false, // Mutations require the write API, not CDN
+})
+
+// === Types ===
+
+interface Post {
+  _type: "post"
+  title: string
+  slug: { _type: "slug"; current: string }
+  publishedAt: string
+  viewCount: number
+  author: { _type: "reference"; _ref: string }
+  categories?: Array<{ _type: "reference"; _ref: string }>
+}
+
+type PostDocument = SanityDocument & Post
+
+// === 1. Create a Document ===
+
+export async function createPost(data: {
+  title: string
+  slug: string
+  authorId: string
+}): Promise<PostDocument> {
+  return client.create<Post>({
+    _type: "post",
+    title: data.title,
+    slug: { _type: "slug", current: data.slug },
+    publishedAt: new Date().toISOString(),
+    viewCount: 0,
+    author: { _type: "reference", _ref: data.authorId },
+  })
+}
+
+// === 2. Patch a Document ===
+
+// Set and unset fields
+export async function updatePostTitle(
+  postId: string,
+  title: string,
+): Promise<PostDocument> {
+  return client
+    .patch(postId)
+    .set({ title })
+    .unset(["subtitle"]) // Remove a field
+    .commit<PostDocument>()
+}
+
+// Increment a numeric field
+export async function incrementViewCount(
+  postId: string,
+): Promise<PostDocument> {
+  return client
+    .patch(postId)
+    .inc({ viewCount: 1 })
+    .commit<PostDocument>()
+}
+
+// Insert into an array
+export async function addCategory(
+  postId: string,
+  categoryId: string,
+): Promise<PostDocument> {
+  return client
+    .patch(postId)
+    .setIfMissing({ categories: [] })
+    .insert("after", "categories[-1]", [
+      { _type: "reference", _ref: categoryId },
+    ])
+    .commit<PostDocument>()
+}
+
+// === 3. Delete a Document ===
+
+export async function deletePost(postId: string): Promise<void> {
+  await client.delete(postId)
+}
+
+// Delete with a GROQ filter
+export async function deleteDraftPosts(): Promise<void> {
+  // Delete all drafts of posts (draft IDs start with "drafts.")
+  await client.delete({
+    query: '*[_type == "post" && _id in path("drafts.**")]',
+  })
+}
+
+// === 4. Transactions (Atomic Multi-Mutation) ===
+
+export async function publishPostWithCategories(data: {
+  title: string
+  slug: string
+  authorId: string
+  categoryNames: string[]
+}): Promise<void> {
+  const transaction = client.transaction()
+
+  // Create category documents
+  const categoryIds: string[] = []
+  for (const name of data.categoryNames) {
+    const id = `category-${name.toLowerCase().replace(/\s+/g, "-")}`
+    categoryIds.push(id)
+
+    transaction.createIfNotExists({
+      _id: id,
+      _type: "category",
+      title: name,
+    })
+  }
+
+  // Create the post with references to categories
+  transaction.create({
+    _type: "post",
+    title: data.title,
+    slug: { _type: "slug", current: data.slug },
+    publishedAt: new Date().toISOString(),
+    viewCount: 0,
+    author: { _type: "reference", _ref: data.authorId },
+    categories: categoryIds.map((id) => ({
+      _type: "reference",
+      _ref: id,
+    })),
+  })
+
+  // All mutations happen atomically
+  await transaction.commit()
+}
+
+// === 5. createOrReplace — Idempotent upsert ===
+
+export async function upsertSettings(settings: {
+  siteName: string
+  description: string
+}): Promise<SanityDocument> {
+  return client.createOrReplace({
+    _id: "siteSettings",
+    _type: "siteSettings",
+    siteName: settings.siteName,
+    description: settings.description,
+  })
+}

package/canonical/reference-solutions/content-lake/realtime.ts

@@ -0,0 +1,187 @@
+/**
+ * Reference Solution: Real-Time Content Listeners
+ *
+ * Demonstrates:
+ * - Setting up client.listen() with GROQ filters
+ * - Handling mutation events (create, update, delete)
+ * - Maintaining an in-memory cache synchronized with the Content Lake
+ * - Subscription cleanup and error handling
+ * - TypeScript types for listener events
+ */
+
+import { createClient, type SanityDocument } from "@sanity/client"
+import type { Subscription } from "rxjs"
+
+// === Client Setup ===
+
+const client = createClient({
+  projectId: "your-project-id",
+  dataset: "production",
+  apiVersion: "2024-01-01",
+  token: process.env.SANITY_API_TOKEN,
+  useCdn: false, // Listeners require the real-time API
+})
+
+// === Types ===
+
+interface Post extends SanityDocument {
+  _type: "post"
+  title: string
+  slug: { current: string }
+  publishedAt: string
+}
+
+interface MutationEvent {
+  type: "mutation"
+  documentId: string
+  transition: "update" | "appear" | "disappear"
+  result?: SanityDocument
+  previousRev?: string
+  resultRev?: string
+}
+
+interface ReconnectEvent {
+  type: "reconnect"
+}
+
+type ListenerEvent = MutationEvent | ReconnectEvent
+
+// === In-Memory Cache ===
+
+class ContentCache<T extends SanityDocument> {
+  private documents = new Map<string, T>()
+
+  getAll(): T[] {
+    return Array.from(this.documents.values())
+  }
+
+  get(id: string): T | undefined {
+    return this.documents.get(id)
+  }
+
+  set(id: string, doc: T): void {
+    this.documents.set(id, doc)
+  }
+
+  delete(id: string): boolean {
+    return this.documents.delete(id)
+  }
+
+  get size(): number {
+    return this.documents.size
+  }
+}
+
+// === Listener Setup ===
+
+/**
+ * Creates a real-time listener that keeps a local cache in sync with
+ * documents matching a GROQ filter.
+ *
+ * Returns an object with the cache and an unsubscribe function.
+ */
+export async function createRealtimeSync<T extends SanityDocument>(options: {
+  filter: string
+  params?: Record<string, unknown>
+  onUpdate?: (event: MutationEvent) => void
+  onError?: (error: Error) => void
+}): Promise<{
+  cache: ContentCache<T>
+  unsubscribe: () => void
+}> {
+  const cache = new ContentCache<T>()
+
+  // 1. Initial fetch — populate cache with current data
+  const initialDocs = await client.fetch<T[]>(
+    `*[${options.filter}]`,
+    options.params || {},
+  )
+
+  for (const doc of initialDocs) {
+    cache.set(doc._id, doc)
+  }
+
+  // 2. Start listener — watch for mutations matching the filter
+  const subscription: Subscription = client
+    .listen<T>(
+      `*[${options.filter}]`,
+      options.params || {},
+      {
+        includeResult: true,
+        includePreviousRevision: false,
+        visibility: "query",
+      },
+    )
+    .subscribe({
+      next: (event) => {
+        if (event.type === "reconnect") {
+          // The listener reconnected — could refetch to ensure consistency
+          return
+        }
+
+        if (event.type === "mutation") {
+          const mutation = event as unknown as MutationEvent
+
+          switch (mutation.transition) {
+            case "appear": {
+              // New document matches the filter
+              if (mutation.result) {
+                cache.set(mutation.documentId, mutation.result as T)
+              }
+              break
+            }
+            case "update": {
+              // Existing document was modified
+              if (mutation.result) {
+                cache.set(mutation.documentId, mutation.result as T)
+              }
+              break
+            }
+            case "disappear": {
+              // Document no longer matches the filter (deleted or updated)
+              cache.delete(mutation.documentId)
+              break
+            }
+          }
+
+          options.onUpdate?.(mutation)
+        }
+      },
+      error: (err) => {
+        options.onError?.(
+          err instanceof Error ? err : new Error(String(err)),
+        )
+      },
+    })
+
+  // 3. Return cache and cleanup function
+  return {
+    cache,
+    unsubscribe: () => subscription.unsubscribe(),
+  }
+}
+
+// === Usage Example ===
+
+async function main() {
+  const { cache, unsubscribe } = await createRealtimeSync<Post>({
+    filter: '_type == "post"',
+    onUpdate: (event) => {
+      console.log(
+        `Post ${event.documentId} ${event.transition}:`,
+        event.result?.title,
+      )
+    },
+    onError: (error) => {
+      console.error("Listener error:", error.message)
+    },
+  })
+
+  console.log(`Watching ${cache.size} posts for changes...`)
+
+  // Clean up when done (e.g., on process exit)
+  process.on("SIGINT", () => {
+    unsubscribe()
+    process.exit(0)
+  })
+}

package/canonical/reference-solutions/image-handling/asset-pipeline.tsx

@@ -0,0 +1,166 @@
+/**
+ * Reference Solution: Image Asset Pipeline with Responsive Images
+ *
+ * Demonstrates:
+ * - Setting up @sanity/image-url builder
+ * - Hotspot and crop support
+ * - Responsive srcSet generation for multiple widths
+ * - WebP format with auto-format
+ * - Reusable React component with TypeScript props
+ */
+
+import imageUrlBuilder from "@sanity/image-url"
+import { createClient } from "@sanity/client"
+
+// === Client & Image Builder Setup ===
+
+const client = createClient({
+  projectId: "your-project-id",
+  dataset: "production",
+  apiVersion: "2024-01-01",
+  useCdn: true,
+})
+
+const builder = imageUrlBuilder(client)
+
+// === Types ===
+
+interface SanityImageCrop {
+  top: number
+  bottom: number
+  left: number
+  right: number
+}
+
+interface SanityImageHotspot {
+  x: number
+  y: number
+  height: number
+  width: number
+}
+
+interface SanityImageSource {
+  _type: "image"
+  asset: {
+    _ref: string
+    _type: "reference"
+  }
+  crop?: SanityImageCrop
+  hotspot?: SanityImageHotspot
+  alt?: string
+}
+
+interface SanityImageProps {
+  /** The image field value from a Sanity document */
+  image: SanityImageSource
+  /** Alt text override (falls back to image.alt) */
+  alt?: string
+  /** Max display width in pixels */
+  maxWidth?: number
+  /** CSS sizes attribute for responsive images */
+  sizes?: string
+  /** Additional CSS class names */
+  className?: string
+  /** Loading strategy */
+  loading?: "lazy" | "eager"
+  /** Priority hint for LCP images */
+  priority?: boolean
+}
+
+// === Image URL Helper ===
+
+/**
+ * Generate a URL for a Sanity image with transforms applied.
+ * The builder automatically respects hotspot and crop metadata.
+ */
+function urlFor(source: SanityImageSource) {
+  return builder.image(source)
+}
+
+// === Responsive Breakpoints ===
+
+const DEFAULT_WIDTHS = [320, 480, 640, 768, 1024, 1280, 1536, 1920]
+const DEFAULT_MAX_WIDTH = 1920
+const DEFAULT_SIZES = "(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
+
+// === Generate srcSet ===
+
+function generateSrcSet(
+  image: SanityImageSource,
+  widths: number[] = DEFAULT_WIDTHS,
+): string {
+  return widths
+    .map((w) => {
+      const url = urlFor(image)
+        .width(w)
+        .auto("format") // Serves WebP to browsers that support it
+        .fit("crop") // Respects hotspot and crop data
+        .url()
+
+      return `${url} ${w}w`
+    })
+    .join(", ")
+}
+
+// === React Component ===
+
+export function SanityImage({
+  image,
+  alt,
+  maxWidth = DEFAULT_MAX_WIDTH,
+  sizes = DEFAULT_SIZES,
+  className,
+  loading = "lazy",
+  priority = false,
+}: SanityImageProps) {
+  if (!image?.asset) return null
+
+  // Filter widths to only include those up to maxWidth
+  const widths = DEFAULT_WIDTHS.filter((w) => w <= maxWidth)
+  if (widths[widths.length - 1] !== maxWidth) {
+    widths.push(maxWidth)
+  }
+
+  // Default src at maxWidth for non-srcset browsers
+  const src = urlFor(image)
+    .width(maxWidth)
+    .auto("format")
+    .fit("crop")
+    .url()
+
+  const srcSet = generateSrcSet(image, widths)
+
+  return (
+    <img
+      src={src}
+      srcSet={srcSet}
+      sizes={sizes}
+      alt={alt || image.alt || ""}
+      className={className}
+      loading={priority ? "eager" : loading}
+      decoding={priority ? "sync" : "async"}
+      style={{ maxWidth: "100%", height: "auto" }}
+    />
+  )
+}
+
+// === Low-Level Helpers (for non-React usage) ===
+
+/**
+ * Get a single image URL with transforms applied.
+ *
+ * @example
+ * const url = getImageUrl(post.mainImage, { width: 800, height: 600 })
+ */
+export function getImageUrl(
+  source: SanityImageSource,
+  options: { width?: number; height?: number; quality?: number } = {},
+): string {
+  let img = urlFor(source).auto("format").fit("crop")
+
+  if (options.width) img = img.width(options.width)
+  if (options.height) img = img.height(options.height)
+  if (options.quality) img = img.quality(options.quality)
+
+  return img.url()
+}