Create ideas via a preview dialog

.github/workflows/build.yml

@@ -15,7 +15,7 @@ env:
   # renovate: datasource=npm depName=npm
   NPM_VERSION: "11"
   # renovate: datasource=npm depName=@microbit-foundation/python-editor-v3-microbit registryUrl=https://npm.pkg.github.com
-  THEME_VERSION: 0.0.0-home.page.124
+  THEME_VERSION: 0.0.0-home.page.125
 
 jobs:
   stages:

docs/analytics-events.md

@@ -181,7 +181,8 @@ Projects page only. Fires when the user changes the sort field or direction.
 
 ### `idea_open`
 
-User opened an idea from the documentation as a new project.
+User opened an idea as a new project, from the home page idea dialog or the
+editor's Ideas tab.
 
 | Param | Values                     |
 | ----- | -------------------------- |

lang/ui.en.json

@@ -245,7 +245,7 @@
   },
   "create-project-action": {
     "defaultMessage": "Create",
-    "description": "Confirm button of the dialog naming a new project"
+    "description": "Button creating a new project: confirms the dialog naming a new project, and creates one from the home page idea dialog"
   },
   "create-python": {
     "defaultMessage": "Create a new Python file in this project",
@@ -391,6 +391,10 @@
     "defaultMessage": "For more support, see the <link>Python Editor guide</link>",
     "description": "Text with an external link to support/help content"
   },
