feat(daffio, docs): enable rendering of example code output in design docs

[damienwebdev]

PR Checklist

• Commit message follows our contributing guidelines
• Tests added/updated (for bug fixes/features)
• Documentation added/updated (for bug fixes/features)

PR Type

• Bug fix
• Feature
• Style update
• Refactor
• Test
• Build
• CI
• Docs
• Performance
• Other (please describe)

Current behavior

We have no way to render code output inside of markdown content in daff.io.

Fixes: #2903, fixes: #2905

New behavior

We can now render design examples (as well as other examples) in daff.io

Breaking change?

• Yes
• No

Additional context

This supersedes

• feat(daffio): add design examples to daff.io #3727
• feat(design-land): add autogenerated color palettes #4242

[damienwebdev]

TODO:

• Find all existing readme files with a design-land-example and make them work
• Make initial render of the example viewer work on design components (daff-tabs interaction)
• Make files for design-examples load
• Add a mode for "simple" examples like color palette guides.

still TODOs

[griest024]

@damienwebdev

Make initial render of the example viewer work on design components (daff-tabs interaction)

Does this refer to SSR?

[griest024]

There's still a slight render issue of the example previews in SSR but I don't think that should block this PR. I think we should piece this up and merge it.

[xelaint]

@griest024 the color palette example is not visible on /docs/design/foundations/color

[griest024]

@griest024 the color palette example is not visible on /docs/design/foundations/color

@xelaint good catch, fixed

[xelaint]

@griest024 Is there a way to prevent these from being displayed?

// Base colors
/// @access private
$white: #ffffff;
/// @access private
$black: #070707;
// need to deprecate
/// @access private
$error: #dd0000;

[griest024]

@griest024 Is there a way to prevent these from being displayed?

// Base colors
/// @access private
$white: #ffffff;
/// @access private
$black: #070707;
// need to deprecate
/// @access private
$error: #dd0000;

There seem to be 3 options:

1. if we only ever want to render maps, we can filter out vars that are just simple color values
2. we can filter out specifically those variables by name, but that will have to be hardcoded in the component
3. add a doc tag that will indicate the var should be excluded from either the docsgen or the rendering

[xelaint]

@griest024 Is there a way to prevent these from being displayed?

// Base colors
/// @access private
$white: #ffffff;
/// @access private
$black: #070707;
// need to deprecate
/// @access private
$error: #dd0000;

There seem to be 3 options:

1. if we only ever want to render maps, we can filter out vars that are just simple color values
2. we can filter out specifically those variables by name, but that will have to be hardcoded in the component
3. add a doc tag that will indicate the var should be excluded from either the docsgen or the rendering

Can be just remove the switch and case here to just display MAP?

@switch (palette.context.parsedValue.type) {
				@case (COLOR) {
					<div style="background-color: {{palette.context.parsedValue.parsed}};">
						<span class="daff-docs-color__hex">{{palette.context.parsedValue.raw}}</span>
						<span class="daff-docs-color__hue">{{palette.context.parsedValue.parsed}}</span>
					</div>
				}
				@case (MAP) {
					@if (palette.context.parsedValue.parsed) {
						@for (shade of palette.context.parsedValue.parsed | keyvalue | daffDocsPaletteShadeSort; track shade.key) {
							<div style="background-color: {{shade.value}};">
								<span class="daff-docs-color__hex">{{shade.key}}</span>
								<span class="daff-docs-color__hue">{{shade.value}}</span>
							</div>
						}
					}
				}
			}

[griest024]

@xelaint yes, that's basically option 1. If you're sure that we'll only ever want to render maps, feel free to go ahead and make that change

[xelaint]

@griest024 Done. Can you review? Should be good to merge if all looks good.