NEBULA-1385: Add initialState to embedable sandbox based on config #6628

William010x · 2022-06-28T16:39:54Z

Context

The landing options/initial state (document, variables, headers) is not currently implemented in the embedded sandbox. This is being added in a studio-ui PR and embeddable-explorer PR
JIRA.

What changed

This PR passes the document, variables, headers that the user provides in ApolloServerPluginLandingPage to the embeddable sandbox

netlify · 2022-06-28T16:40:00Z

✅ Deploy Preview for apollo-server-docs canceled.

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`30ed632`
🔍 Latest deploy log	https://app.netlify.com/sites/apollo-server-docs/deploys/62bcd133c02866000916360b

codesandbox-ci · 2022-06-28T16:41:20Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 30ed632:

Sandbox	Source
Apollo Server Typescript	Configuration
Apollo Server	Configuration

changeset-bot · 2022-06-28T18:32:19Z

⚠️ No Changeset found

Latest commit: 30ed632

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

trevor-scheer · 2022-06-28T18:49:35Z

packages/apollo-server-core/src/plugin/landingPage/default/index.ts

@@ -142,6 +142,7 @@ id="embeddableSandbox"
    target: '#embeddableSandbox',
    initialEndpoint,
    includeCookies: ${config.includeCookies ?? 'false'},
+    initialState: ${config},


initialState should only have 3 properties, maybe better to be explicit about passing only what it expects?

Suggested change

initialState: ${config},

initialState: ${{

document: config.document ?? undefined,

variables: config.variables ?? undefined,

headers: config.headers ?? undefined,

}},

@William010x and I identified that you can't just drop an object into a string template like this (you get an [object Object]), so it's now JSON.stringify()ed.

Additionally, I'll mention that the type of initialState is now a string and it'll need to be JSON.parse()d in the constructor to be useful.

With the substitutions in the template string (${JSON.stringify(expression)}), it actually removes the quotes surrounding the JSON object string, so the returned HTML string will look something like:

<script> var initialEndpoint = window.location.href; new window.EmbeddedSandbox({ target: '#embeddableSandbox', initialEndpoint, includeCookies: false, initialState: {"document":"query test { id }","variables":{"v":"1"},"headers":{"h":"2"}}, }); </script>

I tested this HTML string with the Embedded Sandbox and it seems to work without needing to JSON.parse().

Alternatively, doing something like these (similar to the embeddedExplorerHTML) also works

<script> var initialEndpoint = window.location.href; var state = ${JSON.stringify({ document: config.document ?? undefined, variables: config.variables ?? undefined, headers: config.headers ?? undefined, })}; new window.EmbeddedSandbox({ target: '#embeddableSandbox', initialEndpoint, includeCookies: ${config.includeCookies ?? 'false'}, initialState: state, }); </script>

<script> var initialEndpoint = window.location.href; var state = ${JSON.stringify({ document: config.document ?? undefined, variables: config.variables ?? undefined, headers: config.headers ?? undefined, })}; new window.EmbeddedSandbox({ target: '#embeddableSandbox', initialEndpoint, includeCookies: ${config.includeCookies ?? 'false'}, initialState: { ...state }, }); </script>

I'll look into adding proper unit tests for this though!

Neat, yeah if it's not adding quotes like I expected then you should be all set!

trevor-scheer

This LGTM.

A couple last notes:

The variables type as it's written in the docs change doesn't allow for a nested object. I wish we had a good "one-liner" type to put there, but we really don't. The recursive nature of this type requires writing one type in terms of itself. Options which I'd consider an improvement but still not ideal: Record<string, string | Record>, Record<string, any>.
We sadly have no unit tests for the html rendered by the plugin. It would be nice to see new tests that reflect this change. I won't block you on this, but I'd be happy to work with you to get a few in place. Otherwise, opening a follow-up issue would be the next best option so it's at least not forgotten.

mayakoneval

