From a0c92b899d72c48fe56b79a7414018e8f65e8dcc Mon Sep 17 00:00:00 2001 From: Mariya Radchuk Date: Fri, 2 Aug 2024 17:14:09 +0200 Subject: [PATCH] docs(pie-docs): DSW-2224 checkbox group overview page (#1665) * docs(pie-docs): DSW-2224 checkbox group overview page * feat(pie-checkbox-group): DSW-2224 images update after the latest design review changes --- .changeset/spicy-numbers-doubt.md | 6 + .../img/components/checkbox-group/anatomy.svg | 39 ++++ .../checkbox-group/examples-ltr.svg | 20 ++ .../checkbox-group/examples-rtl.svg | 20 ++ .../modifiers-assistive-text.svg | 24 +++ .../checkbox-group/modifiers-form-label-1.svg | 16 ++ .../checkbox-group/modifiers-form-label-2.svg | 8 + .../components/checkbox-group/overflow.svg | 27 +++ .../components/checkbox-group/overview.svg | 34 +++ .../checkbox-group/states-disabled.svg | 16 ++ .../checkbox-group/states-error.svg | 24 +++ .../checkbox-group/variations-horizontal.svg | 16 ++ .../checkbox-group/variations-vertical.svg | 21 ++ .../checkbox/checkbox-checked-LTR.svg | 2 +- apps/pie-docs/src/componentStatusData.js | 38 ++++ .../checkbox-group/checkbox-group.json | 5 + .../checkbox-group/checkbox-group.md | 8 + .../checkbox-group/overview/overview.md | 196 ++++++++++++++++++ apps/pie-docs/src/components/chip/chip.md | 2 +- .../src/components/data-table/data-table.md | 2 +- .../data-visualisation/data-visualisation.md | 2 +- .../src/components/date-picker/date-picker.md | 2 +- .../snapshots/expected-routes.snapshot.json | 1 + 23 files changed, 524 insertions(+), 5 deletions(-) create mode 100644 .changeset/spicy-numbers-doubt.md create mode 100644 apps/pie-docs/src/assets/img/components/checkbox-group/anatomy.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox-group/examples-ltr.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox-group/examples-rtl.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox-group/modifiers-assistive-text.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox-group/modifiers-form-label-1.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox-group/modifiers-form-label-2.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox-group/overflow.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox-group/overview.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox-group/states-disabled.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox-group/states-error.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox-group/variations-horizontal.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox-group/variations-vertical.svg create mode 100644 apps/pie-docs/src/components/checkbox-group/checkbox-group.json create mode 100644 apps/pie-docs/src/components/checkbox-group/checkbox-group.md create mode 100644 apps/pie-docs/src/components/checkbox-group/overview/overview.md diff --git a/.changeset/spicy-numbers-doubt.md b/.changeset/spicy-numbers-doubt.md new file mode 100644 index 0000000000..3f5fb95f25 --- /dev/null +++ b/.changeset/spicy-numbers-doubt.md @@ -0,0 +1,6 @@ +--- +"pie-docs": minor +--- + +[Added] - PIE Checkbox Group Component overview page. +[Changed] - PIE Checkbox checkbox-checked-LTR.svg update. diff --git a/apps/pie-docs/src/assets/img/components/checkbox-group/anatomy.svg b/apps/pie-docs/src/assets/img/components/checkbox-group/anatomy.svg new file mode 100644 index 0000000000..ed3bd74f11 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox-group/anatomy.svg @@ -0,0 +1,39 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox-group/examples-ltr.svg b/apps/pie-docs/src/assets/img/components/checkbox-group/examples-ltr.svg new file mode 100644 index 0000000000..35a1ccea91 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox-group/examples-ltr.svg @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox-group/examples-rtl.svg b/apps/pie-docs/src/assets/img/components/checkbox-group/examples-rtl.svg new file mode 100644 index 0000000000..94f6b89581 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox-group/examples-rtl.svg @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox-group/modifiers-assistive-text.svg b/apps/pie-docs/src/assets/img/components/checkbox-group/modifiers-assistive-text.svg new file mode 100644 index 0000000000..120db6f90f --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox-group/modifiers-assistive-text.svg @@ -0,0 +1,24 @@ + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox-group/modifiers-form-label-1.svg b/apps/pie-docs/src/assets/img/components/checkbox-group/modifiers-form-label-1.svg new file mode 100644 index 0000000000..90e86ec635 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox-group/modifiers-form-label-1.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox-group/modifiers-form-label-2.svg b/apps/pie-docs/src/assets/img/components/checkbox-group/modifiers-form-label-2.svg new file mode 100644 index 0000000000..f6216e36dc --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox-group/modifiers-form-label-2.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox-group/overflow.svg b/apps/pie-docs/src/assets/img/components/checkbox-group/overflow.svg new file mode 100644 index 0000000000..09e0ab6c90 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox-group/overflow.svg @@ -0,0 +1,27 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox-group/overview.svg b/apps/pie-docs/src/assets/img/components/checkbox-group/overview.svg new file mode 100644 index 0000000000..48e912572f --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox-group/overview.svg @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox-group/states-disabled.svg b/apps/pie-docs/src/assets/img/components/checkbox-group/states-disabled.svg new file mode 100644 index 0000000000..e5f56aa0bc --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox-group/states-disabled.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox-group/states-error.svg b/apps/pie-docs/src/assets/img/components/checkbox-group/states-error.svg new file mode 100644 index 0000000000..8520b15bf7 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox-group/states-error.svg @@ -0,0 +1,24 @@ + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox-group/variations-horizontal.svg b/apps/pie-docs/src/assets/img/components/checkbox-group/variations-horizontal.svg new file mode 100644 index 0000000000..e3e4eed148 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox-group/variations-horizontal.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox-group/variations-vertical.svg b/apps/pie-docs/src/assets/img/components/checkbox-group/variations-vertical.svg new file mode 100644 index 0000000000..5daf066f85 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox-group/variations-vertical.svg @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-checked-LTR.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-checked-LTR.svg index 86f3a48b25..77b3020906 100644 --- a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-checked-LTR.svg +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-checked-LTR.svg @@ -1,6 +1,6 @@ - + diff --git a/apps/pie-docs/src/componentStatusData.js b/apps/pie-docs/src/componentStatusData.js index e6bc2c9b01..b7bfbb1697 100644 --- a/apps/pie-docs/src/componentStatusData.js +++ b/apps/pie-docs/src/componentStatusData.js @@ -470,6 +470,44 @@ const rows = [ status: statusTypes.STABLE, } ], + [ + { componentName: 'Checkbox Group' }, + { + resource: resourceTypes.COMPONENT, + link: 'https://www.figma.com/file/aD4m0j97Ruw8Q4S5lED2Bl/Checkbox-audit?node-id=6312-11778&t=7rNtILex9xojH5wx-4', + status: statusTypes.STABLE, + }, + { + resource: resourceTypes.DOCUMENTATION, + link: 'https://www.figma.com/file/aD4m0j97Ruw8Q4S5lED2Bl/Checkbox-audit?node-id=9938-14138&t=8Cx93DX9PwzEgNJS-4', + status: statusTypes.STABLE, + }, + { + resource: resourceTypes.WEB_COMPONENTS, + status: webComponentStatuses['pie-checkbox-group'], + }, + { + resource: resourceTypes.VUE, + status: statusTypes.NOT_APPLICABLE, + }, + { + resource: resourceTypes.REACT, + link: 'https://snacks.takeaway.com/portal/components/checkbox-group/', + status: statusTypes.STABLE, + }, + { + resource: resourceTypes.IOS_JUST_UI, + status: statusTypes.NOT_APPLICABLE, + }, + { + resource: resourceTypes.IOS_PIE, + status: statusTypes.NOT_APPLICABLE, + }, + { + resource: resourceTypes.ANDROID_PIE, + status: statusTypes.NOT_APPLICABLE, + } + ], [ { componentName: 'Chip' }, { diff --git a/apps/pie-docs/src/components/checkbox-group/checkbox-group.json b/apps/pie-docs/src/components/checkbox-group/checkbox-group.json new file mode 100644 index 0000000000..49cc85b771 --- /dev/null +++ b/apps/pie-docs/src/components/checkbox-group/checkbox-group.json @@ -0,0 +1,5 @@ +{ + "title": "Checkbox Group", + "navKey": "Checkbox Group", + "description": "A checkbox group is a helper component that groups Checkbox components into a visual and functional group." + } diff --git a/apps/pie-docs/src/components/checkbox-group/checkbox-group.md b/apps/pie-docs/src/components/checkbox-group/checkbox-group.md new file mode 100644 index 0000000000..a5cc49d15d --- /dev/null +++ b/apps/pie-docs/src/components/checkbox-group/checkbox-group.md @@ -0,0 +1,8 @@ +--- +eleventyNavigation: + key: 'Checkbox Group' + parent: Components + url: /components/checkbox-group/ + order: 13 +permalink: false +--- diff --git a/apps/pie-docs/src/components/checkbox-group/overview/overview.md b/apps/pie-docs/src/components/checkbox-group/overview/overview.md new file mode 100644 index 0000000000..3f3085d6db --- /dev/null +++ b/apps/pie-docs/src/components/checkbox-group/overview/overview.md @@ -0,0 +1,196 @@ +--- +eleventyNavigation: + key: Overview + parent: 'Checkbox Group' + order: 1 +shouldShowContents: true +permalink: components/checkbox-group/ +--- + +## Overview + +Checkbox groups offer users a binary selection method, allowing them to make multiple selections from a predefined set of options. Each checkbox functions independently, providing immediate feedback through its checked or unchecked state. + +These groups are frequently utilised in forms, settings panels, and various interfaces requiring users to make multiple selections or provide input from predefined options. + +{% contentPageImage { + src:"../../../assets/img/components/checkbox-group/overview.svg", + alt: "Four vertically aligned checkboxes with 'Restaurant settings' group label with second option checked." +} %} + +--- + +## Dos and Don’ts + +{% usage { + do: { + type: usageTypes.text, + items: [ + "Ensure each checkbox has a concise and descriptive label that clearly indicates what selecting it will entail.", + "Use a minimum of 2 checkboxes within a group." + ] + }, + dont: { + type: usageTypes.text, + items: [ + "If the user can only select one option from a group, radio buttons should be used instead of checkboxes.", + "Limit the number of checkboxes presented to users to avoid overwhelming them with choices." + ] + } +} %} + +--- + +## Anatomy + +{% contentPageImage { + src:"../../../assets/img/components/checkbox-group/anatomy.svg", + alt: "Three horizontally aligned checkboxes with numbers specifying four different parts of checkbox group anatomy.", + width: "338px" +} %} + +{% list { + type: listTypes.ordered, + items: [ + "**Form label (Optional):** The [form label](/components/form-label/) provides necessary content / information to a form.", + "**Checkbox input:** A checkbox input indicates the appropriate state. By default it is unselected.", + "**Checkbox label:** Describes the information you want to select or unselect.", + "**Assistive text (Optional):** The [assistive text](/components/assistive-text/) provides additional instructional information / error / success messaging for the whole checkbox group." + ] +} %} + +--- + +## Variations + +Checkbox groups can be laid out both horizontally and vertically depending on the use case and the structure of the UI. Where possible, arrange the checkbox group vertically for easier reading. + +### Horizontal + +{% contentPageImage { + src:"../../../assets/img/components/checkbox-group/variations-horizontal.svg", + alt: "Three horizontally aligned checkboxes with group label.", + width: "258px" +} %} + +### Vertical + +{% contentPageImage { + src:"../../../assets/img/components/checkbox-group/variations-vertical.svg", + alt: "Three vertically aligned checkboxes with group label.", + width: "71px" +} %} + +--- + +## Modifiers + +### Form label + +A form label is recommended to provide the user context of the form element and it’s content. + +{% contentLayout %} + {% contentItem %} + {% contentPageImage { + src: "../../../assets/img/components/checkbox-group/modifiers-form-label-1.svg", + width: "258px", + alt: "Three horizontally aligned checkboxes with group label." + } %} + {% endcontentItem %} + {% contentItem %} + {% contentPageImage { + src: "../../../assets/img/components/checkbox-group/modifiers-form-label-2.svg", + width: "258px", + alt: "Three horizontally aligned checkboxes without group label." + } %} + {% endcontentItem %} +{% endcontentLayout %} + +### Assistive text + +Assistive text is used where needed to provide additional information or error / success messaging regarding the whole form element, and never to individual checkboxes. The assistive text is always used for an error state to provide the user with the information required to complete the form element. + +{% contentPageImage { + src:"../../../assets/img/components/checkbox-group/modifiers-assistive-text.svg", + alt: "Three horizontally aligned checkboxes with group label and red assistive text underneath specifying error state.", + width: "258px" +} %} + +--- + +## Content + +All content should use sentence case. + +### Label + +- Always use clear and concise labels for checkbox group. + +--- + +## Overflow + +### Multiple words overflow + +When the label exceeds the available width, the label will wrap onto a new line. Checkboxes with the same row remain top aligned for consistency, and any additional rows underneath move down to accommodate the additional content. + +{% contentPageImage { + src:"../../../assets/img/components/checkbox-group/overflow.svg", + alt: "Six horizontally aligned checkboxes. First checkbox has a label that overflows to a second line. ", + width: "469px" +} %} + +--- + +## States + +Individual checkbox’s have their own interactive states: default, hover, active, and focus. However, some states apply to the group as a collective because they affect all checkboxes: error and disabled. + +{% contentLayout %} + {% contentItem %} + {% contentPageImage { + src: "../../../assets/img/components/checkbox-group/states-error.svg", + width: "258px", + alt: "Three horizontally aligned checkboxes with group label and red assistive text underneath specifying error state." + } %} + {% endcontentItem %} + {% contentItem %} + {% contentPageImage { + src: "../../../assets/img/components/checkbox-group/states-disabled.svg", + width: "258px", + alt: "Three horizontally aligned checkboxes with group label. Checkbox boxes are greyed out to specify a disabled state." + } %} + {% endcontentItem %} +{% endcontentLayout %} + +--- + +## Examples + +### LTR examples + +Here are some examples of the component in a left-to-right context: + +{% contentPageImage { + src:"../../../assets/img/components/checkbox-group/examples-ltr.svg", + alt: "Two vertically aligned checkboxes with a group label aligned to the right.", + width: "141px" +} %} + +### RTL examples + +Here are some examples of the component in a right-to-left context: + +{% contentPageImage { + src:"../../../assets/img/components/checkbox-group/examples-rtl.svg", + alt: "Two vertically aligned checkboxes with a group label aligned to the left.", + width: "132px" +} %} + +--- + +## Resources + +{% resourceTable { + componentName: 'Checkbox Group' +} %} diff --git a/apps/pie-docs/src/components/chip/chip.md b/apps/pie-docs/src/components/chip/chip.md index cb7f3d7973..7d98cbf60a 100644 --- a/apps/pie-docs/src/components/chip/chip.md +++ b/apps/pie-docs/src/components/chip/chip.md @@ -2,7 +2,7 @@ eleventyNavigation: key: Chip parent: Components - order: 13 + order: 14 url: /components/chip/ permalink: false --- diff --git a/apps/pie-docs/src/components/data-table/data-table.md b/apps/pie-docs/src/components/data-table/data-table.md index f9c7f320ff..504419e99c 100644 --- a/apps/pie-docs/src/components/data-table/data-table.md +++ b/apps/pie-docs/src/components/data-table/data-table.md @@ -2,7 +2,7 @@ eleventyNavigation: key: 'Data Table' parent: Components - order: 14 + order: 15 --- ## Overview diff --git a/apps/pie-docs/src/components/data-visualisation/data-visualisation.md b/apps/pie-docs/src/components/data-visualisation/data-visualisation.md index 600c2aae89..dc002aaf14 100644 --- a/apps/pie-docs/src/components/data-visualisation/data-visualisation.md +++ b/apps/pie-docs/src/components/data-visualisation/data-visualisation.md @@ -3,7 +3,7 @@ eleventyNavigation: key: data-visualisation title: 'Data Visualisation' parent: Components - order: 15 + order: 16 subPageDropdown: true title: 'Data Visualisation' --- diff --git a/apps/pie-docs/src/components/date-picker/date-picker.md b/apps/pie-docs/src/components/date-picker/date-picker.md index 2116959fc6..1000b37132 100644 --- a/apps/pie-docs/src/components/date-picker/date-picker.md +++ b/apps/pie-docs/src/components/date-picker/date-picker.md @@ -2,7 +2,7 @@ eleventyNavigation: key: 'Date Picker' parent: Components - order: 16 + order: 17 --- ## Overview diff --git a/apps/pie-docs/test/snapshots/expected-routes.snapshot.json b/apps/pie-docs/test/snapshots/expected-routes.snapshot.json index 1c337704de..1ae355f914 100644 --- a/apps/pie-docs/test/snapshots/expected-routes.snapshot.json +++ b/apps/pie-docs/test/snapshots/expected-routes.snapshot.json @@ -23,6 +23,7 @@ "components/card/code", "components/carousel-indicator", "components/checkbox", + "components/checkbox-group", "components/chip", "components/chip/code", "components/component-status",