Component Proxies for Kaleidoscope et al

[nezaniel]

Based on #35 we can use the integration API via ::create to handle component proxies (or builders actually?), that gather additional information before calling expensive methods like image URI rendering.

Given Kaleidoscope defines the ImageTag component from before, it can now create a component proxy as follows:

final readonly class ImageTagProxy implements ComponentProxyInterface
{
    public function __construct(
        public ImageSourceInterface $imageSource,
        public string $mediaDescriptors,
    ) {
    }

    public static function create(ImageSourceInterface $imageSource): self
    {
        return new self($imageSource, '');
    }

    public function with(
        ?string $mediaDescriptors = null,
    ): self {
        return new self($this->imageSource, $mediaDescriptors ?: $this->mediaDescriptors);
    }

    public function resolve(): ImageTag
    {
        return new ImageTag(
            $this->imageSource->src(),
            $this->imageSource->srcset($this->mediaDescriptors),
            $this->imageSource->sizes(), // or similar
        );
    }
}

Note that it does not implement the component interface, it must not be rendered directly! We could implement a render() method though that throws a meaningful exception that the proxy must be resolved before rendering.

Additionally, to make things less easy, we add an intermediary Figure component as follows:

export component Figure {
    image: ImageTag with proxy ImageTagProxy // or similar
    caption: string

    return <figure class="figure">
        {image}
        <figcaption>{caption}</figcaption>
    </figure>
}

which transpiles to

final readonly class Figure extends AbstractComponent
{
    /**
     * @internal only for deserialization
     */
    public function __construct(
        public ImageTag|ImageTagProxy $image,
        public string $caption,
    ) {
    }

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

    /**
    * @internal for prop merge only
    */
    public function with(
        ?ImageTag $image = null,
        ?string $caption = null,
    ): self {
        return new self(
            $image,
            $caption,
        );
    }

    public function render(): string
    {
        return '<figure class="figure">
            ' . $this->image . '
            <figcaption>' . $this->caption . '</figcaption>
        </figure>';
    }
}

We now adjust our card component as follows:

export component Card {
    media: Figure {
        image {
            // here we enforce the responsive image sizes etc. for the image in the figure in this component
            mediaDescriptors: "whatever" 
            ...
        }
    }
    headline: Headline {
        size: 'large' // here we enforce headline size for this component
    }

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

which now transpiles to

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

    public static function create(
        Figure $media,
        Headline $headline,
    ): self {
        return new self(
            media: $media->image instanceof ImageTagProxy
                ? new Figure(
                    // here we have all necessary parameters and can resolve before rendering!
                    image: $media->image->with(mediaDescriptors: 'whatever')->resolve(),
                    caption: $media->caption
                )
                : $picture,
            headline: $headline->with(variant: HeadlineVariant::VARIANT_LARGE),
        );
    }

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

In the PHP integration we can now call

class SomeFactory 
{
    public function forSomeNode(Node $node): Card
    {
        return Card::create(
            // assuming node property image is already an asset image source
            media: Figure::create(
                image: ImageTagProxy::create(image: $node->getProperty('image') ?: new DummyImageSource()),
                caption: $node->getProperty('caption'),
            ),
            headline: Headline::create(
                type: HeadlineType::H2,
                content: $node->getProperty('headline')
            ),
        );
    }
}

This way we can instantiate a component

• with exactly the outside props we need to decide in the integration and none more
• without additional helper structs
• with the extra load on the transpiler instead of the renderer
• without losing any functionality of the proxy provider Kaleidoscope (I think)

WDYT?