Code samples & interactive demos

Showing code samples

Code samples that don't need an interactive demo next to it (e.g. just JS logic, without any UI) can use the <CodeSample> component. Pass in the raw code as the code prop, using backticks to delineate the start and end of the code block.

1  function trimAndTidy(code: string): string {
2      // remove any empty lines at start and end
3      code = code.replace(/^s*[\r\n]/g, '').replace(/s*[\r\n]$/g, '')
4  
5          // find common indentation and remove
6          const maxCommonTabs = code.split(\n').reduce((p, c) => c.search(/S|$/) < p ? c.search(/S|$/) : p, 99)
7          code = code.split('\n').map(v => v.substring(maxCommonTabs)).join('\n')
8  
9          return code
10      }

1  <CodeSample code={`
2      function trimAndTidy(code: string): string {
3          // remove any empty lines at start and end
4          code = code.replace(/^s*[\r\n]/g, '').replace(/s*[\r\n]$/g, '')
5  
6          // find common indentation and remove
7          const maxCommonTabs = code.split(\n').reduce((p, c) => c.search(/S|$/) < p ? c.search(/S|$/) : p, 99)
8          code = code.split('\n').map(v => v.substring(maxCommonTabs)).join('\n')
9  
10          return code
11      }
12  `} />

Showing interactive demos

Rendering code samples while also executing the code right next to it is tricky to do, and very reliant on what ecosystem (Vite, SWC, Next, whatever it might be) you're running on right now.

Instead, Starfield provides a <InteractiveDemo> component for both executing (actually "running" in react) code and presenting the raw syntax highlighted source code (which gets processed via <CodeSample>). The executed code is passed as children, whereas the source code is passed via the source prop. These two values must remain in sync; otherwise, users may see code that doesn't represent reality.

As a convention, any use of <InteractiveDemo> should be formatted like this:

1  <InteractiveDemo source={`
2      <Card>
3          Hello world
4      </Card>
5      `} centered={true}>
6      <Card>
7          Hello world
8      </Card>
9  </InteractiveDemo>

1. The source prop on InteractiveDemo must be the first prop, using backticks to delineate the source code, and with a newline immediately after the opening backtick, as well as a newline before the closing backtick (aside from any whitespace).
2. Any other props, such as centered, must be at least the second prop. They can be formatted any way necessary.
3. Both the source code within source and the actual children must be formatted the same way.

TODO

1. Ensure these values are synced up via a eslint rule. Show an error otherwise (we can't automatically sync these, because we don't know which of the two values are the intended ones). Be aware there may be differences because of escaping backticks and backslashes. (We could also assume the children demo is the "real" intended one.)
2. We could hook up dprint's formatter command to format the code, probably in one of our formatting commands.