Add a limited drafts flag

Good enough to view new Reference sections assuming they're published
but the top-level document that adds them is a draft.

src/documentation/reference/content.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { fetchContent } from "../../common/sanity";
+import { flags } from "../../flags";
 import { Toolkit, ToolkitTopic, ToolkitTopicEntry } from "./model";
 
 export const fetchReferenceToolkit = async (
@@ -29,12 +30,16 @@ export const getTopicAndEntry = (
   return [entry.parent, entry];
 };
 
-// For now we just slurp the whole toolkit at once.
-// Might revisit depending on eventual size.
+// We just slurp the whole toolkit at once.
+// This is necessary for the client-side search index.
 const toolkitQuery = (languageId: string): string => {
+  // The flag applies to the top-level document so for now there's no support for viewing drafts further down.
+  const noDraftsConstraint = flags.drafts
+    ? ""
+    : `&& (_id in path("drafts.**"))`;
   return `
-  *[_type == "toolkit" && language == "${languageId}" && (slug.current == "explore" || slug.current == "reference") && !(_id in path("drafts.**"))]{
-    id, name, description, language,
+  *[_type == "toolkit" && language == "${languageId}" && (slug.current == "explore" || slug.current == "reference") ${noDraftsConstraint}]{
+    _id, id, name, description, language,
     contents[]->{
       name, slug, compatibility, subtitle, image,
       introduction[] {
@@ -75,11 +80,17 @@ const toolkitQuery = (languageId: string): string => {
   }`;
 };
 
+const isDraft = (document: { _id: string }) => /^drafts\./.test(document._id);
+
 const adaptContent = (result: any): Toolkit | undefined => {
-  const toolkits = result as Toolkit[];
+  let toolkits = result as Toolkit[];
   if (toolkits.length === 0) {
     return undefined;
   }
+  // Prefer drafts if we got both
+  if (toolkits.some(isDraft)) {
+    toolkits = toolkits.filter(isDraft);
+  }
   if (toolkits.length > 1) {
     throw new Error("Unexpected results");
   }

src/documentation/reference/model.ts

@@ -8,6 +8,13 @@ import { PortableText, SimpleImage, Slug } from "../../common/sanity";
 import { HasCompatibility } from "../common/model";
 
 export interface Toolkit {
+  /**
+   * The CMS internal id.
+   */
+  _id: string;
+  /**
+   * The logical id.
+   */
   id: string;
   name: string;
   description: string;

src/documentation/search/search.test.ts

@@ -101,6 +101,7 @@ describe("buildReferenceIndex", () => {
   it("uses language from the toolkit for the Reference index", async () => {
     const api: ApiDocsResponse = {};
     const referenceEn: Toolkit = {
+      _id: "asdf",
       id: "reference",
       description: "description",
       language: "en",
@@ -154,6 +155,7 @@ describe("SearchWorker", () => {
     const indexMessage: IndexMessage = {
       kind: "index",
       reference: {
+        _id: "asdf",
         id: "reference",
         description: "Reference stuff",
         name: "Reference",
@@ -185,6 +187,7 @@ describe("SearchWorker", () => {
     const emptyIndex: IndexMessage = {
       kind: "index",
       reference: {
+        _id: "asdf",
         id: "reference",
         description: "Reference stuff",
         name: "Reference",
@@ -196,6 +199,7 @@ describe("SearchWorker", () => {
     const fullIndex: IndexMessage = {
       kind: "index",
       reference: {
+        _id: "asdf",
         id: "reference",
         description: "Reference stuff",
         name: "Reference",

src/flags.ts

@@ -16,30 +16,34 @@ import { Stage, stage as stageFromEnvironment } from "./environment";
  * A union of the flag names (alphabetical order).
  */
 export type Flag =
-  /**
-   * Enables verbose debug logging to the console of drag events.
-   */
-  | "dndDebug"
-
   /**
    * Flag to add a beta notice. Enabled for staging site but not production stages.
    */
   | "betaNotice"
-
   /**
-   * Disables the pop-up welcome dialog.
+   * Enables verbose debug logging to the console of drag events.
+   */
+  | "dndDebug"
+  /**
+   * Shows CMS drafts in preference to live content.
    *
-   * Added to support user-testing and has the nice side-effect of disabling
-   * the dialog for local development so is worth keeping for that use alone.
+   * Currently only supported for the reference content.
    */
-  | "noWelcome"
+  | "drafts"
   /**
    * Disables language selection from the settings menu.
    *
    * Added so we can embed the editor in micro:bit classroom without competing language
    * options. The language selected in classroom is passed through via query param.
    */
-  | "noLang";
+  | "noLang"
+  /**
+   * Disables the pop-up welcome dialog.
+   *
+   * Added to support user-testing and has the nice side-effect of disabling
+   * the dialog for local development so is worth keeping for that use alone.
+   */
+  | "noWelcome";
 
 interface FlagMetadata {
   defaultOnStages: Stage[];
@@ -49,6 +53,7 @@ interface FlagMetadata {
 const allFlags: FlagMetadata[] = [
   // Alphabetical order.
   { name: "dndDebug", defaultOnStages: [] },
+  { name: "drafts", defaultOnStages: ["local", "REVIEW"] },
   { name: "betaNotice", defaultOnStages: ["local", "REVIEW", "STAGING"] },
   { name: "noWelcome", defaultOnStages: ["local", "REVIEW"] },
   { name: "noLang", defaultOnStages: [] },