Separating integration from presentation props

[nezaniel]

When using nested components, it makes sense to separate props into those that are passed in from outside (e.g. content, a Kaleidoscope image source or a headline type) from those the outer component wants to define for its children. A composite card component might want to enforce the size of its headline e.g.

Let's assume we have three components: Headline, ImageTag and Card, which combines the first two:

export component Headline {
    type: HeadlineType
    size: HeadlineSize = 'large' @internal // or similar
    content: string

   return ...
}

which transpiles to

final readonly class Headline extends AbstractComponent
{

    /**
    * @internal only for deserialization
    */
    public function __construct(
        public HeadlineType $type,
        public HeadlineSize $size,
        public string $content,
    ) {
    }

    /**
    * @api to be used in integration
    */
    public static function create(
        HeadlineType $type,
        string $content,
    ): self {
        return new self(
            $type,
            HeadlineSize::REGULAR, // here goes the default value, not part of the integration API
            $content,
        );
    }

    /**
    * @internal to be used for prop merging
    */
    public function with(
        ?HeadlineType $type = null,
        ?HeadlineVariant $variant = null,
        ?string $content = null,
    ): self {
        return new self(
            $type !== null ? $type : $this->type,
            $variant !== null ? $variant : $this->variant,
            $content !== null ? $content :  $this->content,
        );
    }

    public function render(): string
    {
        return '...';
    }
}

,

export component ImageTag {
    src: string
    srcset: string
    sizes: string

   return ...
}

which transpiles to

final readonly class ImageTag extends AbstractComponent
{

    /**
    * @internal only for deserialization
    */
    public function __construct(
        public string $src,
        public string $srcset,
        public string $sizes,
    ) {
    }

    /**
    * @api to be used in integration
    */
    public static function create(
        string $src,
        string $srcset,
        string $sizes,
    ): self {
        return new self($src, $srcset, $sizes);
    }

    /**
    * @internal to be used for prop merging
    */
    public function with(
        ?string $src,
        ?string $srcset,
        ?string $content,
    ): self {
        return new self(
            $src !== null ? $src : $this->src,
            $srcset !== null ? $srcset : $this->srcset,
            $sizes !== null ? $sizes :  $this->sizes,
        );
    }

    public function render(): string
    {
        return '...';
    }
}

and

export component Card {
    image: ImageTag
    headline: Headline {
        size: 'large' // here we enforce headline size for this component
    }

    return <div class="card">
        {image}
        {headline} // here we just render the headline without calling its constructor
    </div>
}

which transpiles to

final readonly class Card extends AbstractComponent
{

    /**
    * @internal only for deserialization
    */
    public function __construct(
        public ImageTag $image,
        public Headline $headline,
    ) {
    }

    /**
    * @api to be used in integration
    */
    public static function create(
        ImageTag $image,
        Headline $headline, // a headline without meaningful size, which cannot be set by integration
    ): self {
        return new self(
            image: $image,
            headline: $headline->with(size: HeadlineSize::LARGE),
        );
    }

    /**
    * @internal to be used for prop merging
    */
    public function with(
        ?ImageTag $image,
        ?Headline $headline,
    ): self {
        return new self(
            $image !== null ? $image : $this->image,
            $headline !== null ? $headline : $this->headline,
        );
    }

    public function render(): string
    {
        return '<div class="card">' . $this->image . $this->headline . '</div>';
    }
}

In the PHP integration we can now call

class SomeFactory 
{
    public function forSomeNode(Node $node): Card
    {
        return Card::create(
            image: ImageTag::create(...), // wherever we get that information from
            headline: Headline::create(
                type: HeadlineType::H2,
                content: $node->getProperty('headline')
            ),
        );
    }
}

The handling of component proxies, like Kaleidoscope does it, follows in the next part.
WDYT?

[mhsdesign]

interesting, especially because its a solution for the presentational props problem we talked about long ago with somewhat of the ideas we came up with just lately we had when trying to solve the Kaleidoscope riddle.

just to elaborate what i understand as the presentational problem: its the dilemma of having to specify props in the integration already which are rather independent of integration like the font or colour.

Imagine a box with dark background where a subcomponent, the text should be light. Now how should the integration now that headlines in this box should use the variant light? Without having designed the components themselves this must be tested out.

When we talked before about that i think we also considered options like specifying just the Headline props and separating the rendering

struct HeadlineProps
{
   content: string
   tagName: 'h1'|'h2'|‘h3‘
}

component Headline
{
    props: HeadlineProps
    // presentational props
    color: 'light'|'dark'
    
    return <props.tagName class={match(color) { 'light' => 'color-light', 'dark' => 'color-dark' }}>{props.content}</props.tagName>
}

component Box
{
   headline: HeadlineProps

   return <div class="bg-dark">
      <Headline props={headline} color="light" />
   </div>
}

Or possibly also overriding the variant from a headline by recreating it:

struct Headline
{
   content: string
   tagName: 'h1'|'h2'|‘h3‘

    // presentational props
    color: 'light'|'dark'
    
    return <tagName class={match(color) { 'light' => 'color-light', 'dark' => 'color-dark' }}>{content}</tagName>
}

component Box
{
   headline: Headline

   return <div class="bg-dark">
      <Headline {...headline} color="light" />
   </div>
}

[nezaniel]

That's another great example, yes! In the above schema it would be

component Headline
{
    tagName: 'h1'|'h2'|‘h3‘
    content: string
    color: 'light'|'dark' = 'dark' @internal
    
    return <{tagName} class={match(color) { 'light' => 'color-light', 'dark' => 'color-dark' }}>{content}</{tagName}>
}

