From 58c65543980fdbf90e173080e198db4c5fe5a46c Mon Sep 17 00:00:00 2001 From: Matthew Cheely Date: Tue, 19 May 2020 15:28:47 -0400 Subject: [PATCH] docs: clarify alpha status, components likely to change Several people have asked about why the component library is in an alpha release stage, and what components are likely to see breaking changes before the end of alpha. This attempts to clarify those issues in the documentation. --- COMPONENT_DESIGN.md | 26 +++++++++++++++++++++++--- README.md | 4 ++++ 2 files changed, 27 insertions(+), 3 deletions(-) diff --git a/COMPONENT_DESIGN.md b/COMPONENT_DESIGN.md index b957dcd41e..5abdc25b81 100644 --- a/COMPONENT_DESIGN.md +++ b/COMPONENT_DESIGN.md @@ -2,8 +2,13 @@ Best practices for developing presentational web components that have a nice API and are easy to work with. - - [Prefer structured markup](#markdown-header-prefer-structured-markup-over-complex-attributes-over-js-interfaces) - - [Use a consistent input API](#markdown-header-use-a-consistent-api-for-components-that-accept-input) +The general principle at work in this document is that our presentational components should have APIs that are +consistent with native browser elements. They should feel familiar to users who are comfortable working with +native input elements and controls. + +- [Prefer structured markup](#markdown-header-prefer-structured-markup-over-complex-attributes-over-js-interfaces) +- [Use a consistent input API](#markdown-header-use-a-consistent-api-for-components-that-accept-input) +- [Don't use reflectToAttr](#markdown-header-dont-use-reflecttoattr) ## Prefer structured markup over complex attributes or js interfaces @@ -71,4 +76,19 @@ those components and for events emitted by the components. In particular compone - Should have a `value` attribute and property, like the various native input-related elements - An additional boolean attribute similar to `checked` may be appropriate for elements with boolean state. - Should emit the `input` event (at a minimum) with the `detail` property on the event set to the data the -component is intended to get from the user. + component is intended to get from the user. + +## Don't use reflectToAttr + +Stencil properties can be set with the option `reflectToAttr`. When set, a change in an elements property will +also change the value of the attribute in the DOM. For example, when dealing with this input element: + +```html + +``` + +If `reflectToAttr` was set on `value`, then calling `document.getElementById("myInput").value = "new value"` would +mean that `document.getElementById("myInput").getAttr("value")` would now return "new value". This is _not_ how +native browser elements behave. It also puts the internal implementation of the compnent in conflict with the surrounding +framework used to render it about what the attribute's value should be, since it is being set twice, potentially leading +to bugs. diff --git a/README.md b/README.md index 36ab2ac38c..86535019bd 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,10 @@ You may also want to join the chat room for the Genesys Cloud [Common UI Develop ## Installing the library +Currently the main line of development is done in the 1.0.0-alpha branch/release. This is because we are working on making +changes to the APIs of some components to bring them up to our [API design standards](COMPONENT_DESIGN.md). The elements +that are currently likely to change are documented by the `likely-breaking-changes` label [in JIRA](). + ### Prerequisites Published artifacts are stored in our private artifactory/jfrog registry, so you will need to update your