embedded api

[mbostock]

TODO:

• Generate embed script (e.g., /chart.js) during preview
• Generate embed script (e.g., /chart.js) during build via embedPaths dynamicPaths
• Fix build so that module rendering applies content-hashed aliases (via resolvers)
• Fix build so that assets & imports of embedded modules are included
• Fix build so that the tree output is relevant for embedded modules
• Fix messy types in build
• Embed script script takes precedence over page (e.g., /chart.js.md)
• Ignore pre-empted pages (/chart.js.md given /chart.js) in the sidebar & pager
• Compute transitive static imports for preloading
• Inline file registration to avoid ordering problem
• Allow CORS during preview
• Restrict CORS preview to specific origins
• Documentation
• Tests

Fixes #1084.
Fixes #1583.

[mbostock]

Would be simpler to just invert the precedence and have /chart.js.md take precedence over /chart.js? I don’t think it matters which one we choose; we just have to pick one, so we should pick whatever’s easier for us. Edit: There is a philosophical reason to give /chart.js precedence which is that it is an exact match and more specific than /chart.js.md, and hence we should stay the course. Further edit: I think we could just disallow /chart.js.md entirely and require that pages only have a single extension. That restriction should simplify things and feels reasonable and more forward-looking.

[mbostock]

Boo, one of our tests has a page sub/page1..10.md which already violates the double extension rule, suggesting that we should allow pages to have double extensions but fix the precedence issue… I need to think more.

[Fil]

This is fantastic! and I couldn't find how to break it 👍
Adding a few suggestions for the documentation.

[Fil]

Suggested change

	const sql = postgres(); // Note: uses psql environment variables
	const sql = postgres(); // See https://github.com/porsager/postgres to set up the environment variables

[mbostock]

This comment exists in multiple places. (I’ve been copying it every time I use Postgres.js.) I’m not sure we need it. The link from the text is probably enough, but I did think it was useful to mention that it depends on environment variables.

[Fil]

I had to test this and log every line of it! it works :)

[Fil]

Speaking of which, an example of a responsive chart (that reruns to adapt to the container's width) might be welcome here, or separately in a full-blown example.

[mbostock]

Yes. That should just be the resize helper, as normal.

[Fil]

This is a bit too allusive. It might be worth developing an example of how to use observable.params.id within chart.js so that it corresponds to the requested product and displays data from the corresponding (parametrized) data loader. The example can live as a stand-alone example app, and we'd just add a link here.

[mbostock]

Yeah, I didn’t want to duplicate the documentation of parameterized routes here, but I also wanted to allude to it, since it feels like a natural question (how would I show multiple views?) with perhaps a surprising answer (the views bake-in their data rather than expecting it to be passed in as a prop from the host app).