Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: adding more notes #390

Draft
wants to merge 10 commits into
base: next
Choose a base branch
from
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ import '@phase2/outline-container';
bottom-margin="spacing-8"
>
## Description
Lit components receive input and store their state as JavaScript class fields or properties.
Outline components receive input and store their state as JavaScript class fields(normally called slots) or properties.
glitchgirl marked this conversation as resolved.
Show resolved Hide resolved

[Reactive properties](https://lit.dev/docs/components/properties/) are properties that can trigger the reactive update cycle when changed, re-rendering the component, and optionally be read or written to attributes.

Expand All @@ -35,14 +35,21 @@ import '@phase2/outline-container';
</outline-container>

### Property usage basics

- Properties should be commented using [JSDoc](https://github.com/jsdoc/jsdoc).
- Each property should provide a comment including a description of the attribute functionality or purpose.
- Pass to `type` the appropriate [converter](https://lit.dev/docs/components/properties/#conversion-type) (`String`, `Boolean`, etc.).
- Pass to `attribute` an attribute name in kebab-case.
- Attribute names must not collide with HTML standard ones `title`, `href`, etc.
- This means it is best to name properties more like `link-title`, `link-href`, etc.

- Lit [documentation]()

### Slots versus properties
- When do I use a property?
- Properties are used for non-content features that impact the state of the component. For example, active versus inactive states.
- The component shouldn't change its own public properties, except in response to user input. For example, you could set a property to change background color, but the component itself shouldn't change it's own color.
- Slots are used for content, such as text, icons, or images.
glitchgirl marked this conversation as resolved.
Show resolved Hide resolved

### Property with default value

The below sample uses the `stringProperty = ''` to provide a default value to the property if it is not supplied or calculated by the component itself.
Expand Down