Add an advanced variants notation to SDC

Related to nod_'s question: how would you relate those variants props to data from Drupal, e.g. a value coming from one entity field? Or ar they expected to always be hard-coded values, and "content" data only used in slots?

Add card.imfo.yml

id: card
label: Card
description: A reusable card component
type: component

props:
kind:
type: string
default: button
text:
type: string
default: Default text

examples:
primary:
title: Primary card
description: A card with a button
props:
kind: button
text: Click me

secondary:
title: Secondary card
description: A card with a link
props:
kind: link
text: Go there
then add twig file card.html.twig

and then render in node or page.html.twig

and render in any page or node twig file

{# Renders with defaults #}
{% render '@your_theme/card' %}

{# Renders with manual override #}
{% render '@your_theme/card' with { kind: 'link', text: 'Manually set' } %}

Since #3390712: Add component variants to SDC, we have introduced variant in SDC definition:

variants:
  primary:
    title: Primary
    description: ...
  secondary:
    title: Secondary
    description: ...
  tertiary:
    title: Tertiary
    description: ...

This simple notation covers the majority of the use cases discovered in public design systems and projects.

However, it fails to express advanced 2 use cases:

When there is no explicit "variant" prop upstream documentation

Variants are called "variant" in upstream documentation and/or code for:

• https://shoelace.style
• https://spectrum.adobe.com
• https://daisyui.com/
• https://www.patternfly.org/
• ..

However, they may be called:

• "type" in https://m3.material.io/
• "kind" (in code) & "variant" (in documentation, sometimes) in https://carbondesignsystem.com/
• "color" & "version" in https://bulma.io
• ...

When proposing this "advanced notation", @alex.skrypnyk told us "do not expose the variant name as a prop to the component's Twig", so this proposal may allow us to be more faithful to the upstream documentation sending the expected variable to the template instead of variant?

However, the notation looks excessively complicated for renaming "variant" to "kind". Example

name:  Card
variants:
  primary:
    title: Primary
    description: ...
    props:
       variant: primary
  secondary:
    title: Secondary
    description: ...
    props:
       variant: secondary
  tertiary:
    title: Tertiary
    description: ...
    props:
       variant: tertiary
 ...
props: 
  type: object
  properties:
    kind:
      title: Kind
     type: string
    enum: 
      - primary
     - secondary
     - tertiary
slots: {}

When a variant is the combination of 2 or more enums

In Bulma, what we call "variant" can sometimes be understood as a combination of "color" and "version". Example: https://bulma.io/documentation/elements/button/

In this case, the advanced notation proposal looks useful:

name:  Button
variants:
  primary_light:
    title: Primary Light
    props:
       color: primary
       version: light
  primary:
    title: Primary dark
    props:
       color: primary
       version: dark
  secondary:
    title: Secondary light
    props:
       color: secondary
       version: light
   ...
props: 
  type: object
  properties:
    color:
      title: Color
     type: string
     enum: 
      - primary
     -  link
    version:
      title: Version
     type: string
     enum: 
      - dark
     -  light
slots: {}

Conclusion

So, with this advanced notation, what will be the processing? If the chosen variant as a non empty "props" property, we send the value of the props insetad of the "variant" variable?

It will allow us to mix the simple notation and the advanced one. Example:

name:  Button
variants:
  foo:
    title: Foo
  bar:
    title: Bar
    props:
       color: primary
       version: dark
   ...
props:
  type: object
  properties:
    color: {...}
    version: {...}
slots: {}

If foo is selected, variant = foo will be sent to the template. If bar is selected, color = primary and version = dark will be sent to the template.

I am still not 100% convinced by this proposal because it is always possible to pick only one of the enum (color OR version in this example) as the "glorified" variant enum. But there is something interesting to explore here anyway.

I have updated the title because the principle of "examples" may be better addressed with a "component stories" API, distinct from component definition.

@pdureau
I think we have clarified that I was talking about stories. I'm not sure why this issue was steered towards extending the variants API. The examples and description was talking about stories and there are references to this issue that are talking about stories as well. Now all those links will lead to this issue and people will be confused.

I do not know what to do now since you have added comments to this issue. Can you move them to another issue?

@nod_
During our discussion we established that there were 3 understandings of what "variant" meant:

1. The glorified prop - https://www.drupal.org/project/drupal/issues/3390712
2. The advanced glorified prop - what finnsky meant
3. The Storybook-like stories - what I meant

This issue had "storybook" and "examples" in it and it was linked from other issues as an issue related to defining an API for storybook-style examples (3).

Now this became an issue about (2). I've updated the description to use "variants" instead of "examples" for clarity.

I still want a place to track (3). But I will raise it separately.