Proposal for an improved EditorPageWithStorybookPreview to better mock actual implementation that uses iFrames #2543

SonicScrewdriver · 2025-05-30T22:16:59Z

Summary:

[neverending-story-2] New Editor Page that properly implements iframe communication

NOTE: THIS IS A DRAFT PR and still needs polish / cleanup.

github-actions · 2025-05-30T22:18:16Z

Size Change: 0 B

Total Size: 481 kB

ℹ️ View Unchanged

Filename	Size
`packages/kas/dist/es/index.js`	20.7 kB
`packages/keypad-context/dist/es/index.js`	1 kB
`packages/kmath/dist/es/index.js`	5.98 kB
`packages/math-input/dist/es/index.js`	98.6 kB
`packages/math-input/dist/es/strings.js`	1.61 kB
`packages/perseus-core/dist/es/index.js`	21.2 kB
`packages/perseus-editor/dist/es/index.js`	91.3 kB
`packages/perseus-linter/dist/es/index.js`	7.14 kB
`packages/perseus-score/dist/es/index.js`	9.25 kB
`packages/perseus-utils/dist/es/index.js`	403 B
`packages/perseus/dist/es/index.js`	208 kB
`packages/perseus/dist/es/strings.js`	7.56 kB
`packages/pure-markdown/dist/es/index.js`	1.22 kB
`packages/simple-markdown/dist/es/index.js`	6.72 kB

_{compressed-size-action}

SonicScrewdriver · 2025-05-30T22:18:17Z

packages/perseus-editor/src/__stories__/editor-page-with-storybook-preview.tsx

 const onChangeAction = action("onChange");

 function EditorPageWithStorybookPreview(props: Props) {
    const [previewDevice, setPreviewDevice] =
-        React.useState<DeviceType>("phone");
+        React.useState<DeviceType>("desktop");


Upstream defaults to desktop, so I figured we should too.

github-actions · 2025-05-30T22:18:51Z

npm Snapshot: Published

Good news!! We've packaged up the latest commit from this PR (4337311) and published it to npm. You
can install it using the tag PR2543.

Example:

pnpm add @khanacademy/perseus@PR2543

If you are working in Khan Academy's frontend, you can run the below command.

./tools/bump_perseus_version.ts -t PR2543

If you are working in Khan Academy's webapp, you can run the below command.

./dev/tools/bump_perseus_version.js -t PR2543

ivyolamit · 2025-06-02T18:37:25Z

packages/perseus-editor/src/__stories__/editor-page-with-storybook-preview.tsx

-
-    const apiOptions = props.apiOptions ?? {
-        isMobile: false,
+    const isMobile = previewDevice === "phone" || previewDevice === "tablet";


SonicScrewdriver · 2025-06-02T19:47:17Z

There's a failing linter here, but I want to confirm with the team about whether and/or where we should be declaring the globals before fixing it!

SonicScrewdriver · 2025-06-05T21:43:48Z

packages/perseus-editor/src/__stories__/editor-page-with-storybook-preview.tsx

+    interface Window {
+        iframeDataStore: Record<string, any>;
+    }
+}


Temporary location while I determine the right location for this, if there is one.

I think the right spot is to get rid of this as a way to send data between the host page and the iframe. Ideally, this should pass the data along with the postMessage() call. Not asking you to do that now, but mid-term, that'd be how we fix this.

jeremywiebe

Love that you've started into this! I have some comments but generally am very happy to see you pushing into cleaning this up and enabling it in Storybook!

jeremywiebe · 2025-06-06T17:41:25Z

packages/perseus-editor/src/__stories__/editor-page-with-storybook-preview.tsx

+    interface Window {
+        iframeDataStore: Record<string, any>;
+    }
+}


I think the right spot is to get rid of this as a way to send data between the host page and the iframe. Ideally, this should pass the data along with the postMessage() call. Not asking you to do that now, but mid-term, that'd be how we fix this.

jeremywiebe · 2025-06-06T17:45:06Z

packages/perseus-editor/src/__stories__/editor-page-with-storybook-preview.tsx

+                frameSource="/iframe.html?id=perseuseditor-perseus-frame--frame&viewMode=story"
+                previewURL="/iframe.html?id=perseuseditor-perseus-frame--frame&viewMode=story"


Does this leverage a Storybook iframe feature? I'd be mildly concerned that this could break if someone re-names a story. We could also just put a container page in the Vite static asset directory if you think that's more resilient to changes.

I didn't need to leverage much of storybook at all! I tried to avoid too much storybook middleware as it seemed to diverge a little from how we would set it up in production.