+  "guide-tab": {
+    "defaultMessage": "Guide",
+    "description": "Sidebar tab button text. Tab shows the guide for the idea the project was opened from."
+  },
   "help": {
     "defaultMessage": "Help",
     "description": "Help menu label"

src/common/AreaHeading.tsx

@@ -9,15 +9,15 @@ import { Box } from "styled-system/jsx";
 
 interface AreaHeadingProps {
   name: string;
-  description: ReactNode;
+  description?: ReactNode;
 }
 
 const AreaHeading = ({ name, description }: AreaHeadingProps) => (
   <Box p="5" pt="3">
     <Text as="h2" fontSize="3xl" fontWeight="semibold">
       {name}
     </Text>
-    <Text fontSize="md">{description}</Text>
+    {description !== undefined && <Text fontSize="md">{description}</Text>}
   </Box>
 );
 

src/documentation/GuideArea.tsx

@@ -0,0 +1,58 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { Text } from "@microbit/ui";
+import { FormattedMessage } from "react-intl";
+import { Stack } from "styled-system/jsx";
+import AreaHeading from "../common/AreaHeading";
+import { docStylesClass } from "../common/documentation-styles";
+import HeadedScrollablePanel from "../common/HeadedScrollablePanel";
+import Spinner from "../common/Spinner";
+import { useOpenIdeaSlug } from "../project/projects-hooks";
+import { useDocumentation } from "./documentation-hooks";
+import IdeaGuideContent from "./ideas/IdeaGuideContent";
+import { Idea } from "./ideas/model";
+
+/**
+ * The guide for the idea the open project came from: its content without
+ * the program, which is in the editor.
+ */
+const GuideArea = () => {
+  const slug = useOpenIdeaSlug();
+  const { ideas } = useDocumentation();
+  if (ideas.status === "loading") {
+    return <Spinner />;
+  }
+  const idea =
+    ideas.status === "ok"
+      ? ideas.content.find((idea) => idea.slug.current === slug)
+      : undefined;
+  if (!idea) {
+    return (
+      <Text p="5" height="100%">
+        <FormattedMessage id="toolkit-error-loading" />
+      </Text>
+    );
+  }
+  return <Guide idea={idea} />;
+};
+
+const Guide = ({ idea }: { idea: Idea }) => (
+  <HeadedScrollablePanel heading={<AreaHeading name={idea.name} />}>
+    <Stack
+      gap="3"
+      fontSize="sm"
+      p="5"
+      pr="3"
+      mt="1"
+      mb="1"
+      className={docStylesClass}
+    >
+      <IdeaGuideContent idea={idea} />
+    </Stack>
+  </HeadedScrollablePanel>
+);
+
+export default GuideArea;

src/documentation/common/DocumentationContent.tsx

@@ -43,6 +43,11 @@ interface DocumentationContextValue {
   parentSlug?: string;
   toolkitType?: string;
   title?: string;
+  /**
+   * Links to Reference and API, which navigate the editor's sidebar. False
+   * outside the editor, where they show as plain text.
+   */
+  editorLinks?: boolean;
 }
 
 const DocumentationContext = React.createContext<DocumentationContextValue>({});
@@ -67,10 +72,17 @@ const useCodeEmbedContext = () => {
   return { parentSlug, toolkitType, title };
 };
 
+const useEditorLinks = () =>
+  useContext(DocumentationContext).editorLinks !== false;
+
 const DocumentationApiLinkMark = (
   props: SerializerMarkProps<ToolkitApiLink>
 ) => {
   const [, setState] = useRouterState();
+  const editorLinks = useEditorLinks();
+  if (!editorLinks) {
+    return <>{props.children}</>;
+  }
   return (
     <Link
       color="brand.600"
@@ -91,6 +103,10 @@ const DocumentationInternalLinkMark = (
   props: SerializerMarkProps<ToolkitInternalLink>
 ) => {
   const [state, setState] = useRouterState();
+  const editorLinks = useEditorLinks();
+  if (!editorLinks) {
+    return <>{props.children}</>;
+  }
   return (
     <Link
       color="brand.600"

src/documentation/ideas/IdeaGuideContent.tsx

@@ -0,0 +1,70 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { CSSProperties } from "react";
+import { Box } from "styled-system/jsx";
+import { runtimeAspectRatioClass } from "../../common/documentation-styles";
+import {
+  getAspectRatioPadding,
+  imageUrlBuilder,
+} from "../../common/imageUrlBuilder";
+import DocumentationContent, {
+  DocumentationContextProvider,
+} from "../common/DocumentationContent";
+import ImageWithFallback from "../common/ImageWithFallback";
+import OfflineImageFallback from "../OfflineImageFallback";
+import { withoutCode } from "./idea-code";
+import { Idea } from "./model";
+
+interface IdeaGuideContentProps {
+  idea: Idea;
+  /**
+   * In the editor's guide panel: with the idea's image, and links to
+   * Reference and API. False in the home page's idea dialog.
+   */
+  inEditor?: boolean;
+}
+
+/**
+ * An idea's content without its program, for the guide panel and the home
+ * page's idea dialog. Callers supply the surrounding stack and
+ * docStylesClass.
+ */
+const IdeaGuideContent = ({ idea, inEditor = true }: IdeaGuideContentProps) => {
+  // Runtime value derived from the image reference.
+  const imagePadding = idea.image
+    ? getAspectRatioPadding(idea.image.asset._ref)
+    : undefined;
+  return (
+    <>
+      {inEditor && idea.image && (
+        <Box
+          width="600px"
+          maxWidth="100%"
+          className={imagePadding ? runtimeAspectRatioClass : undefined}
+          style={{ "--aspect-ratio-padding": imagePadding } as CSSProperties}
+        >
+          <ImageWithFallback
+            src={imageUrlBuilder.image(idea.image.asset).fit("max").url()}
+            ignoreFallback={navigator.onLine}
+            fallback={<OfflineImageFallback width={600} />}
+            alt=""
+            borderTopRadius="lg"
+          />
+        </Box>
+      )}
+      <DocumentationContextProvider
+        parentSlug={idea.slug.current}
+        toolkitType="ideas"
+        title={idea.name}
+        editorLinks={inEditor}
+      >
+        <DocumentationContent blocks={withoutCode(idea.content)} />
+      </DocumentationContextProvider>
+    </>
+  );
+};
+
+export default IdeaGuideContent;

src/documentation/ideas/idea-code.ts

@@ -0,0 +1,19 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { PortableText } from "../../common/sanity";
+import { Idea } from "./model";
+
+const isCode = (
+  block: PortableText[number]
+): block is { _type: "python"; main: string } => block._type === "python";
+
+/** The idea's program: its content's first code block. */
+export const ideaCode = (idea: Idea): string | undefined =>
+  idea.content?.find(isCode)?.main;
+
+/** The idea's content without its code, for the guide beside the editor. */
+export const withoutCode = (content: PortableText | undefined): PortableText =>
+  (content ?? []).filter((block) => !isCode(block));

src/e2e/app.ts

@@ -301,7 +301,7 @@ export class App {
     }
   }
 
-  async switchTab(tabName: "Files" | "API" | "Reference" | "Ideas") {
+  async switchTab(tabName: "Files" | "API" | "Reference" | "Ideas" | "Guide") {
     await this.page.getByRole("tab", { name: tabName }).click();
   }
 

src/e2e/home.test.ts

@@ -42,6 +42,29 @@ test.describe("home page", () => {
     await app.expectEditorContainText("from microbit import");
   });
 
+  test("opens an idea from its dialog as a project with its guide", async ({
+    app,
+    homePage,
+  }) => {
+    const ideaName = "Emotion badge";
+    await homePage.goto();
+    await homePage.page.getByRole("button", { name: ideaName }).click();
+    const dialog = homePage.page.getByRole("dialog");
+    await expect(
+      dialog.getByRole("heading", { name: ideaName, exact: true })
+    ).toBeVisible();
+
+    await dialog.getByRole("button", { name: "Create", exact: true }).click();
+
+    await expect(app.page).toHaveURL(appUrlPattern("project/guide"));
+    await app.expectProjectName(ideaName);
+    await expect(
+      app.page.getByRole("tab", { name: "Guide", selected: true })
+    ).toBeVisible();
+    await app.expectDocumentationTopLevelHeading(ideaName);
+    await app.expectEditorContainText("from microbit import");
+  });
+
   test("returns home from the editor with the project listed", async ({
     app,
     homePage,

src/fs/projects-db.ts

@@ -17,6 +17,8 @@ export interface ProjectMeta {
   name: string | undefined;
   /** Last modified or opened, for ordering by recency. */
   timestamp: number;
+  /** The idea the project was opened from, whose guide it shows. */
+  ideaSlug?: string;
 }
 
 /** A project as listed on the pages: its metadata plus what it contains. */

src/pages/HomePage.tsx

@@ -31,11 +31,11 @@ import { useSettings } from "../settings/settings";
 import { createProjectsPageUrl } from "../urls";
 import ActionCard from "./ActionCard";
 import DefaultPageLayout from "./DefaultPageLayout";
+import IdeaDialog from "./IdeaDialog";
 import ProjectIcon from "./ProjectIcon";
 import HomepageBanner from "./HomepageBanner";
 import HomepageFooter from "./HomepageFooter";
 import {
-  useCreateProject,
   useImportProjectFiles,
   usePageProjects,
   useProjectPageActions,
@@ -55,14 +55,27 @@ const HomePage = () => {
   const intl = useIntl();
   const [{ languageId }] = useSettings();
   const brand = useDeployment();
-  const createProject = useCreateProject("home");
+  const [selectedIdea, setSelectedIdea] = useState<{
+    slug: string;
+    title: string;
+  }>();
+  const selectIdea = useCallback(
+    (slug: string, title: string) => setSelectedIdea({ slug, title }),
+    []
+  );
   const importFiles = useImportProjectFiles();
   const handleDrop = useCallback(
     (files: File[]) => void importFiles(files, "drop"),
     [importFiles]
   );
   return (
     <DefaultPageLayout>
+      {selectedIdea && (
+        <IdeaDialog
+          {...selectedIdea}
+          onClose={() => setSelectedIdea(undefined)}
+        />
+      )}
       <FileDropTarget
         data-testid="home-drop-target"
         onFileDrop={handleDrop}
@@ -71,7 +84,7 @@ const HomePage = () => {
         <HomepageBanner />
         <ProjectsRow />
         <CarouselRow
-          carouselItems={createIdeaCards(intl, createProject)}
+          carouselItems={createIdeaCards(intl, selectIdea)}
           title={<FormattedMessage id="ideas-row-title" />}
           navigation
         />