From c959d080edc66b20eab87ae47a5cc1e61b105440 Mon Sep 17 00:00:00 2001 From: Erin Donehoo Date: Mon, 10 Oct 2022 16:37:14 -0400 Subject: [PATCH 1/6] Adds content to page component react examples. --- .../src/components/Page/examples/Page.md | 70 +++++++++++++++---- 1 file changed, 55 insertions(+), 15 deletions(-) diff --git a/packages/react-core/src/components/Page/examples/Page.md b/packages/react-core/src/components/Page/examples/Page.md index 3ee6a7075e5..242e374ff44 100644 --- a/packages/react-core/src/components/Page/examples/Page.md +++ b/packages/react-core/src/components/Page/examples/Page.md @@ -23,49 +23,89 @@ import './page.css'; ## Examples -### Vertical nav +### Basic page components + +A page will typically contain the following components: + +- A header [toolbar](/components/toolbar) with ``, which often contains actions, icons, buttons, and/or dropdown menus. +- A [masthead](/components/masthead) with a `` that contains the ``, a ``that contains the ``, and `` that contains the page's header toolbar. +- A `` with, a `header` that often contains a masthead, a ``, and one or more `` components. + +### Vertical navigation + +To add vertical side navigation to a ``, pass a `` component into the `sidebar` property. To render navigation in the ``, use the `nav` property. + +The `isNavOpen` property helps facilitate the opening and closing of the sidebar and should be 'true' when the navigation sidebar is visible. ```ts file="./PageVerticalNav.tsx" ``` -### Horizontal nav +### Legacy vertical navigation + +This example shows the legacy implementation of a page's vertical navigation. Our updated recommendation advises you to use a masthead and toolbar to make headers, rather than `` and `` as shown in the following example. + +```ts file="./PageVerticalNavUsingPageHeaderComponent.tsx" +``` + +### Horizontal navigation + +To add horizontal top navigation to a ``, each navigation item should be set as a `` in the `` that is passed to the ``. ```ts file="./PageHorizontalNav.tsx" ``` -### Tertiary nav +### Tertiary navigation + +To add a tertiary navigation component to a page, use the `tertiaryNav` property. The following example passes a string of ‘Navigation’ to `tertiaryNav`, but you can pass fully built-out components, such as navigation. + +In this example, `` sets the `display` property equal to "{{ default: 'stack' }}" to stack the masthead items and also passes in "inset={{ default: 'insetXs' }}" to adjust the inset padding. ```ts file="./PageTertiaryNav.tsx" ``` -### With or without fill +### Uncontrolled nav + +When the `isManagedSidebar` property is true, it manages the sidebar open/close state, removing the need to pass both `isNavOpen` into the `` and `onNavToggle` into the ``. + +```ts file="./PageUncontrolledNav.tsx" +``` + +### Filled page sections + +To make a `` fill the available vertical space of the page, set the `isFilled` property equal to true. + +By default, the last page section sets `isFilled` equal to true. ```ts file="./PageWithOrWithoutFill.tsx" ``` ### Main section padding -```ts file="./PageMainSectionPadding.tsx" -``` +To adjust the padding of a ``, you can pass in different values to the `padding` property. These value should be aligned to various breakpoints, including 'default', 'sm', 'md', 'lg', 'xl', '2xl'. -### Uncontrolled nav +To remove padding, pass 'noPadding' into `padding`. For example, the second section in this example passes in `padding={{ default: 'noPadding' }}`. Since no specific breakpoints are mentioned, every breakpoint will have 'noPadding'. -```ts file="./PageUncontrolledNav.tsx" -``` +To add padding on specific breakpoints, specify the value for those breakpoints. For example, the third section in this example passes in `padding={{ default: 'noPadding', md: 'padding', lg: 'padding' }}`. On 'md' and 'lg' breakpoints, the default value will be overwritten, and padding will be added. -### Group section +To remove padding at specific breakpoints, pass in 'noPadding' at those breakpoints. For example, the fourth section in this example passes in `padding={{ md: 'noPadding' }}`, which means that 'md' is the only breakpoint that will remove padding. -```ts file="./PageGroupSection.tsx" +```ts file="./PageMainSectionPadding.tsx" ``` -### Vertical nav using PageHeader component +### Group section -This example is provided because PageHeader and PageHeaderTools are still in use; however, going forward Masthead and Toolbar should be used to make headers rather than PageHeader and PageHeaderTools. +To group page content sections, add one or more `` components to a ``. -```ts file="./PageVerticalNavUsingPageHeaderComponent.tsx" +The following example adds a group containing both the `` and a section of content. + +```ts file="./PageGroupSection.tsx" ``` ### Centered section +When a width-limited page section is wider than the value of --pf-c-page--section--m-limit-width--MaxWidth, the section will be centered in the main section. + +The content in this example is placed in a card to better illustrate how the section behaves when it is centered. A card is not required to center a page section. + ```ts file="./PageCenteredSection.tsx" -``` +``` \ No newline at end of file From c77d1b3d73ecf81f8ca747811469062a97efffb9 Mon Sep 17 00:00:00 2001 From: Erin Donehoo Date: Thu, 17 Nov 2022 10:00:22 -0500 Subject: [PATCH 2/6] Content updates. --- packages/react-core/src/components/Page/examples/Page.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/packages/react-core/src/components/Page/examples/Page.md b/packages/react-core/src/components/Page/examples/Page.md index 242e374ff44..0a5fd971053 100644 --- a/packages/react-core/src/components/Page/examples/Page.md +++ b/packages/react-core/src/components/Page/examples/Page.md @@ -27,9 +27,8 @@ import './page.css'; A page will typically contain the following components: -- A header [toolbar](/components/toolbar) with ``, which often contains actions, icons, buttons, and/or dropdown menus. -- A [masthead](/components/masthead) with a `` that contains the ``, a ``that contains the ``, and `` that contains the page's header toolbar. -- A `` with, a `header` that often contains a masthead, a ``, and one or more `` components. +- A `` with a `header` that often contains a masthead, a ``, and one or more `` components. +-[Mastheads](/components/masthead) contain the ``, a `` that contains a ``, and the page's header toolbar within ``. ### Vertical navigation @@ -58,7 +57,7 @@ To add horizontal top navigation to a ``, each navigation item should be s To add a tertiary navigation component to a page, use the `tertiaryNav` property. The following example passes a string of ‘Navigation’ to `tertiaryNav`, but you can pass fully built-out components, such as navigation. -In this example, `` sets the `display` property equal to "{{ default: 'stack' }}" to stack the masthead items and also passes in "inset={{ default: 'insetXs' }}" to adjust the inset padding. +In this example, `` sets the `display` property equal to `"{{ default: 'stack' }}"` to stack the masthead items and also passes in `"inset={{ default: 'insetXs' }}"` to adjust the inset padding. ```ts file="./PageTertiaryNav.tsx" ``` From 50a7a0e19a175b2fead4507db0c85c33af4d0ae5 Mon Sep 17 00:00:00 2001 From: Erin Donehoo Date: Thu, 8 Dec 2022 12:55:40 -0500 Subject: [PATCH 3/6] Updates content based on feedback. --- .../src/components/Page/examples/Page.md | 47 ++++++++++++------- 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/packages/react-core/src/components/Page/examples/Page.md b/packages/react-core/src/components/Page/examples/Page.md index 0a5fd971053..45a05832d29 100644 --- a/packages/react-core/src/components/Page/examples/Page.md +++ b/packages/react-core/src/components/Page/examples/Page.md @@ -27,19 +27,21 @@ import './page.css'; A page will typically contain the following components: -- A `` with a `header` that often contains a masthead, a ``, and one or more `` components. --[Mastheads](/components/masthead) contain the ``, a `` that contains a ``, and the page's header toolbar within ``. +- A `` with a `header` that often contains a [masthead](/components/masthead) + - Mastheads contain the ``, a `` that contains a ``, and the page's header toolbar within ``. +- A `` for vertical navigation +- One or more `` components ### Vertical navigation -To add vertical side navigation to a ``, pass a `` component into the `sidebar` property. To render navigation in the ``, use the `nav` property. +To add a vertical sidebar to a ``, pass a `` component into the `sidebar` property. To render navigation in the sidebar, use the `nav` property of the ``. The `isNavOpen` property helps facilitate the opening and closing of the sidebar and should be 'true' when the navigation sidebar is visible. ```ts file="./PageVerticalNav.tsx" ``` -### Legacy vertical navigation +### Legacy page header This example shows the legacy implementation of a page's vertical navigation. Our updated recommendation advises you to use a masthead and toolbar to make headers, rather than `` and `` as shown in the following example. @@ -48,21 +50,21 @@ This example shows the legacy implementation of a page's vertical navigation. Ou ### Horizontal navigation -To add horizontal top navigation to a ``, each navigation item should be set as a `` in the `` that is passed to the ``. +To add horizontal top navigation to a ``, each navigation item should be set as a `` in the `` that is passed to the `` of the ``. ```ts file="./PageHorizontalNav.tsx" ``` -### Tertiary navigation +### Legacy tertiary navigation -To add a tertiary navigation component to a page, use the `tertiaryNav` property. The following example passes a string of ‘Navigation’ to `tertiaryNav`, but you can pass fully built-out components, such as navigation. +Horizontal sub-navigation is now recommended instead of tertiary-level navigation. -In this example, `` sets the `display` property equal to `"{{ default: 'stack' }}"` to stack the masthead items and also passes in `"inset={{ default: 'insetXs' }}"` to adjust the inset padding. +Tertiary navigation allows you to add an additional navigation menu alongside vertical or horizontal navigation. To create tertiary navigation, use the `tertiaryNav` property. The following example passes `tertiaryNav="Navigation"` into a `` component. ```ts file="./PageTertiaryNav.tsx" ``` -### Uncontrolled nav +### Uncontrolled navigation When the `isManagedSidebar` property is true, it manages the sidebar open/close state, removing the need to pass both `isNavOpen` into the `` and `onNavToggle` into the ``. @@ -71,22 +73,24 @@ When the `isManagedSidebar` property is true, it manages the sidebar open/close ### Filled page sections -To make a `` fill the available vertical space of the page, set the `isFilled` property equal to true. +By default, the last page section is "filled", meaning it fills the available vertifcal space of a page. -By default, the last page section sets `isFilled` equal to true. +To change the default behavior, use the `isFilled` property. To make other page sections "filled", set `isFilled` equal to "true". To disable the last page section from being "filled", set `isFilled` equal to "false". ```ts file="./PageWithOrWithoutFill.tsx" ``` ### Main section padding -To adjust the padding of a ``, you can pass in different values to the `padding` property. These value should be aligned to various breakpoints, including 'default', 'sm', 'md', 'lg', 'xl', '2xl'. +To adjust the padding of a ``, you can pass in different values to the `padding` property. These values should be aligned to a specific breakpoint: 'default', 'sm', 'md', 'lg', 'xl', and '2xl'. Each breakpoint passed into the property should be given a value of either ‘padding’ or ‘noPadding’. -To remove padding, pass 'noPadding' into `padding`. For example, the second section in this example passes in `padding={{ default: 'noPadding' }}`. Since no specific breakpoints are mentioned, every breakpoint will have 'noPadding'. +As the page's viewport width increases, breakpoints inherit the padding behavior of the previous breakpoint. For example, padding that is set on 'lg' also applies to 'xl' and '2xl'. -To add padding on specific breakpoints, specify the value for those breakpoints. For example, the third section in this example passes in `padding={{ default: 'noPadding', md: 'padding', lg: 'padding' }}`. On 'md' and 'lg' breakpoints, the default value will be overwritten, and padding will be added. +To remove padding entirely, pass 'noPadding' to the `default` breakpoint. For example, the second section in this example passes in `padding={{ default: 'noPadding' }}`. Since no specific breakpoints are mentioned, every breakpoint will have 'noPadding'. -To remove padding at specific breakpoints, pass in 'noPadding' at those breakpoints. For example, the fourth section in this example passes in `padding={{ md: 'noPadding' }}`, which means that 'md' is the only breakpoint that will remove padding. +To add padding at specific breakpoints, pass in "padding" at those breakpoints. For example, the third section in this example passes in `padding={{ default: 'noPadding', md: 'padding', lg: 'padding' }}`. At 'md', 'lg', 'xl' and '2xl' breakpoints, the default value will be overwritten, and padding will be added. + +To remove padding at specific breakpoints, pass in 'noPadding' at those breakpoints. For example, the fourth section in this example passes in `padding={{ md: 'noPadding' }}`, which means that 'md', ‘lg’ 'xl' and '2xl' breakpoints will have ‘noPadding’. ```ts file="./PageMainSectionPadding.tsx" ``` @@ -95,16 +99,23 @@ To remove padding at specific breakpoints, pass in 'noPadding' at those breakpoi To group page content sections, add one or more `` components to a ``. -The following example adds a group containing both the `` and a section of content. +The following example adds a group containing ``, ``, and `` components. + +To add additional components and information to a group, you may use the following properties: + +- To indicate that a breadcrumb should be in a group, use `isBreadcrumbGrouped`. +- To indicate that tertiary navigation should be in a group, use `isTertiaryNavGrouped`. +- To specify additional group content, use `additionalGroupedContent`. + ```ts file="./PageGroupSection.tsx" ``` ### Centered section -When a width-limited page section is wider than the value of --pf-c-page--section--m-limit-width--MaxWidth, the section will be centered in the main section. +By default, a page section spans the width of the page. To reduce the width of a section, use the `isWidthLimited` property. To center align width-limited page sections, use the `isCenterAligned` property. When a width-limited page section is wider than the value of `--pf-c-page--section--m-limit-width--MaxWidth`, the section will automatically be centered. -The content in this example is placed in a card to better illustrate how the section behaves when it is centered. A card is not required to center a page section. +The content in this example is placed in a card to better illustrate how the section behaves when it is centered, but a card is not required to center a page section. ```ts file="./PageCenteredSection.tsx" ``` \ No newline at end of file From d4093cdd5b44c4375d4179d76490c7a957700d7e Mon Sep 17 00:00:00 2001 From: Erin Donehoo Date: Thu, 15 Dec 2022 10:14:27 -0500 Subject: [PATCH 4/6] Further content edits. --- .../react-core/src/components/Page/examples/Page.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/react-core/src/components/Page/examples/Page.md b/packages/react-core/src/components/Page/examples/Page.md index 45a05832d29..de4cdcf82c9 100644 --- a/packages/react-core/src/components/Page/examples/Page.md +++ b/packages/react-core/src/components/Page/examples/Page.md @@ -50,14 +50,14 @@ This example shows the legacy implementation of a page's vertical navigation. Ou ### Horizontal navigation -To add horizontal top navigation to a ``, each navigation item should be set as a `` in the `` that is passed to the `` of the ``. +To add horizontal navigation to the top of a ``, add the navigation inside of a `` in the `` that is passed to the `` of the ``. ```ts file="./PageHorizontalNav.tsx" ``` ### Legacy tertiary navigation -Horizontal sub-navigation is now recommended instead of tertiary-level navigation. +[Horizontal sub-navigation](/components/navigation#horizontal-subnav) is now recommended instead of tertiary-level navigation. Tertiary navigation allows you to add an additional navigation menu alongside vertical or horizontal navigation. To create tertiary navigation, use the `tertiaryNav` property. The following example passes `tertiaryNav="Navigation"` into a `` component. @@ -73,7 +73,7 @@ When the `isManagedSidebar` property is true, it manages the sidebar open/close ### Filled page sections -By default, the last page section is "filled", meaning it fills the available vertifcal space of a page. +By default, the last page section is "filled", meaning it fills the available vertical space of a page. To change the default behavior, use the `isFilled` property. To make other page sections "filled", set `isFilled` equal to "true". To disable the last page section from being "filled", set `isFilled` equal to "false". @@ -88,9 +88,9 @@ As the page's viewport width increases, breakpoints inherit the padding behavior To remove padding entirely, pass 'noPadding' to the `default` breakpoint. For example, the second section in this example passes in `padding={{ default: 'noPadding' }}`. Since no specific breakpoints are mentioned, every breakpoint will have 'noPadding'. -To add padding at specific breakpoints, pass in "padding" at those breakpoints. For example, the third section in this example passes in `padding={{ default: 'noPadding', md: 'padding', lg: 'padding' }}`. At 'md', 'lg', 'xl' and '2xl' breakpoints, the default value will be overwritten, and padding will be added. +To add padding at specific breakpoints, pass in "padding" at those breakpoints. For example, the third section in this example passes in `padding={{ default: 'noPadding', md: 'padding' }}`. At 'md', 'lg', 'xl', and '2xl' breakpoints, the default value will be overwritten, and padding will be added. -To remove padding at specific breakpoints, pass in 'noPadding' at those breakpoints. For example, the fourth section in this example passes in `padding={{ md: 'noPadding' }}`, which means that 'md', ‘lg’ 'xl' and '2xl' breakpoints will have ‘noPadding’. +To remove padding at specific breakpoints, pass in 'noPadding' at those breakpoints. For example, the fourth section in this example passes in `padding={{ md: 'noPadding' }}`, which means that 'md', 'lg' 'xl', and '2xl' breakpoints will have `noPadding`. ```ts file="./PageMainSectionPadding.tsx" ``` @@ -113,7 +113,7 @@ To add additional components and information to a group, you may use the followi ### Centered section -By default, a page section spans the width of the page. To reduce the width of a section, use the `isWidthLimited` property. To center align width-limited page sections, use the `isCenterAligned` property. When a width-limited page section is wider than the value of `--pf-c-page--section--m-limit-width--MaxWidth`, the section will automatically be centered. +By default, a page section spans the width of the page. To reduce the width of a section, use the `isWidthLimited` property. To center align width-limited page sections, use the `isCenterAligned` property. When the main content area of a page is wider than the value of a centered, width-limited page section's `--pf-c-page--section--m-limit-width--MaxWidth` custom property, the section will automatically be centered. The content in this example is placed in a card to better illustrate how the section behaves when it is centered, but a card is not required to center a page section. From 56beb1444b850462625de6c62663ea4ef88853bb Mon Sep 17 00:00:00 2001 From: Michael Coker <35148959+mcoker@users.noreply.github.com> Date: Fri, 6 Jan 2023 15:08:11 -0600 Subject: [PATCH 5/6] chore(page): use numeral in example description --- packages/react-core/src/components/Page/examples/Page.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/react-core/src/components/Page/examples/Page.md b/packages/react-core/src/components/Page/examples/Page.md index de4cdcf82c9..a77037a6896 100644 --- a/packages/react-core/src/components/Page/examples/Page.md +++ b/packages/react-core/src/components/Page/examples/Page.md @@ -30,7 +30,7 @@ A page will typically contain the following components: - A `` with a `header` that often contains a [masthead](/components/masthead) - Mastheads contain the ``, a `` that contains a ``, and the page's header toolbar within ``. - A `` for vertical navigation -- One or more `` components +- 1 or more `` components ### Vertical navigation @@ -118,4 +118,4 @@ By default, a page section spans the width of the page. To reduce the width of a The content in this example is placed in a card to better illustrate how the section behaves when it is centered, but a card is not required to center a page section. ```ts file="./PageCenteredSection.tsx" -``` \ No newline at end of file +``` From c4d45d188f96121436d56d8bc4f9926d42c47807 Mon Sep 17 00:00:00 2001 From: Michael Coker <35148959+mcoker@users.noreply.github.com> Date: Fri, 6 Jan 2023 15:09:43 -0600 Subject: [PATCH 6/6] chore(page): use numeral in example description --- packages/react-core/src/components/Page/examples/Page.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react-core/src/components/Page/examples/Page.md b/packages/react-core/src/components/Page/examples/Page.md index a77037a6896..1a3eeee2a3c 100644 --- a/packages/react-core/src/components/Page/examples/Page.md +++ b/packages/react-core/src/components/Page/examples/Page.md @@ -97,7 +97,7 @@ To remove padding at specific breakpoints, pass in 'noPadding' at those breakpoi ### Group section -To group page content sections, add one or more `` components to a ``. +To group page content sections, add 1 or more `` components to a ``. The following example adds a group containing ``, ``, and `` components.