From 4047d6ac83814cd4c6f3a8afda82d97f76f2f356 Mon Sep 17 00:00:00 2001 From: Morgan Date: Wed, 17 May 2023 12:13:11 -0400 Subject: [PATCH 1/5] fix: adding more notes --- .../component-development/06-properties.mdx | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/packages/outline-docs/src/guides/development/component-development/06-properties.mdx b/packages/outline-docs/src/guides/development/component-development/06-properties.mdx index b36cd51ac..31f357fb6 100644 --- a/packages/outline-docs/src/guides/development/component-development/06-properties.mdx +++ b/packages/outline-docs/src/guides/development/component-development/06-properties.mdx @@ -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. [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. @@ -35,7 +35,6 @@ import '@phase2/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.). @@ -43,6 +42,14 @@ import '@phase2/outline-container'; - 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. + ### 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. From 2fde40f9213e693c4831675f01e7c218178c8dff Mon Sep 17 00:00:00 2001 From: Morgan Smith Date: Wed, 17 May 2023 12:34:43 -0400 Subject: [PATCH 2/5] Update packages/outline-docs/src/guides/development/component-development/06-properties.mdx Co-authored-by: Ofer Shaal --- .../guides/development/component-development/06-properties.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/outline-docs/src/guides/development/component-development/06-properties.mdx b/packages/outline-docs/src/guides/development/component-development/06-properties.mdx index 31f357fb6..cc4829d0b 100644 --- a/packages/outline-docs/src/guides/development/component-development/06-properties.mdx +++ b/packages/outline-docs/src/guides/development/component-development/06-properties.mdx @@ -48,7 +48,7 @@ import '@phase2/outline-container'; - 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. +- Slots are used for content, such as HTML markup, text, icons, or images. ### Property with default value From 738a28c91bb77f44a39723878a04c5e0cce1e2eb Mon Sep 17 00:00:00 2001 From: Morgan Date: Wed, 17 May 2023 12:35:49 -0400 Subject: [PATCH 3/5] fix: cleaning --- .../guides/development/component-development/06-properties.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/outline-docs/src/guides/development/component-development/06-properties.mdx b/packages/outline-docs/src/guides/development/component-development/06-properties.mdx index cc4829d0b..67683bc4b 100644 --- a/packages/outline-docs/src/guides/development/component-development/06-properties.mdx +++ b/packages/outline-docs/src/guides/development/component-development/06-properties.mdx @@ -21,7 +21,7 @@ import '@phase2/outline-container'; bottom-margin="spacing-8" > ## Description - Outline components receive input and store their state as JavaScript class fields(normally called slots) or properties. + Outline components receive input and store their state as JavaScript class fields(normally called attributes) or properties. [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. From 0b6821b2a7359808c5037a8071f3ce8356f08f93 Mon Sep 17 00:00:00 2001 From: Morgan Date: Wed, 17 May 2023 15:33:29 -0400 Subject: [PATCH 4/5] fix: folder structure, making rules squishy --- docs/README.md | 1 - .../guides/{development => }/99-additional-resources.mdx | 0 .../component-development/01-component-structure.mdx | 0 .../{development => }/component-development/03-styles.mdx | 0 .../component-development/04-controllers.mdx | 0 .../{development => }/component-development/05-render.mdx | 0 .../component-development/06-properties.mdx | 6 +++--- .../{development => }/component-development/07-slots.mdx | 0 .../component-development/08-lifecycle-methods.mdx | 0 .../{development => }/component-development/09-events.mdx | 0 .../component-development/10-utility-functions.mdx | 0 .../component-development/11-extending.mdx | 0 .../guides/{development => }/component-development/main.mdx | 0 13 files changed, 3 insertions(+), 4 deletions(-) delete mode 100644 docs/README.md rename packages/outline-docs/src/guides/{development => }/99-additional-resources.mdx (100%) rename packages/outline-docs/src/guides/{development => }/component-development/01-component-structure.mdx (100%) rename packages/outline-docs/src/guides/{development => }/component-development/03-styles.mdx (100%) rename packages/outline-docs/src/guides/{development => }/component-development/04-controllers.mdx (100%) rename packages/outline-docs/src/guides/{development => }/component-development/05-render.mdx (100%) rename packages/outline-docs/src/guides/{development => }/component-development/06-properties.mdx (91%) rename packages/outline-docs/src/guides/{development => }/component-development/07-slots.mdx (100%) rename packages/outline-docs/src/guides/{development => }/component-development/08-lifecycle-methods.mdx (100%) rename packages/outline-docs/src/guides/{development => }/component-development/09-events.mdx (100%) rename packages/outline-docs/src/guides/{development => }/component-development/10-utility-functions.mdx (100%) rename packages/outline-docs/src/guides/{development => }/component-development/11-extending.mdx (100%) rename packages/outline-docs/src/guides/{development => }/component-development/main.mdx (100%) diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index a48ea5f62..000000000 --- a/docs/README.md +++ /dev/null @@ -1 +0,0 @@ -# Outline Documentation diff --git a/packages/outline-docs/src/guides/development/99-additional-resources.mdx b/packages/outline-docs/src/guides/99-additional-resources.mdx similarity index 100% rename from packages/outline-docs/src/guides/development/99-additional-resources.mdx rename to packages/outline-docs/src/guides/99-additional-resources.mdx diff --git a/packages/outline-docs/src/guides/development/component-development/01-component-structure.mdx b/packages/outline-docs/src/guides/component-development/01-component-structure.mdx similarity index 100% rename from packages/outline-docs/src/guides/development/component-development/01-component-structure.mdx rename to packages/outline-docs/src/guides/component-development/01-component-structure.mdx diff --git a/packages/outline-docs/src/guides/development/component-development/03-styles.mdx b/packages/outline-docs/src/guides/component-development/03-styles.mdx similarity index 100% rename from packages/outline-docs/src/guides/development/component-development/03-styles.mdx rename to packages/outline-docs/src/guides/component-development/03-styles.mdx diff --git a/packages/outline-docs/src/guides/development/component-development/04-controllers.mdx b/packages/outline-docs/src/guides/component-development/04-controllers.mdx similarity index 100% rename from packages/outline-docs/src/guides/development/component-development/04-controllers.mdx rename to packages/outline-docs/src/guides/component-development/04-controllers.mdx diff --git a/packages/outline-docs/src/guides/development/component-development/05-render.mdx b/packages/outline-docs/src/guides/component-development/05-render.mdx similarity index 100% rename from packages/outline-docs/src/guides/development/component-development/05-render.mdx rename to packages/outline-docs/src/guides/component-development/05-render.mdx diff --git a/packages/outline-docs/src/guides/development/component-development/06-properties.mdx b/packages/outline-docs/src/guides/component-development/06-properties.mdx similarity index 91% rename from packages/outline-docs/src/guides/development/component-development/06-properties.mdx rename to packages/outline-docs/src/guides/component-development/06-properties.mdx index 67683bc4b..245b4e061 100644 --- a/packages/outline-docs/src/guides/development/component-development/06-properties.mdx +++ b/packages/outline-docs/src/guides/component-development/06-properties.mdx @@ -26,8 +26,8 @@ import '@phase2/outline-container'; [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. ## Documentation Status - - Status: Needs Work/In Progress + + Status: Complete / Update to data May 2023

This documentation is in need of additional work, or is currently in progress.

@@ -41,7 +41,6 @@ import '@phase2/outline-container'; - 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 @@ -49,6 +48,7 @@ import '@phase2/outline-container'; - 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 HTML markup, text, icons, or images. +- There are cases in which adding content as a property will make sense, for example using a title to control the state of the component. Use this cautiously, as it can cause issues with a11y tools and automation. ### Property with default value diff --git a/packages/outline-docs/src/guides/development/component-development/07-slots.mdx b/packages/outline-docs/src/guides/component-development/07-slots.mdx similarity index 100% rename from packages/outline-docs/src/guides/development/component-development/07-slots.mdx rename to packages/outline-docs/src/guides/component-development/07-slots.mdx diff --git a/packages/outline-docs/src/guides/development/component-development/08-lifecycle-methods.mdx b/packages/outline-docs/src/guides/component-development/08-lifecycle-methods.mdx similarity index 100% rename from packages/outline-docs/src/guides/development/component-development/08-lifecycle-methods.mdx rename to packages/outline-docs/src/guides/component-development/08-lifecycle-methods.mdx diff --git a/packages/outline-docs/src/guides/development/component-development/09-events.mdx b/packages/outline-docs/src/guides/component-development/09-events.mdx similarity index 100% rename from packages/outline-docs/src/guides/development/component-development/09-events.mdx rename to packages/outline-docs/src/guides/component-development/09-events.mdx diff --git a/packages/outline-docs/src/guides/development/component-development/10-utility-functions.mdx b/packages/outline-docs/src/guides/component-development/10-utility-functions.mdx similarity index 100% rename from packages/outline-docs/src/guides/development/component-development/10-utility-functions.mdx rename to packages/outline-docs/src/guides/component-development/10-utility-functions.mdx diff --git a/packages/outline-docs/src/guides/development/component-development/11-extending.mdx b/packages/outline-docs/src/guides/component-development/11-extending.mdx similarity index 100% rename from packages/outline-docs/src/guides/development/component-development/11-extending.mdx rename to packages/outline-docs/src/guides/component-development/11-extending.mdx diff --git a/packages/outline-docs/src/guides/development/component-development/main.mdx b/packages/outline-docs/src/guides/component-development/main.mdx similarity index 100% rename from packages/outline-docs/src/guides/development/component-development/main.mdx rename to packages/outline-docs/src/guides/component-development/main.mdx From 704150d4c412a3480af1d5f34e0e36eea6982be5 Mon Sep 17 00:00:00 2001 From: Morgan Date: Fri, 19 May 2023 11:10:32 -0400 Subject: [PATCH 5/5] fix: adding more context --- .../guides/component-development/06-properties.mdx | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/packages/outline-docs/src/guides/component-development/06-properties.mdx b/packages/outline-docs/src/guides/component-development/06-properties.mdx index 245b4e061..54d97c5a2 100644 --- a/packages/outline-docs/src/guides/component-development/06-properties.mdx +++ b/packages/outline-docs/src/guides/component-development/06-properties.mdx @@ -41,14 +41,18 @@ import '@phase2/outline-container'; - 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]() +- Lit [documentation](https://lit.dev/docs/components/properties/) ### 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 HTML markup, text, icons, or images. -- There are cases in which adding content as a property will make sense, for example using a title to control the state of the component. Use this cautiously, as it can cause issues with a11y tools and automation. + - Properties and slots should mirror HTML as close as possible. For example, if something would just be a in a div, it should probably be a slot. However, something like an aria-label should typically be a property. + - Properties are used for non-content features that impact the state of the component. Non-content here means any structured data that isn't just HTML. For example, active versus inactive states. + - There are some exceptions, such as making alt-text for images, which might make more sense to be a property. +- 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. +- There are definitely cases where a component is doing something internally that warrants reflecting its internal state back in the HTML markup regardless of any user action. For example, detecting dark mode or an a11y config. +- In general slots are used for content, such as HTML markup, text, icons, or images. +- The more of the component that is slots, the more flexible the component will be. +- There are cases in which adding content as a property will make sense, for example using a title to control the state of the component. Use this cautiously, as it can cause issues with a11y tools and automation. This is mostly only with older tools/ low quality tools. ### Property with default value