From f806d90a4e8afff6a807c942e60476a1b0cb586a Mon Sep 17 00:00:00 2001 From: Stephen Watkins Date: Wed, 16 Aug 2023 17:13:32 -0400 Subject: [PATCH 1/5] initial adr --- .../decisions/012_include_layouts.md | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 documentation/decisions/012_include_layouts.md diff --git a/documentation/decisions/012_include_layouts.md b/documentation/decisions/012_include_layouts.md new file mode 100644 index 000000000..f81a5f987 --- /dev/null +++ b/documentation/decisions/012_include_layouts.md @@ -0,0 +1,71 @@ +--- +status: Approved +date: 2023-08-17 +deciders: stephenjwatkins, OskiTheCoder, ldewald +--- + +# Include layouts in Easy UI + +## Context and Problem Statement + +Easy UI needs to determine if it will include site-specific layouts in its component library. + +While shared components are more obviously included in component libraries, broader-scoped components such as layouts are often deferred to their respective app. There are reasons to include them in a component library however. This decision will record will analyze the situation and make a determination that suits its requirements. + +## Decision Drivers + +- Non-disruptive to site developers +- Layouts should play well with frameworks and site-level architectures +- Site-specific logic can be deferred to the consumer +- Quality standards can be met + +## Options Considered + +- Include layouts in Easy UI +- Create a "Patterns" guide for creating layouts using Easy UI components +- Create a generic PageLayout component that can scaffold an array of generic configurations +- Defer layout responsibility entirely to their respective site + +## Decision Outcome + +Easy UI will include layouts in its component library as Shell components. Shell components will only concern itself with presentation, deferring business logic to the consumer. + +## Analysis + +Researched how component libraries do this. Per usual, every component library does it differently. Some component libraries include concrete page layouts with targeted hooks for content. Other times component libraries provide a generic page layout component that allows for broad-use slotting in of content. And others simply provide a "Patterns" section in their library documentation that guides consumers how to construct layouts using components in the libraries. Finally, it could be an aspect that the component library doesn't deal with at all. + +There are advantages and disadvantages to each approach. + +By not dealing with it at all, it eases the burden of the component library. The library can focus exclusively on shared concerns and lower-level matters. This puts the responsibility on the consumer, however, to "fend for itself". This allows the consumer to work fast and flexibly at the cost of potential inconsistency and lower standards. + +By deferring complete responsibility to the consumer with patterns, you allow the consuming site to have complete control over its layout, presentation included. This obviously allows the most freedom and flexibility and general nimbleness to the specific site. This results in a faster short term result. The cost of this approach is that it can lead to general inconsistencies across the Web ecosystem, as well as lower the bar on quality standards. + +Using a more generic page layout component can sometimes be beneficial by allowing a more freeform "page builder" kind of pattern. This pattern allows for a large set of pages to be composed by providing an outer container with varying inner components that can be stacked on top of each other. This can be common for marketing pages where content is varying and more freeform, but it can also be used for appy sites. See Atlaskit's PageLayout component as an example. + +Finally, some component libraries provide specific page components that should be directly used by consumers. They provide properties on these components to allow for a specific level of customization to the consumer, but by and large the presentation and structure is locked down by the component itself. While this reduces the level of flexibility and control by the consumer, it has the advantage of allowing the consumer to do less work while leading to a more cohesive UI ecosystem with higher UX standards due to the UX tooling accompanying the component library. + +It's worth noting that none of these approaches include business logic as part of the component. Only presentational concerns. Business logic should be left to the consuming site. They are each just varying degrees of how much presentation is locked down by the component in the component library. + +Due to the makeup of the organization at EasyPost, we will include concrete page layouts with targeted hooks for conent in Easy UI. Consuming sites will have control over the business logic and any presentational hooks will be dictated by design. This decison will benefit our ecosystem by ensuring there is consistency and a higher quality standard with the Easy UI tooling and processes. + +While we will include these components in Easy UI, we will not dilute the specific meaning of the names "page" and "layout" in web frameworks. Pages are often the leaf node in routing structures, while layouts are branches in the routing hierarchy. Pages and layouts often carry certain business logic pertaining to that part of the routing tree. As such, because Easy UI only concerns itself with presentational concerns, we should avoid naming components that could conflict with these existing semantics. So we'll use the suffix "Shell" to denote that it only contains the presentational shell of the respective layout. + +## Example + +Shells can be used inside existing layouts: + +```tsx +import { ProductShell } from "@easypost/easy-ui/FocusedProductLayout"; + +function DashboardLayout() { + // handles business logic for determining logged in user, redirects, etc + return ( + + + + {children} + + + ); +} +``` From 2d8165a94103f6dee0c72417d55a8c01810c8043 Mon Sep 17 00:00:00 2001 From: Stephen Watkins Date: Thu, 17 Aug 2023 15:20:38 -0400 Subject: [PATCH 2/5] add layouts adr --- .../decisions/012_include_layouts.md | 71 ------------------- documentation/decisions/012_page_layouts.md | 66 +++++++++++++++++ 2 files changed, 66 insertions(+), 71 deletions(-) delete mode 100644 documentation/decisions/012_include_layouts.md create mode 100644 documentation/decisions/012_page_layouts.md diff --git a/documentation/decisions/012_include_layouts.md b/documentation/decisions/012_include_layouts.md deleted file mode 100644 index f81a5f987..000000000 --- a/documentation/decisions/012_include_layouts.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -status: Approved -date: 2023-08-17 -deciders: stephenjwatkins, OskiTheCoder, ldewald ---- - -# Include layouts in Easy UI - -## Context and Problem Statement - -Easy UI needs to determine if it will include site-specific layouts in its component library. - -While shared components are more obviously included in component libraries, broader-scoped components such as layouts are often deferred to their respective app. There are reasons to include them in a component library however. This decision will record will analyze the situation and make a determination that suits its requirements. - -## Decision Drivers - -- Non-disruptive to site developers -- Layouts should play well with frameworks and site-level architectures -- Site-specific logic can be deferred to the consumer -- Quality standards can be met - -## Options Considered - -- Include layouts in Easy UI -- Create a "Patterns" guide for creating layouts using Easy UI components -- Create a generic PageLayout component that can scaffold an array of generic configurations -- Defer layout responsibility entirely to their respective site - -## Decision Outcome - -Easy UI will include layouts in its component library as Shell components. Shell components will only concern itself with presentation, deferring business logic to the consumer. - -## Analysis - -Researched how component libraries do this. Per usual, every component library does it differently. Some component libraries include concrete page layouts with targeted hooks for content. Other times component libraries provide a generic page layout component that allows for broad-use slotting in of content. And others simply provide a "Patterns" section in their library documentation that guides consumers how to construct layouts using components in the libraries. Finally, it could be an aspect that the component library doesn't deal with at all. - -There are advantages and disadvantages to each approach. - -By not dealing with it at all, it eases the burden of the component library. The library can focus exclusively on shared concerns and lower-level matters. This puts the responsibility on the consumer, however, to "fend for itself". This allows the consumer to work fast and flexibly at the cost of potential inconsistency and lower standards. - -By deferring complete responsibility to the consumer with patterns, you allow the consuming site to have complete control over its layout, presentation included. This obviously allows the most freedom and flexibility and general nimbleness to the specific site. This results in a faster short term result. The cost of this approach is that it can lead to general inconsistencies across the Web ecosystem, as well as lower the bar on quality standards. - -Using a more generic page layout component can sometimes be beneficial by allowing a more freeform "page builder" kind of pattern. This pattern allows for a large set of pages to be composed by providing an outer container with varying inner components that can be stacked on top of each other. This can be common for marketing pages where content is varying and more freeform, but it can also be used for appy sites. See Atlaskit's PageLayout component as an example. - -Finally, some component libraries provide specific page components that should be directly used by consumers. They provide properties on these components to allow for a specific level of customization to the consumer, but by and large the presentation and structure is locked down by the component itself. While this reduces the level of flexibility and control by the consumer, it has the advantage of allowing the consumer to do less work while leading to a more cohesive UI ecosystem with higher UX standards due to the UX tooling accompanying the component library. - -It's worth noting that none of these approaches include business logic as part of the component. Only presentational concerns. Business logic should be left to the consuming site. They are each just varying degrees of how much presentation is locked down by the component in the component library. - -Due to the makeup of the organization at EasyPost, we will include concrete page layouts with targeted hooks for conent in Easy UI. Consuming sites will have control over the business logic and any presentational hooks will be dictated by design. This decison will benefit our ecosystem by ensuring there is consistency and a higher quality standard with the Easy UI tooling and processes. - -While we will include these components in Easy UI, we will not dilute the specific meaning of the names "page" and "layout" in web frameworks. Pages are often the leaf node in routing structures, while layouts are branches in the routing hierarchy. Pages and layouts often carry certain business logic pertaining to that part of the routing tree. As such, because Easy UI only concerns itself with presentational concerns, we should avoid naming components that could conflict with these existing semantics. So we'll use the suffix "Shell" to denote that it only contains the presentational shell of the respective layout. - -## Example - -Shells can be used inside existing layouts: - -```tsx -import { ProductShell } from "@easypost/easy-ui/FocusedProductLayout"; - -function DashboardLayout() { - // handles business logic for determining logged in user, redirects, etc - return ( - - - - {children} - - - ); -} -``` diff --git a/documentation/decisions/012_page_layouts.md b/documentation/decisions/012_page_layouts.md new file mode 100644 index 000000000..25bfebbb2 --- /dev/null +++ b/documentation/decisions/012_page_layouts.md @@ -0,0 +1,66 @@ +--- +status: Approved +date: 2023-08-17 +deciders: stephenjwatkins, OskiTheCoder, ldewald +--- + +# Incorporate page layouts in Easy UI + +## Context and Problem Statement + +Easy UI is evaluating the inclusion of site-specific page layouts in its component library. While shared, specialized components are commonly part of libraries, broader page layout components are often left to the app. This decision record will assess the situation and attempt to align with the organization's needs. + +## Decision Drivers + +- Compatibility with frameworks and site architectures +- Support for site-specific business logic and extensibility +- Adherence to quality standards +- Scalability with evolving design, Easy UI, and consuming sites +- Minimal disruption for site developers + +## Options Considered + +- Include page layout components in Easy UI +- Develop a "Patterns" guide for Easy UI-based page layout creation +- Opt-out of page layouts, deferring responsibility to sites + +## Decision Outcome + +Easy UI will incorporate layouts into its component library as "PageShell" components, focusing solely on presentation while delegating business logic to consumers. + +## Analysis + +Various component libraries adopt different strategies for managing page layouts, each with its own set of advantages and limitations. These strategies include: + +**Opting Out**: Some component libraries choose not to include predefined page layouts. This approach allows the library to focus on specific, shared functionalities. While it reduces responsibilities for platform teams, it places greater onus on feature teams. As a consequence, without the support of component library tools, feature teams might need to reimplement certain elements, potentially leading to inconsistent and suboptimal user experiences (UX). + +**Using Documented "Patterns"**: Some component libraries provide users with documented "Patterns" to guide them in creating layouts using the library's components. This approach simplifies implementation compared to starting from scratch and permits customization at the site level. However, it can still result in disparities and duplicated efforts over time. For this method to be successful, Easy UI must build and document all essential components necessary for building page layouts. + +**Including Page Layouts**: Another approach involves supplying dedicated page layout components with predefined slots for content placement. This shifts the responsibility onto the component library and platform team, reducing the implementation burden on feature teams. This approach limits flexibility outside the library and mandates updates to adhere to the component library's processes. Nonetheless, this facilitates the use of component library tooling and processes, enhancing consistency and UX. + +It's important to emphasize that, regardless of the approach chosen, the handling of business logic remains the responsibility of the consumer. Components should exclusively address presentation-related matters. + +Given EasyPost's organizational structure, characterized by distinct feature teams and relatively subpar UX tooling/processes beyond the component library, we opt to develop and maintain page layout components within Easy UI. These page layout components will include essential properties and hooks, enabling consuming sites to meet their individual design and feature requisites. This decision benefits our entire platform by promoting uniformity and upholding higher quality standards, particularly for page layouts being some of the more UI-challenging aspects of our sites. + +**Regarding Terminology:** Although we will incorporate these components into Easy UI, we intend to preserve the distinct meanings of "page" and "layout" found in web frameworks. "Pages" often represent terminal nodes in routing structures, whereas "layouts" signify branches. Both pages and layouts commonly involve specific business logic pertaining to their respective parts of the routing tree. Since Easy UI exclusively deals with presentation-related concerns, we will avoid naming components in a way that might confuse or overlap with these established semantics. Instead, we will adopt the term "Shell" (i.e. `ProductShell`), to explicitly indicate that it encompasses the outer presentation container of the corresponding layout. + +## Example + +_app/layouts/DashboardLayout:_ + +```tsx +import { ProductShell } from "@easypost/easy-ui/FocusedProductLayout"; + +// DashboardLayout component handles site-specific business logic (e.g. +// determining logged in user, redirects, etc) +function DashboardLayout() { + return ( + + + + {children} + + + ); +} +``` From 61980b9f043eed41ef217945fae1a60865ef3346 Mon Sep 17 00:00:00 2001 From: Stephen Watkins Date: Thu, 17 Aug 2023 15:23:07 -0400 Subject: [PATCH 3/5] adjustments --- documentation/decisions/012_page_layouts.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/documentation/decisions/012_page_layouts.md b/documentation/decisions/012_page_layouts.md index 25bfebbb2..06ef786d8 100644 --- a/documentation/decisions/012_page_layouts.md +++ b/documentation/decisions/012_page_layouts.md @@ -56,11 +56,11 @@ import { ProductShell } from "@easypost/easy-ui/FocusedProductLayout"; function DashboardLayout() { return ( - - - {children} - + + ); } ``` + +Note that this isn't a spec, just a high-level example of how to think about what the component library would offer and how it could be incorporated into existing apps. From b7a89ee5950385bd690cc3b81cae4ab25c9d8620 Mon Sep 17 00:00:00 2001 From: Stephen Watkins Date: Thu, 17 Aug 2023 15:33:40 -0400 Subject: [PATCH 4/5] adjustments --- documentation/decisions/012_page_layouts.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/documentation/decisions/012_page_layouts.md b/documentation/decisions/012_page_layouts.md index 06ef786d8..d4b45657b 100644 --- a/documentation/decisions/012_page_layouts.md +++ b/documentation/decisions/012_page_layouts.md @@ -26,13 +26,13 @@ Easy UI is evaluating the inclusion of site-specific page layouts in its compone ## Decision Outcome -Easy UI will incorporate layouts into its component library as "PageShell" components, focusing solely on presentation while delegating business logic to consumers. +Easy UI will incorporate page layouts into its component library as "PageShell" components, focusing solely on presentation while delegating business logic to consumers. ## Analysis Various component libraries adopt different strategies for managing page layouts, each with its own set of advantages and limitations. These strategies include: -**Opting Out**: Some component libraries choose not to include predefined page layouts. This approach allows the library to focus on specific, shared functionalities. While it reduces responsibilities for platform teams, it places greater onus on feature teams. As a consequence, without the support of component library tools, feature teams might need to reimplement certain elements, potentially leading to inconsistent and suboptimal user experiences (UX). +**Opting Out**: Many component libraries choose not to include predefined page layouts. This approach allows the library to focus on specific, shared functionalities. While it reduces responsibilities for platform teams, it places greater onus on feature teams. As a consequence, without the support of component library tools, feature teams may need to implement elements of their own, potentially leading to inconsistent and suboptimal user experiences (UX). **Using Documented "Patterns"**: Some component libraries provide users with documented "Patterns" to guide them in creating layouts using the library's components. This approach simplifies implementation compared to starting from scratch and permits customization at the site level. However, it can still result in disparities and duplicated efforts over time. For this method to be successful, Easy UI must build and document all essential components necessary for building page layouts. @@ -40,7 +40,9 @@ Various component libraries adopt different strategies for managing page layouts It's important to emphasize that, regardless of the approach chosen, the handling of business logic remains the responsibility of the consumer. Components should exclusively address presentation-related matters. -Given EasyPost's organizational structure, characterized by distinct feature teams and relatively subpar UX tooling/processes beyond the component library, we opt to develop and maintain page layout components within Easy UI. These page layout components will include essential properties and hooks, enabling consuming sites to meet their individual design and feature requisites. This decision benefits our entire platform by promoting uniformity and upholding higher quality standards, particularly for page layouts being some of the more UI-challenging aspects of our sites. +**We opt to develop and maintain page layout components within Easy UI.** Considering EasyPost's organizational structure, which consists of distinct feature teams, and acknowledging the limited quality of UX tooling outside the component library, Easy UI emerges as the best choice for success with page layout components. + +These components will include essential properties and hooks, enabling consuming sites to meet their individual design and feature requisites. This decision benefits our entire platform by promoting uniformity and upholding higher quality standards, particularly for page layouts being some of the more UI-challenging aspects of our sites. **Regarding Terminology:** Although we will incorporate these components into Easy UI, we intend to preserve the distinct meanings of "page" and "layout" found in web frameworks. "Pages" often represent terminal nodes in routing structures, whereas "layouts" signify branches. Both pages and layouts commonly involve specific business logic pertaining to their respective parts of the routing tree. Since Easy UI exclusively deals with presentation-related concerns, we will avoid naming components in a way that might confuse or overlap with these established semantics. Instead, we will adopt the term "Shell" (i.e. `ProductShell`), to explicitly indicate that it encompasses the outer presentation container of the corresponding layout. From a6321fc472dd68e01b07fcc009fd700129b85f05 Mon Sep 17 00:00:00 2001 From: Stephen Watkins Date: Thu, 17 Aug 2023 15:34:11 -0400 Subject: [PATCH 5/5] remove note --- documentation/decisions/012_page_layouts.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/documentation/decisions/012_page_layouts.md b/documentation/decisions/012_page_layouts.md index d4b45657b..8406fb40b 100644 --- a/documentation/decisions/012_page_layouts.md +++ b/documentation/decisions/012_page_layouts.md @@ -64,5 +64,3 @@ function DashboardLayout() { ); } ``` - -Note that this isn't a spec, just a high-level example of how to think about what the component library would offer and how it could be incorporated into existing apps.