wow thank you for the tests 🙏

mayakoneval · 2022-06-29T17:06:02Z

docs/source/api/plugin/landing-pages.md

@@ -106,6 +106,52 @@ By default, the landing page displays a footer that links to the documentation t
 <tr>
 <td>

+###### `document`


do these get passed through to sandbox in the regular landing page? We were just missing them before but they are supported right?

yup! they were always in ApolloServerPluginLandingPageDefaultBaseOptions, but just not mentioned in the docs

mayakoneval · 2022-06-29T17:06:10Z

docs/source/api/plugin/landing-pages.md

+</td>
+<td>
+
+A GraphQL document (eg, query or mutation) to populate in the Studio Explorer's editor on load.


Suggested change

A GraphQL document (eg, query or mutation) to populate in the Studio Explorer's editor on load.

A GraphQL document (eg, query or mutation) to populate in the Studio Sandbox Explorer's editor on load.

Do we still want to add this? This API applies to both sandbox and explorer, right?

This is the local dev docs, so they will only ever lead to sandbox afaict

no strong opinion tho!

trevor-scheer

Thanks for adding these tests! I'm a lot more confident in the HTML we're expecting now 👍

A few minor comments mostly about structure, otherwise this is great.

Would you please add an entry to the vNEXT section of CHANGELOG.md? A small description with a link to your PR is great, you can look to the others for example.

trevor-scheer · 2022-06-29T17:06:17Z

packages/apollo-server-core/src/__tests__/landingPageConfigHTML.test.ts