This currently links to the Perseus Frame Component's story in "story" mode (AKA the full page view). I think the vite static asset directory could make a lot of sense, as it's definitely possible for this to break if someone moves the Perseus Frame component story. While I don't think it's likely that someone will rename the story, I think the static asset directory is a good way to keep us safe. :) I'll look into getting that working!

jeremywiebe · 2025-06-06T17:47:37Z

packages/perseus-editor/src/__stories__/editor-page.stories.tsx

+export const EditorWithDropdownWidget: Story = {
+    name: "Editor with Dropdown Widget",
+    args: {
+        question: {
+            content:
+                "Which of the following is a prime number?\n\n[[☃ dropdown 1]]",
+            images: {},
+            widgets: {
+                "dropdown 1": {
+                    type: "dropdown",
+                    graded: true,
+                    options: {
+                        choices: [
+                            {
+                                content: "Choose an answer",
+                                correct: false,
+                            },
+                            {
+                                content: "4",
+                                correct: false,
+                            },
+                            {
+                                content: "6",
+                                correct: false,
+                            },
+                            {
+                                content: "7",
+                                correct: true,
+                            },
+                            {
+                                content: "8",
+                                correct: false,
+                            },
+                        ],
+                        placeholder: "Choose an answer",
+                        static: false,
+                    },
+                    version: {
+                        major: 0,
+                        minor: 0,
+                    },
+                },
+            },
+        },
+        hints: [
+            {
+                content:
+                    "A prime number is a number greater than 1 that has no positive divisors other than 1 and itself.",
+                images: {},
+                widgets: {},
+            },
+        ],
+    },
+    parameters: {
+        docs: {
+            description: {
+                story: "Editor with dropdown widget to test preview frame communication and height adjustments.",
+            },
+        },
+    },
 };


I think you can also get documentation for a story by putting a JSDoc comment on the story itself. It's a little more compact and, I think, more natural to find for future maintenance.

Suggested change

export const EditorWithDropdownWidget: Story = {

name: "Editor with Dropdown Widget",

args: {

question: {

content:

"Which of the following is a prime number?\n\n[[☃ dropdown 1]]",

images: {},

widgets: {

"dropdown 1": {

type: "dropdown",

graded: true,

options: {

choices: [

{

content: "Choose an answer",

correct: false,

},

{

content: "4",

correct: false,

},

{

content: "6",

correct: false,

},

{

content: "7",

correct: true,

},

{

content: "8",

correct: false,

},

],

placeholder: "Choose an answer",

static: false,

},

version: {

major: 0,

minor: 0,

},

},

},

},

hints: [

{

content:

"A prime number is a number greater than 1 that has no positive divisors other than 1 and itself.",

images: {},

widgets: {},

},

],

},

parameters: {

docs: {

description: {

story: "Editor with dropdown widget to test preview frame communication and height adjustments.",

},

},

},

};

/**

* Editor with dropdown widget to test preview frame communication and

* height adjustments.

*/

export const EditorWithDropdownWidget: Story = {

name: "Editor with Dropdown Widget",

args: {

question: {

content:

"Which of the following is a prime number?\n\n[[☃ dropdown 1]]",

images: {},

widgets: {

"dropdown 1": {

type: "dropdown",

graded: true,

options: {

choices: [

{

content: "Choose an answer",

correct: false,

},

{

content: "4",

correct: false,

},

{

content: "6",

correct: false,

},

{

content: "7",

correct: true,

},

{

content: "8",

correct: false,

},

],

placeholder: "Choose an answer",

static: false,

},

version: {

major: 0,

minor: 0,

},

},

},

},

hints: [

{

content:

"A prime number is a number greater than 1 that has no positive divisors other than 1 and itself.",

images: {},

widgets: {},

},

],

},

};

jeremywiebe · 2025-06-06T17:48:16Z

packages/perseus-editor/src/__stories__/editor-page.stories.tsx

