Proposal: adding TypedProps

[tomdavies]

Why this is useful

1. Makes the template patterns more self-documenting without the need for comments
2. Speeds debugging (I think the validation should only run when in HARD_MODE - i.e. not in production)
3. Makes it possible to do reflection on component props, enabling Storybook-style auto-generated UI for manipulating prop values in a future Craft living styleguide generator (imagine a UI with 2 frames: a rendered Twig component + autogenerated form UI for changing prop values, change the props and the template re-renders)

1 & 2 are immediate term wins, 3 is long term value

Implementation:

I’m already going to re-work defineProps() to use Yii’s DynamicModel (which I should have used in the first place TBH). That allows us to pass a Yii Model rules() definition as a second argument

Then we need a prop type syntax that is:

• Straightforward to translate to Model rules
• Fluent / not overly verbose
• Can be gradually adopted / opt-in while supporting the current literal syntax

Much as it pains me to say anything positive about React, the propTypes fluent API is quite nice, and more readable/less verbose than a Vue style object definition. It also should be fairly easy to convert to Yii Model rules, I think something like this could work well.

Examples

Basic usage

{% do defineProps(data, {
  'featured': propType.boolean.default(false),
  'name': propType.string.default('John Doe'),
  'phone': propType.oneOfType(['string', 'number']),
  'phoneType': propType.enum.oneOf(['home', 'work', 'mobile']),
  'roles': propType.arrayOf(propType.string.isRequired),
}) %}

Advanced usage

Nested objects:

{% do defineProps(data, {
  'address': propType.shape({
    'street': propType.string.isRequired,
    'city': propType.string.isRequired,
    'state': propType.string,
    'zip': propType.string.isRequired,
  }),
}) %}

optionalObjectWithShape: PropTypes.shape({
optionalProperty: PropTypes.string,
requiredProperty: PropTypes.number.isRequired
}),

We could abstract values to config for reuse/consistency across components

<?php
  // config/conventions.php
  return [
    'propTypes' => [
      'presets' = [
        'themes' => [ 
          'values' => ['light', 'dark'],
          'default' => 'light',
        ],
      ],
    ],
  ];

{% do defineProps(opts, {
  'theme': propType.enum.preset('themes')
  'theme2': propType.enum.preset('themes').default('dark')
}) %}

{# 'light'#}
{{ opts.theme }} 
{# 'dark' #}
{{ opts.theme2 }} 

Craft Element types

We can / should directly support Craft elements as types, as this will be a common use case. We can either directly describe the shape of the element that we're actually using (via withShape()),or provide refinements in ElementQuery syntax: entry.section('news') or category.group('news')

Aside: maybe we could have a shorter alias of propType() (such as pt() / prop ) for brevity?

{% do defineProps(data, {
  'entry': propType.entry,
  'otherEntry': propType.entry.isRequired.withShape({
      'title': propType.string.isRequired,
      'url': propType.url.isRequired,
      'image': propType.asset.isRequired,
    }),
}) %}

collectionOf() would work like take(), i.e. it would accept any of:

• a single element
• an array of elements
• a query
• a collection

{% do defineProps(data, {
  'articles': propType.collectionOf(propType.entry),
  'categories': propType.collectionOf(category.group('news')),
  'image': propType.asset.kind('image'),
  'blocks': propType.collectionOf(propType.matrixBlock.withShape({
    'heading': propType.string,
    'body': propType.string.isRequired,
  })),
}) %}

Custom Element types

The above would be equivalent to:

{% do defineProps(data, {
  'entry': propType.element('craft\\elements\\Entry'),
}) %}

So supporting custom element types would be an easy lift

Craft Field types

Similarly, we should support Craft custom field types that we use frequently out of the box:

{% do defineProps(data, {
  'action': propType.fields.linkIt,
  'richText': propType.fields.redactor,
}) %}

And instances of other classes could either be supported dynamically with a isInstanceOf() method:

{% do defineProps(data, {
  'map': propType.isInstanceOf('doublesecretagency\\googlemaps\\records\\Address'),
}) %}

Or declared in config:

<?php
  // config/conventions.php
  return [
    'propTypes' => [
      'types' = [
        'mapAddress' => [ 
          'instanceOf' => 'doublesecretagency\\googlemaps\\records\\Address',
          'validationStrategy' => 'Model', // instances are models so we can call validate() on them
        ],
      ],
    ],
  ];

Impersonating a class-typed prop

Often, we need pass data to a component that expects a class instance of say Entry, but what we actually have is a collection of dynamically assembled properties.

This is where asType() comes in. asType() is aware of the same types, fields and elements as defineProps() and will attempt to coerce the data into the type specified.

defineProps validation will then work in exactly the same way as if a "real" instance of the Type had been passed

e.g.

{# _components/card.twig #}
{% do defineProps(data, {
  'entry': propType.entry.isRequired.withShape({
    'title': propType.string.isRequired,
    'description': propType.fields.redactor.isRequired,
    'action': propType.fields.linkIt,
    'image': propType.asset.isRequired,
  }),
}) %}

{# index.twig #}
{% include '_components/card' with {
  entry: asType.entry({
    title: 'Fake card title',
    image: assetFromSomewhere,
    description: asType.fields.redactor('<p>Lorem ipsum dolor sit amet</p>'),
    url: asType.fields.linkIt({
      url: '/',
      text: 'Take me to the river',
    }),
  })
} %}

Note: asType.elements.entry is probably more consistent, but it is more verbose, so I wonder if having the shortcut for "core" element types is worth it...