feat: prop get set new

[johnjenkins]

• NEW / UPDATED FROM ORIGINAL PR feat(): @Prop getters / setters #2899 *

Allowing the @Prop decorator to use get / set provides many quality of life improvements for developers and can improve the api of their components (see linked issues for many valid, uncontested use cases).

Validation & Guards. Transforming data. Read-only properties. All things that may be achievable at the moment but can be extremely cumbersome to implement.

What is the current behavior?

@Prop() decorated attributes cannot be used with get() or set()

GitHub Issue Number: Fixes #1359

What is the new behavior?

/**
 * This prop will be readonly 
 * (and will automatically get '@readonly' added to the docs description)
*/
@Prop()
get myReadonlyProp() {
  return 'a string';
}

// getter & setter with validation
private _agent: 'xxx' | 'James Pond Robocod' |  'James Bond' = 'James Bond'; 
@Prop()
get agent() {
  return this._agent;
}
set agent(agent: string) {
  if (
       typeof agent === 'string' && 
       (agent === 'xxx' || agent === 'James Pond Robocod')
  ) this._agent = agent;
}

Documentation

@Prop decorator attributes: attribute and reflect work as expected.

Prop setters work as expected in relation to @Watch decorated methods (the Watch method will only be called after the setter has actually changed the property value).

get() only properties will be marked as @readonly in the JSDoc comment.

Known limitations

When using the dist / 'lazy' bundle, If an initial value is set (via an attribute for example) in-order to 'go through' the class' set() method, Stencil can only do so after lazily fetching / loading the class component. This means one initial render / tick before being able to set the incoming, initial value.

This limitation does not exist on the dist-custom-elements/ non-lazy bundle

ionic-team/stencil-site#1496

Does this introduce a breaking change?

• Yes
• No

Testing

• Linked to local projects with the instructions found in the Contributing guidelines
• Stencil unit / jest tests
• Stencil e2e / wdio tests

Other information

[christian-bromann]

@johnjenkins great work 👏 do you think this feature needs to amendments to the Stencil docs?

[johnjenkins]

@christian-bromann done :)

ionic-team/stencil-site#1496

[christian-bromann]

LGTM 👍 great work 👏

[dogoku]

@johnjenkins you legend! 🎉