+        docs: {
+            description: {
+                component:
+                    "Perseus EditorPage with built-in preview functionality using Storybook iframe. ",


Where does this description show up when it's done on the Meta object?

Oh weird. These were showing up locally for me on a "docs" page added for the relevant folders, but they no longer do after rebasing the newest changes from main into this branch. Did we turn off the docs feature when upgrading Storybook?

You can see the docs on the storybook publish for this PR:
https://650db21c3f5d1b2f13c02952-ejozbvanyy.chromatic.com/?path=/docs/perseuseditor-perseus-frame--docs
https://650db21c3f5d1b2f13c02952-ejozbvanyy.chromatic.com/?path=/docs/perseuseditor-editorpage--docs

Here's one we had from before:
https://650db21c3f5d1b2f13c02952-ejozbvanyy.chromatic.com/?path=/docs/perseus-components-number-input--docs

We didn't turn it off as far as I know, but I did upgrade us to Storybook v9 and I wonder if that changed things! I'll look into that. Fix: #2565

However, I still think it'd be better to use JSDoc comments as suggested.. they show up the same way and (IMHO at least) are much more natural than figuring out how to add the right combination of docs parameters etc. :)

See: https://storybook.js.org/docs/api/doc-blocks/doc-block-description#writing-descriptions

jeremywiebe · 2025-06-06T17:50:59Z

packages/perseus-editor/src/__stories__/perseus-frame-component.tsx

+ *
+ * @returns A PerseusFrameComponent that renders the content of the EditorPage.
+ */
+const PerseusFrameComponent = () => {


This is fantastic that you reverse-engineered this info. Ideally, I'd love to extract the same component out of webapp and move it into Perseus (so that we'd have both sides of the communication channel in Perseus) and then eventually refactor to use the same component in the stories as in production. Future work, but this definitely paves the way! Thanks.

@third

## Summary: @third [noticed](#2543 (comment)) that our Storybook docs weren't working anymore. This is a regression that happened during the Storybook v9 upgrade. This PR fixes autodocs (and enables the TOC feature which is a nice little addition). Issue: "none" ## Test plan: `pnpm install; pnpm start` -> stories have a "Docs" entry again Author: jeremywiebe Reviewers: SonicScrewdriver Required Reviewers: Approved By: SonicScrewdriver Checks: ✅ 8 checks were successful Pull Request URL: #2565

… communication

…ybookPreview to better mock actual implementation

…m implementation variances

…ot particularly necessary to call out

SonicScrewdriver self-assigned this May 30, 2025

SonicScrewdriver added the olc-5.0.b3e8b label May 30, 2025

SonicScrewdriver commented May 30, 2025

View reviewed changes

SonicScrewdriver changed the title ~~docs(changeset): Overhaul of EditorPageWithStorybookPreview to better mock actual implementation~~ docs(changeset): Overhaul of EditorPageWithStorybookPreview to better mock actual implementation using iFrames May 30, 2025

SonicScrewdriver changed the title ~~docs(changeset): Overhaul of EditorPageWithStorybookPreview to better mock actual implementation using iFrames~~ Proposal for an improved EditorPageWithStorybookPreview to better mock actual implementation that uses iFrames May 31, 2025

ivyolamit reviewed Jun 2, 2025

View reviewed changes

SonicScrewdriver commented Jun 5, 2025

View reviewed changes

jeremywiebe reviewed Jun 6, 2025

View reviewed changes

jeremywiebe mentioned this pull request Jun 6, 2025

[Storybook] Fix docs (and enable TOC on stories) #2565

Merged

SonicScrewdriver force-pushed the neverending-story-2 branch from a0d25bf to 63a9646 Compare June 10, 2025 16:44

SonicScrewdriver added 9 commits July 8, 2025 12:06

[neverending-story-2] New Editor Page that properly implements iframe…

43bf3fc

… communication

[neverending-story-2] docs(changeset): Overhaul of EditorPageWithStor…

3b132a4

…ybookPreview to better mock actual implementation

[neverending-story-2] Cleaning up implementation and checking upstrea…

5e17aac

…m implementation variances

[neverending-story-2] comment cleanup

b7d49a6

[neverending-story-2] No need to over complicate window

0701dee

[neverending-story-2] Clean up story comments

725b4c1

[neverending-story-2] cleanup as these aren't needed

99d851f

[neverending-story-2] clean up story as much of this was removed or n…

2933948

…ot particularly necessary to call out

[neverending-story-2] updating to new source

4337311

SonicScrewdriver force-pushed the neverending-story-2 branch from 63a9646 to 4337311 Compare July 8, 2025 19:06

		frameSource="/iframe.html?id=perseuseditor-perseus-frame--frame&viewMode=story"
		previewURL="/iframe.html?id=perseuseditor-perseus-frame--frame&viewMode=story"

Proposal for an improved EditorPageWithStorybookPreview to better mock actual implementation that uses iFrames #2543

Are you sure you want to change the base?

Proposal for an improved EditorPageWithStorybookPreview to better mock actual implementation that uses iFrames #2543

Uh oh!

Conversation

SonicScrewdriver commented May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary:

Uh oh!

github-actions bot commented May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

npm Snapshot: Published

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SonicScrewdriver commented Jun 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jeremywiebe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

SonicScrewdriver commented May 30, 2025 •

edited

Loading

github-actions bot commented May 30, 2025 •

edited

Loading

github-actions bot commented May 30, 2025 •

edited

Loading