sdc_showcase

SDC Showcase generates browsable preview pages for your Single Directory Components (SDCs). No manual stories, no hand-written fixtures. Enable the module and every component gets a detail page with a schema reference and rendered variations.

Components render with the site's front-end theme, so the showcase matches production.

What does it do?

• Auto-discovers all SDC components across your installed themes and modules
• Generates realistic props from JSON Schema. Strings become lorem ipsum, enums and booleans are swept through every value, numbers respect min/max bounds, URIs become valid URLs.
• Builds a variation matrix for each component: baseline, enum/boolean sweeps, edge cases (empty, long, zero, null), and hand-crafted combinations
• Collections compose multiple components into full page layouts with repeat, vary, and nested slot content
• Entity directives define mock Drupal entities in YAML (media, nodes, files) that are created in-memory and never saved to the database
• Visual regression ready. Drush commands output every showcase URL for piping into BackstopJS, Percy, Playwright, or any screenshot tool.

Who is it for?

• Front-end developers building SDC component libraries who want to see every prop combination without writing stories
• QA teams who need to inspect components across variants, edge cases, and breakpoints
• CI pipelines that run visual regression tests against stable, deterministic URLs
• Site builders who want a browsable catalogue of available components

How does it compare to other tools?

There are a few existing options for previewing SDC components. They each have a different focus.

Storybook (CL Server) runs a Node.js process alongside Drupal and renders components in Storybook's UI. You get Storybook's addon ecosystem (accessibility audits, viewport switching, controls panel), but you need a Node build toolchain, a .stories.js or .stories.twig file per component, and components render outside Drupal's pipeline. Preprocessors, alter hooks, and theme inheritance don't apply. What you see in Storybook may not match the live site.

SDC Component Library is a lighter-weight Drupal-native alternative to Storybook. It auto-discovers SDC components and renders previews at /components using .story.twig files. It's simpler to set up than Storybook (no Node.js), but you still need to write a story file for each component you want to preview, and it only shows one preview per story. There's no automatic variation generation or edge case testing, and no Drush tooling for extracting stable per-variation URLs for CI pipelines.

UI Patterns is primarily about integrating components with Drupal's layout and field systems: mapping SDC props to entity fields, layout builder regions, and views. It includes a pattern library page, but that's not its focus. The library shows one or two examples per component with hand-written sample data. It doesn't auto-generate variations, sweep enums, test edge cases, or support visual regression workflows.

SDC Showcase is built specifically for component QA and visual testing:

• Zero story authoring. Variations are generated from the JSON Schema you've already written. No story files to write or maintain. Enable the module and every component has a preview page.
• Renders inside Drupal. Components go through the real rendering pipeline with your theme, preprocessors, libraries, and alter hooks. No Node.js process, no separate dev server.
• Automatic edge case coverage. The sweep layer tests every enum value and boolean state. The edge layer tests empty strings, long text, zero, negative numbers, and missing optional props. These are the cases that break templates in production and that nobody writes stories for.
• Deterministic URLs for CI. Every variation has a stable, seedable URL. drush ssc:urls --include-variations outputs them all. No browser automation needed to navigate a UI.
• No build toolchain. It's a Drupal module. composer require, drush en, done.
• Entity-aware. The _entity directive creates real (unsaved) Drupal entities in YAML for props that expect media objects, node references, or file entities. Other tools require you to either create content in the database or mock the rendering yourself.

Tip

These tools aren't mutually exclusive. If you need Storybook's addon ecosystem, SDC Component Library's simplicity, or UI Patterns' layout builder integration, use them. SDC Showcase is for when you want full variation coverage that renders in production context, without maintaining story files.

Showcase pages

• Index page (/sdc-showcase) lists all discovered components grouped by provider, with links to collections
• Component page (/sdc-showcase/{provider}--{name}) shows the schema reference table and all variations rendered inline or in iframes
• Variation page (/sdc-showcase/{provider}--{name}/{variation}) renders a single variation in isolation, useful for iframe embedding or screenshots
• Collection page (/sdc-showcase/collection/{id}) renders a multi-component page layout

Automatic variation generation

The showcase reads your component's JSON Schema and generates variations:

• Baseline gives you one variation with all props at their defaults or generated values
• Sweep produces one variation per value for every enum and boolean prop. A component with 3 colour variants and a dark-mode toggle gets 5 sweep variations automatically.
• Edges produce boundary values to stress-test templates: empty strings, very long text, zero, negative numbers, and "without" variations for every optional prop

Tip

The better your JSON Schema, the better the output. Components with enum, minimum/maximum, examples, and default values produce realistic previews out of the box.

Override files

You can customise any component's showcase with a co-located YAML file:

components/
  bold-statement/
    bold-statement.component.yml
    bold-statement.twig
    bold-statement.sdc_showcase.yml   ← override file

Override files let you:

• Pin props to realistic content instead of generated lorem ipsum
• Define combinations: hand-crafted prop sets that produce named variations (e.g. "Dark mode with CTA", "Minimal without buttons")
• Enable or disable baseline, sweep, and edge generation per component
• Customise slots with HTML strings, embedded SDC components, or mixed lists
• Tweak the props of a specific auto-generated variation without rewriting it
• Exclude variations that aren't useful

You can generate skeleton override files for all your components with drush ssc:gen.

Entity directives

Some components expect Drupal entity objects as props: media images, referenced nodes, file entities. The _entity directive defines these in YAML:

pinned:
  card_image:
    _entity:
      entity_type: media
      bundle: image
      view_mode: default
      fields:
        name: "Hero image"
        field_media_image:
          _entity:
            entity_type: file
            fields:
              uri: "public://sdc-showcase/sdc-showcase-placeholder.jpg"
              filename: "sdc-showcase-placeholder.jpg"

Entities are created in-memory via Entity::create() and never saved to the database. Nested entities (a media entity referencing a file entity, for example) work fine. Add view_mode to pass rendered output instead of the raw entity object.

Collections

Collections compose multiple components into a single page, simulating real layouts:

landing_page:
  label: "Landing Page"
  components:
    - component: "my_theme:hero"
      props:
        title: "Welcome"

    - component: "my_theme:card"
      repeat: 3
      vary: [title, description]
      props:
        image_url: "https://example.com/photo.jpg"

    - component: "my_theme:cta-banner"
      props:
        heading: "Get Started"
      slots:
        extra: "<p>Call us today</p>"

Use repeat to render a component multiple times, vary to re-generate specific props on each repetition, and slot content can include embedded SDC component references.

Custom data generators

The generator system is plugin-based and extensible. You can write your own to handle custom format values in JSON Schema:

#[SdcDataGenerator(
  id: 'my_image_url',
  label: 'Image URL',
  schema_types: [],
  schema_formats: ['image-url'],
  weight: 20,
)]
class ImageUrlGenerator extends SdcDataGeneratorBase {
  public function generate(string $prop_name, array $schema, array $options, int $seed): mixed {
    return 'https://picsum.photos/seed/' . $seed . '/800/600';
  }
}

Generators match by format first (more specific), then by type (broader). Built-in generators cover strings, numbers, booleans, enums, URIs, arrays, and objects.

Visual regression testing

Every showcase URL is stable and deterministic (controlled by a configurable seed):

# All component page URLs:
drush ssc:urls

# Individual variation URLs for granular screenshots:
drush ssc:urls --include-variations

# Pipe into BackstopJS, Percy, Playwright, etc.:
drush ssc:urls --include-variations | xargs -I {} backstop reference --url={}

Access control

The showcase has a configurable access restriction layer on top of Drupal permissions:

• Open uses standard Drupal permissions only
• Disabled blocks all showcase routes with a 403. Use this on production.
• HTTP Basic Auth requires a username and password on top of permissions. CI tools like BackstopJS and Playwright support this natively.
• Query string requires ?sdc_key=VALUE on every URL. Simpler for scripted access.

Iframe mode

Iframe mode renders each variation inside its own iframe for full CSS/JS isolation. This prevents components from leaking global styles, sticky positioning, or z-index conflicts into each other. Iframes load lazily and auto-resize to their content height.

Drush commands

• drush ssc:list lists all showcased components
• drush ssc:gen scaffolds override files for components that don't have one
• drush ssc:urls outputs all showcase URLs (--include-variations for granular URLs)
• drush ssc:cc clears the showcase render cache

Example sub-module

The bundled SDC Showcase Examples sub-module (sdc_showcase_example) includes realistic example components that demonstrate every feature:

• Hero Banner uses enums, booleans, a custom format: image-url generator, and _entity media for the background
• Profile Card uses nested _entity for the avatar, arrays of objects with enum values, and department enum sweep
• Testimonial uses an integer prop with min/max, a style enum, and a boolean toggle
• CTA Banner uses format: uri, a theme enum, and slot content
• Card Grid shows component nesting via slots in a responsive grid layout
• Stats Counter and Content Block are intentionally poorly-defined (no enums, no defaults, no descriptions) to show what auto-generation looks like with minimal schema information

Enable with drush en sdc_showcase_example to see a working reference.

Requirements

• Drupal 10.6 or 11.x
• PHP 8.1+
• At least one theme or module that provides SDC components

Installation

composer require drupal/sdc_showcase
drush en sdc_showcase

Then visit /sdc-showcase to see your component library.