Introducing Starchart Studio

From one, many

The biggest “bit” of a story tool is having two or more views of the same story: the fully-featured story page and a stand-alone iframed page for the component to sit in isolation. I wanted to keep basic component stories to a single file, so I settled on Astro’s MDX integration as a base for stories. This allows developers to write Markdown documentation while also exporting an object with configuration, including a component that can be passed around and rendered. When globbed, they come with a bunch of useful properties, too, which can be used to build out robust systems if not used directly to generate pages.

One of properties is file. When combined with getStaticPaths and dynamic params in filenames, you can create multiple related pages from a single input. Because this function is run server-side from Node, you can use Node built-ins without worry, like path. I grab the basename of the file, and generate two entries in getStaticPaths, one for the isolated component, and one for the fully-featured story page. I can even have different properties that get passed to those components (from Astro.props) from this, making it possible to further change exactly what’s available on the page. This includes signaling if the page should be inline and, if so, choosing a different layout. The main Starchart.astro component basically exists to do just that:

{
  story.inline ? (
    <InlineStory
      Component={story.Component}
      props={story.properties}
      slug={story.slug}
    />
  ) : (
    <BlockStory
      Component={story.Component}
      {...story.properties}
      chart={chart}
    />
  )
}

chart, in the above code sample, is actually the list of all components, and their URLs, ready to be made into nav of some sort. Getting this from an individual page is kinda tricky; getStaticPaths runs in isolation so it’s hard to capture the glob and reuse it. When you use Starchart’s getStaticPaths function, you’re actually calling a method on a singleton class instance; that lets me save the results to a property and recall them during other function calls, which you make to set up the story. As a side note, a singleton class to hold state is a pattern I find myself using quite often when with JS modules.

Dealing with state

With this basic setup and the built-in component model, I had prop-only components rendering! Inputs couldn’t be changed, but I considered that a fair tradeoff considering they’re designed to not be once loaded. But sometimes you have state, and that posed problems.

I knew developers would need to define functions to connect form updates to their state management of choice, but Astros’ define:vars for passing variables into script tags stringifies everything, so no functions allowed. While I maybe could work around this with an exec, it was strike one. Next, the system works using dynamic tags to render the component, but dynamic tags can’t be hydrated. This unfortunately took me a while of spinning to realize; as it’s only mentioned under dynamic tags and not in the hydration docs, but I got there. That was strike two. One more and this whole thing collapses. But fortunately, Astro’s component model, while a hinderance here, actually saved me.

See, Astro is all about mixing islands of interactivity with static content. This means that you can make a static Astro component that has hydrated components in it, and that works fine. Because that component doesn’t need to be hydrated, it can then be dynamically loaded. And thus, a simple, if slightly inelegant, solution emerged: hydrated components need to be wrapped in a static component. We’ll pass you all the props you need to render your component, just swap the direct component call in your story for your wrapped one. This also provides a clear place to add Starchart-specific code for managing state and events without coupling it into your production component.

The last bit is pretty straight-forward: the isolated component lives in an iframe, so postmessage to send data across that border, with a couple of custom events and some developer-facing helper functions to manage it all for them, so they just need to write how their state changes when it comes it.