+
+describe('Landing Page Config HTML', () => {
+  it('for embedded explorer with document, variables, headers and displayOptions provided', () => {
+    const config = {


If you define config as the actual options type (ApolloServerPluginEmbeddedLandingPageProductionDefaultOptions) you won't need the type casts below. Right now TS infers the type of the object (with docsPanelState and theme as string, which is not narrow enough). But if you tell it the object's type, it'll correctly give you an error if you used an incorrect string for those properties.

packages/apollo-server-core/src/__tests__/landingPageConfigHTML.test.ts

CHANGELOG.md

trevor-scheer

LGTM! We'll want to port these changes over to the version-4 branch as well (ignoring any docs changes). If you have time for that, that would be great. If not, you can open an issue for it and assign to me.

Co-authored-by: Trevor Scheer <trevor.scheer@gmail.com>

trevor-scheer · 2022-07-05T20:06:12Z

@glasser can you review in post? I was thinking I'd release this, but since you're back tomorrow I'll hold off in case you want to recommend any follow-ups.

glasser

so just to check — this was basically a bug, where the TS types had these parameters but in one particular case (embedded) we weren't passing them through?

glasser · 2022-07-06T17:40:09Z

docs/source/api/plugin/landing-pages.md

@@ -228,7 +274,7 @@ If you omit this, the Explorer initially loads an example query based on your sc

 ###### `variables`

-`Record<string, string>`
+`Record<string, string | Record>`


maybe the right hand side here should just be unknown or any? i mean you can put numbers and bools and lists in variables...

This ticket was for a new config (initialState) recently added to the embedded-explorer repo. These parameters (document, variables and headers) already existed, but yeah they weren't used or passed through for embedded Sandbox.

The parameters were added and the docs were updated accordingly

Added this change in #6656

…sts (#6633) Allow configuration of embeddable sandbox initial state. The initial `document`, `variables`, and `headers` can now be provided to the plugin config to populate these values on page load. Ported for AS4 from #6628

Add initialState to embedable sandbox based on config

e347e53

Update docs to include new supported API

0df5c73

trevor-scheer requested changes Jun 28, 2022

View reviewed changes

Only add specific properties to initial state

c3d22e4

William010x requested a review from trevor-scheer June 28, 2022 20:39

trevor-scheer approved these changes Jun 28, 2022

View reviewed changes

William010x added 3 commits June 28, 2022 18:11

Update type for variables in API docs

60ebbc3

Add unit tests for landing page config HTML

62019bc

Make code prettier

719587c

mayakoneval approved these changes Jun 29, 2022

View reviewed changes

trevor-scheer requested changes Jun 29, 2022

View reviewed changes

Code review comments

6a7d5a0

William010x requested a review from trevor-scheer June 29, 2022 18:49

trevor-scheer reviewed Jun 29, 2022

View reviewed changes

CHANGELOG.md Outdated Show resolved Hide resolved

trevor-scheer approved these changes Jun 29, 2022

View reviewed changes

Update CHANGELOG.md

30ed632

Co-authored-by: Trevor Scheer <trevor.scheer@gmail.com>

William010x mentioned this pull request Jun 29, 2022

NEBULA-1385: Add initial state to embeddable sandbox and HTML unit tests #6633

Merged

trevor-scheer merged commit 07639bb into apollographql:main Jul 5, 2022

glasser reviewed Jul 6, 2022

View reviewed changes

William010x mentioned this pull request Jul 8, 2022

NEBULA-1385: Sandbox initial state cleanup #6656

Merged

trevor-scheer mentioned this pull request Jul 11, 2022

Release 3.10.0 #6662

Merged

github-actions bot locked as resolved and limited conversation to collaborators Mar 16, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

NEBULA-1385: Add initialState to embedable sandbox based on config #6628

NEBULA-1385: Add initialState to embedable sandbox based on config #6628

William010x commented Jun 28, 2022

netlify bot commented Jun 28, 2022 •

edited

codesandbox-ci bot commented Jun 28, 2022 •

edited

changeset-bot bot commented Jun 28, 2022 •

edited

trevor-scheer Jun 28, 2022

trevor-scheer Jun 28, 2022

William010x Jun 28, 2022

William010x Jun 28, 2022

trevor-scheer Jun 28, 2022

trevor-scheer left a comment •

edited

mayakoneval left a comment

mayakoneval Jun 29, 2022

William010x Jun 29, 2022

mayakoneval Jun 29, 2022

William010x Jun 29, 2022

mayakoneval Jun 30, 2022

mayakoneval Jun 30, 2022

trevor-scheer left a comment

trevor-scheer Jun 29, 2022

trevor-scheer left a comment

trevor-scheer commented Jul 5, 2022

glasser left a comment

glasser Jul 6, 2022

William010x Jul 8, 2022 •

edited

William010x Jul 8, 2022

-    initialState: ${config},
+    initialState: ${{
+      document: config.document ?? undefined,
+      variables: config.variables ?? undefined,
+      headers: config.headers ?? undefined,
+    }},

	A GraphQL document (eg, query or mutation) to populate in the Studio Explorer's editor on load.
	A GraphQL document (eg, query or mutation) to populate in the Studio Sandbox Explorer's editor on load.

NEBULA-1385: Add initialState to embedable sandbox based on config #6628

NEBULA-1385: Add initialState to embedable sandbox based on config #6628

Conversation

William010x commented Jun 28, 2022

Context

What changed

netlify bot commented Jun 28, 2022 • edited

✅ Deploy Preview for apollo-server-docs canceled.

codesandbox-ci bot commented Jun 28, 2022 • edited

changeset-bot bot commented Jun 28, 2022 • edited

⚠️ No Changeset found

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

trevor-scheer left a comment • edited

Choose a reason for hiding this comment

mayakoneval left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

trevor-scheer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

trevor-scheer left a comment

Choose a reason for hiding this comment

trevor-scheer commented Jul 5, 2022

glasser left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

William010x Jul 8, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

netlify bot commented Jun 28, 2022 •

edited

codesandbox-ci bot commented Jun 28, 2022 •

edited

changeset-bot bot commented Jun 28, 2022 •

edited

trevor-scheer left a comment •

edited

William010x Jul 8, 2022 •

edited