, transpiled to

final readonly class Headline extends AbstractComponent
{

    /**
    * @internal only for deserialization
    */
    public function __construct(
        public TagName $tagName,
        public string $content,
        public Color $color,
    ) {
    }

    /**
    * @api to be used in integration
    */
    public static function create(
        TagName $tagName,
        string $content
    ): self {
        return new self(
            tagName: $tagName,
            content: $content,
            color: Color::DARK, // the default
        );
    }

    /**
    * @internal to be used for prop merging
    */
    public function with(
        ?TagName $tagName = null,
        ?string $content = null,
        ?Color $color = null,
    ): self {
        return new self(
            $tagName !== null ? $tagName : $tagName->image,
            $content !== null ? $content : $this->content,
            $color !== null ? $color : $this->color,
        );
    }

    public function render(): string
    {
        return '<' . $this->tagName . ' class="' . match($this->color) { Color::LIGHT => 'color-light', Color::DARK => 'color-dark' } . '">' . $this->content . '</' . $this->tagName . '>';
    }
}

and

export component Box
{
    headline: Headline {
        color: 'light'
    }

   return <div class="bg-dark">
      {headline}
   </div>
}

transpiling to

final readonly class Box extends AbstractComponent
{
    /**
    * @internal only for deserialization
    */
    public function __construct(
        public Headline $headline,
    ) {
    }

    /**
    * @api to be used in integration
    */
    public static function create(
        Headline $headline, // a headline without meaningful color, which cannot be set by integration
    ): self {
        return new self(
            headline: $headline->with(color: Color::LIGHT),
        );
    }

    /**
    * @internal to be used for prop merging
    */
    public function with(
        ?Headline $headline,
    ): self {
        return new self(
            $headline !== null ? $headline : $this->headline,
        );
    }

    public function render(): string
    {
        return '<div class="bg-dark">' . $this->headline . '</div>';
    }
}

In the factory we can now just call

class SomeFactory 
{
    public function forSomeNode(Node $node): Box
    {
        return Box::create(
            headline: Headline::create(
                type: HeadlineType::H2,
                content: $node->getProperty('headline')
            ),
        );
    }
}

to wrap the headline properly in a (dark background) box.

The followup question would now be: What if the box itself can be dark or light and the headline must always have the inverse color? Is that something we have to handle here (like doing a match on the internal headline color) or can this be done more elegantly in CSS without needing this?

[mhsdesign]

What if the box itself can be dark or light and the headline must always have the inverse color?

Indeed this is harder to replicate with the approach you draw out. And overall, yes it looks pretty but there is still a new level of complexity for the component engine.

The example i showed - which was as far as i know intended already by the spec or even possibly implemented, allowes for FULL flexibility while not having to extend anything:

Box {
   headline: Headline

  return <Headline {...headline} color={match(boxVariant) {'light' => 'dark', 'dark' => 'light'} />
}

The following would transpile the following

public function render() {
   return (new Headline(content: $this->headline->content, tagName: $this->headline->tagName, color: match($this->boxVariant) {'light' => 'dark', 'dark' => 'light'}))->render();
}

Which is the cool thing and one of the unique things of a pure component language. The prop headline can be used as component, or can be used to access its props via spread.

Downside of this approach being that the initial integration set 'color' will be fully overridden ... but for that we might even levarage nullability:

<Headline {...headline} color={headline.color ?? match(boxVariant) {'light' => 'dark', 'dark' => 'light'} />

component Headline
{
    tagName: 'h1'|'h2'|‘h3‘
    content: string
    color: 'light'|'dark'|null
    
    return <{tagName} class={match(color) { 'light' => 'color-light', default, 'dark' => 'color-dark' }}>{content}</{tagName}>
}

Meaning that the integration can just enter NULL for color and depending on its placement it will be choosen. But the integration doesnt loose full control to be able to still force a better value (if headline.color ?? is used)

[nezaniel]

well, since afaik presentational props can only depend on integrational ones (or be constant) we could use the match statement on creation:

export component Box
{
    color: light|dark
    headline: Headline {
        color: match(color) {'light' => 'dark', 'dark' => 'light'}
    }

   return <div class={match(color) {'light': => 'color-light', dark => 'color-dark'}>
      {headline}
   </div>
}

transpiling to

final readonly class Box extends AbstractComponent
{
    /**
    * @internal only for deserialization
    */
    public function __construct(
        public Headline $headline,
    ) {
    }

    /**
    * @api to be used in integration
    */
    public static function create(
        Color $color, // this has to be specified from outside
        Headline $headline, // a headline without meaningful color, which cannot be set by integration
    ): self {
        return new self(
            color: $color,
            headline: $headline->with(color: match($color) {Color::DARK => Color::LIGHT, Color::LIGHT => Color::DARK),
        );
    }

    /**
    * @internal to be used for prop merging
    */
    public function with(
        ?Color $color = null,
        ?Headline $headline = null,
    ): self {
        return new self(
             $color !== null ? $color : $this->color,
            $headline !== null ? $headline : $this->headline,
        );
    }

    public function render(): string
    {
        return '<div class="'. match($this->color) {Color::LIGHT => 'bg-light', Color::DARK => 'bg-dark'} . '">' . $this->headline . '</div>';
    }
}

which hopefully doesn't introduce too much complexity as matching is already implemented, isn't it? 😅
At least it's not a new concept...