From 9f5b87a22c11f7d806294e124f592b6c9a33cec3 Mon Sep 17 00:00:00 2001 From: Parimal Satyal <88370597+psatyal@users.noreply.github.com> Date: Mon, 7 Nov 2022 10:37:58 +0100 Subject: [PATCH 1/6] Added new documentation Added: - Dropdown button - Dropdown menu - Toast Modified: - Tooltips --- .../tooltip/stories/Tooltip.stories.mdx | 30 +++++++++-- .../src/stories/DropdownButton.stories.mdx | 26 ++++++++++ frontend/src/stories/DropdownMenu.stories.mdx | 32 ++++++++++++ frontend/src/stories/Toast.stories.mdx | 51 +++++++++++++++++++ 4 files changed, 135 insertions(+), 4 deletions(-) create mode 100644 frontend/src/stories/DropdownButton.stories.mdx create mode 100644 frontend/src/stories/DropdownMenu.stories.mdx create mode 100644 frontend/src/stories/Toast.stories.mdx diff --git a/frontend/src/app/spot/components/tooltip/stories/Tooltip.stories.mdx b/frontend/src/app/spot/components/tooltip/stories/Tooltip.stories.mdx index 1dcbe7cf44..aa5f7ac8ae 100644 --- a/frontend/src/app/spot/components/tooltip/stories/Tooltip.stories.mdx +++ b/frontend/src/app/spot/components/tooltip/stories/Tooltip.stories.mdx @@ -27,15 +27,17 @@ import { SbTooltipComponent } from './Tooltip.component'; > Example of a tooltip -Tooltips are used to provide additional information about an interactive element on mouse hover. +The tooltip provides additional textual context on hover over interactive elements. + +This context can be used to provide additional information (hover over a "help" icon) or to signal state information (for example, if a certain item is disabled). By default, they take 100% of the width of the containing element. However, max-width should be specified manually for each tooltip, depending on the circumstances and placement of the element. -Tooltips have a min-width of X rem. +> Eg. Tooltip on a file list, on a file that is not available due to permissions issues -Tooltips automatically align themselves to the top or the bottom of the element it is attached to, depending on the positioning of the element in the viewport. +## Structure and Options -## Options +The tooltip is simply a text label. Tooltips by default have a dark gray background (_Gray 1: #333_), but a lighter version is also available with a sky blue background in the default theme (_Feedback/Info/Light_). @@ -65,3 +67,23 @@ export const Template = (args) => ({ {Template.bind({})} + + +## Behaviour + +The tooltip appears next to the item being hovered (which must never be covered), but does not follow the cursor. Hovering out of the element that triggered it will cause the tooltip disappear. + +Tooltips automatically align themselves to the top or the bottom of the element it is attached to, depending on the positioning of the element in the viewport. + +## Margins and Spacing + +A tooltip's width is generally determined by the containing text. + +However, due to technical limitations, there is a hard min-width of 20-rem and a max-width of 90vw. Tooltips shorter than 20-rem will have additional space on the rigth. + +The minimum width of the tooltip depends on the length of the text, and the maximum width depends on the width of the containing element. + +A tooltip can be multi-line if necessary (?) It is never truncated. + +> Eg. A long multi-line tooltip + diff --git a/frontend/src/stories/DropdownButton.stories.mdx b/frontend/src/stories/DropdownButton.stories.mdx new file mode 100644 index 0000000000..50159c5b4d --- /dev/null +++ b/frontend/src/stories/DropdownButton.stories.mdx @@ -0,0 +1,26 @@ +import { Meta, Story, Canvas } from '@storybook/addon-docs'; + + + +# Dropdown button + +> Example: Filter button with a badge value of 3. + +## Description + +The dropdown button is a special type of button with a permanent down arrow on the right edge (suggesting further actions) and an optional badge. + +## Behaviour + +Clicking on a dropdown button generally opens the dropdown menu, or a drop modal. When the menu or modal is open, clicking on the button again closes it. + +> Example: A more button that opens a dropdown menu + +In some (rarer) cases, it can open a panel. An example of this is the Filter button. + +## Options + +The badge is optional and can hold a number from 0 to 99. After 99, the number simply reads "99+". + + + diff --git a/frontend/src/stories/DropdownMenu.stories.mdx b/frontend/src/stories/DropdownMenu.stories.mdx new file mode 100644 index 0000000000..60a69b688b --- /dev/null +++ b/frontend/src/stories/DropdownMenu.stories.mdx @@ -0,0 +1,32 @@ +import { Meta, Story, Canvas } from '@storybook/addon-docs'; + + + +# Dropdown menu + +> Example: A dropdown menu with four items + +The dropdown menu is a contextual menu triggered by clicking on a dropdown button. It provides options to the use. + +## Structure and Options + +The dropdown menu consists of a list of items, generally *menu rows*, with an optional title. + +The title is not interactive. It serves to provide additional context, if necessary. + +A menu item is interactive and generally represents an action. + +## States + +Each menu item has three states: regular, hover and clicked. + +## Margins and Spacing + +Each item has a height of 1.5 rem. There is a 0.25 rem spacing between the optional icon and the label, and a 0.5 rem rem spacing to the left and right. + +The width is determined by the longest object, or can be defined manually. If defined manually, items that are very long and exceed this length are truncated. + +> Eg: a menu item that's very long and truncated + + + diff --git a/frontend/src/stories/Toast.stories.mdx b/frontend/src/stories/Toast.stories.mdx new file mode 100644 index 0000000000..2511ad77c7 --- /dev/null +++ b/frontend/src/stories/Toast.stories.mdx @@ -0,0 +1,51 @@ +import { Meta, Story, Canvas } from '@storybook/addon-docs'; + + + +# Toast + +> Example: A success toast + +Toasts are small generally one-line messages that appear to inform the user of the result of an action, or an update to the current view. + +## Structure and Options + +The toast consists of: + +- An optional icon +- A text +- A close button + +There are four types of toasts, each with a specific icon and colour associated with it: + +An **Information** toast is blue and provides the user with helpful information about the current view. + +> Eg: a blue notification toast (as it exists today) + +A **Success** toast is green and indicates to the user that an action has been successfully carried out. + +> Eg: a green success toast (as it exists today) + +A **Warning** toast is orange and indicates that there are potential risks or possibility of error. + +> Eg: an orange toast (is this used somewhere?) + +An **Error** toast is red and indicates that something did not not go as expected, and that there is a problem. + +> Eg: a red toast (as it exists today, when moving an WP in GANTT view is not possible) + +## Behaviour + +The toast appears either as result of user action (a work package attribute is modified, for example) or a background action (there are new notifications). + +The text is generally merely informational, although there might sometimes be a link with an approproate action. + +> Eg. Blue notification toast with "Load new notifications" link. + +Toasts do not disappear automatically; they must be manually closed by the user. + +Ideally, only one toast should be visible at any time. Hoever, there are circumstances where multiple toasts might be generated and visible to the user; in this case, the toasts must "pile" vertically with a 1 rem (?) spacing between them. + +## Margins and Spacing + +The toast has a height of 2.5 rem, with a 0.5 rem padding on all sides, and a 0.5 rem spacing between the icon, text and the close button. From 6bab602c3525673084c20c6941c4215398759b5a Mon Sep 17 00:00:00 2001 From: Parimal Satyal <88370597+psatyal@users.noreply.github.com> Date: Tue, 8 Nov 2022 10:36:16 +0100 Subject: [PATCH 2/6] Added docs for text field --- .gitignore | 1 + .../text-field/stories/TextField.stories.mdx | 70 +++++++++++++++++-- 2 files changed, 64 insertions(+), 7 deletions(-) diff --git a/.gitignore b/.gitignore index df9f9436af..30ef630ff2 100644 --- a/.gitignore +++ b/.gitignore @@ -132,3 +132,4 @@ structure.sql # lefthook.yml user override lefthook-local.yml +frontend/package-lock.json diff --git a/frontend/src/app/spot/components/text-field/stories/TextField.stories.mdx b/frontend/src/app/spot/components/text-field/stories/TextField.stories.mdx index 1a92487ea5..91b7b1a0ad 100644 --- a/frontend/src/app/spot/components/text-field/stories/TextField.stories.mdx +++ b/frontend/src/app/spot/components/text-field/stories/TextField.stories.mdx @@ -22,7 +22,13 @@ import { SpotTextFieldComponent } from '../text-field.component'; }} /> -# Text Fields +# Text Field + +The text field is one of the most common input elements used in a wide range of scenarios: fill a form, enter work package details, search for something, pick a date. + +## Structure and Options + +The most basic text field is simply an input field where the user can type in text. ({ }, }) + +The text field component affords a few optional elements: + +An optional icon can be added to the left edge to provide additional context when this is necessary (in a search field, for example): + +> Example: A search bar with a icon to the left + +An icon can also optionally be placed on the right edge. This arrow can provide additional hints on how the text input field will behave; for example, a right arrow might suggest that the value will be immediately submitted, or a down arrow might indicate that the text field will open a drop modal underneath it (a list of assignees, for example). + +The right icon can also be converted to an icon-only link that allows the user to clear the field. + +> Example: A text field with a search icon, preset text and a clear icon on the right + +## Behaviour + +Clicking on a text field will move it to the focused state. + +A text field can have placeholder text to provide additionanl context or information; this text is replaced by actual text that the user inputs, and is shown again only if the field is cleared. + {Template.bind({})} + +The clear icon-only link on the right only appears on some text fields. + +The width of a text field is fixed and defined either manually, or by the width of the containing element. When text exceeds the available width, it scrolls with the cursor within the text field (and clips on the other end). + +## States + +The **Default** state indicates that a text field is ready to accept text input. + + {Template.bind({})} + +The **Focus** state has a coloured outline, the same as any focused element in OpenProject. + +The **Hover** element has a darker border. + +The **Disabled** state shows all elements (including icons and any placeholder or input text) in grey, and makes any interaction impossible. + {Template.bind({})} + +The **Error** state puts a red outline around the text input. (_Note_: This state is only used when the text input is part of a _Form element_, which supplements this red outline with an message error message). The error state is usually temporary; fixing the cause of the error (via asyncronous form validation) usually allows it to revert back to the focus + +> Example: Error state + +## Margins and Spacing + +The text field has 0.5 rem left and right margins, and a 0.25 rem top and bottom margins. + +There is also a 0.25 rem spacing between items (icon and text). + + + + From f64a9aac8b0a9cd290a54189a53763847924c669 Mon Sep 17 00:00:00 2001 From: Parimal Satyal <88370597+psatyal@users.noreply.github.com> Date: Thu, 17 Nov 2022 16:45:08 +0100 Subject: [PATCH 3/6] Added docs re: section headers --- .../src/stories/SectionHeaders.stories.mdx | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 frontend/src/stories/SectionHeaders.stories.mdx diff --git a/frontend/src/stories/SectionHeaders.stories.mdx b/frontend/src/stories/SectionHeaders.stories.mdx new file mode 100644 index 0000000000..b123be6822 --- /dev/null +++ b/frontend/src/stories/SectionHeaders.stories.mdx @@ -0,0 +1,48 @@ +import { Meta, Story, Canvas } from '@storybook/addon-docs'; +import { moduleMetadata } from '@storybook/angular'; + +# Section Headers + +> Example: Section header example + +The section header is used to separate different sections of a page or a view, or different grouping of similar functionality. + +In the Files tab for example, the section header separates the Attachments section and the the different file storages that may be available to a work package. + +## Structure and Options + +Section headers are at their most basic form a label (in all-caps) with a line underneath. + +> Example of a basic section header + +However, they can be extended with a few additional features: + +**Left icon** +This icon can be added to provide context. In a files list, for example, the left icon is used to indicate to which storage provider (for example, Nextcloud) that file storage is linked. + +In some parts of the application, this icon is also used to indicate open/closed state when the section header functions as an accordian (see *Behaviour*). + +*Note: Since this element is always all-caps, the baseline of the font requires the icon to be raised by a few pixels. See* Margins and Spacing *for more details.* + +**Right icon** +The icon can be placed to the right of the text too, if required. This should be used sparingly. + +**Action** +This is usually a button on the far edge (by default the right edge) of the component, but can also be a link. This is used to provide additional contextual action related to that whole section (to access the home directory in Nextcloud in a new tab, for example). + +> Example of a section header with a left icon and an action (like a Nextcloud file storage) + +**Right position** +The entire structure can be inverted, with the action buton on the left and the title and icons on the right. This should ideally never be used, but exists because such a format already exists in some places. Use sparingly. + +## Behaviour + +The section header behaves either as a regular header (static) or as an accordian, where clicking on the entire section header will expand and collapse the content underneath. + +> Example: "Group by" accordian, like a cost report page + +## Margins and Spacing + +The headers have an 0.5 rem top and bottom margin. + + From e8758ba62c4fc213d550e830644a7ebfe76cc660 Mon Sep 17 00:00:00 2001 From: Parimal Satyal <88370597+psatyal@users.noreply.github.com> Date: Thu, 17 Nov 2022 16:52:08 +0100 Subject: [PATCH 4/6] Added the bit about icon baseline @b12f Does this work? --- frontend/src/stories/SectionHeaders.stories.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/frontend/src/stories/SectionHeaders.stories.mdx b/frontend/src/stories/SectionHeaders.stories.mdx index b123be6822..3f0d9e4521 100644 --- a/frontend/src/stories/SectionHeaders.stories.mdx +++ b/frontend/src/stories/SectionHeaders.stories.mdx @@ -45,4 +45,6 @@ The section header behaves either as a regular header (static) or as an accordia The headers have an 0.5 rem top and bottom margin. +Because the label is all-caps, the baseline of the font is (visually) slightly higher than it otherwise would have been with mixed case. If the optional icons are used, the CSS of this component automatically pushed them up by a few pixels for better alignment. + From ffa61606ff6cea2a6b55d371efad2f267702b0b9 Mon Sep 17 00:00:00 2001 From: Parimal Satyal <88370597+psatyal@users.noreply.github.com> Date: Mon, 21 Nov 2022 19:12:39 +0100 Subject: [PATCH 5/6] Updates after Marc's feedback Updated: - Text Field - Tooltip - Dropdown Menu - Section headers There are a few few more open questions, which will be handled in a separate commit. --- .../components/text-field/stories/TextField.stories.mdx | 6 +++--- .../spot/components/tooltip/stories/Tooltip.stories.mdx | 2 +- frontend/src/stories/DropdownMenu.stories.mdx | 7 +++++-- frontend/src/stories/SectionHeaders.stories.mdx | 8 ++++---- 4 files changed, 13 insertions(+), 10 deletions(-) diff --git a/frontend/src/app/spot/components/text-field/stories/TextField.stories.mdx b/frontend/src/app/spot/components/text-field/stories/TextField.stories.mdx index 91b7b1a0ad..470b142b27 100644 --- a/frontend/src/app/spot/components/text-field/stories/TextField.stories.mdx +++ b/frontend/src/app/spot/components/text-field/stories/TextField.stories.mdx @@ -59,7 +59,7 @@ An optional icon can be added to the left edge to provide additional context whe > Example: A search bar with a icon to the left -An icon can also optionally be placed on the right edge. This arrow can provide additional hints on how the text input field will behave; for example, a right arrow might suggest that the value will be immediately submitted, or a down arrow might indicate that the text field will open a drop modal underneath it (a list of assignees, for example). +An icon can also optionally be placed on the right edge. This arrow can provide additional hints on how the text input field will behave; for example, a right arrow might suggest that the value will be immediately submitted, or a dropdown arrow might indicate that the text field will open a drop modal underneath it (a list of assignees, for example). The right icon can also be converted to an icon-only link that allows the user to clear the field. @@ -104,7 +104,7 @@ The **Default** state indicates that a text field is ready to accept text input. The **Focus** state has a coloured outline, the same as any focused element in OpenProject. -The **Hover** element has a darker border. +The **Hover** element has a darker border (Basic/Gray 1: #333333). The **Disabled** state shows all elements (including icons and any placeholder or input text) in grey, and makes any interaction impossible. @@ -119,7 +119,7 @@ The **Disabled** state shows all elements (including icons and any placeholder o -The **Error** state puts a red outline around the text input. (_Note_: This state is only used when the text input is part of a _Form element_, which supplements this red outline with an message error message). The error state is usually temporary; fixing the cause of the error (via asyncronous form validation) usually allows it to revert back to the focus +The **Error** state puts a red outline around the text input. (_Note_: This state is only used when the text input is part of a _Form element_, which supplements this red outline with an message error message). The error state is usually temporary; fixing the cause of the error (via asyncronous form validation) usually allows it to revert back to the focus state. > Example: Error state diff --git a/frontend/src/app/spot/components/tooltip/stories/Tooltip.stories.mdx b/frontend/src/app/spot/components/tooltip/stories/Tooltip.stories.mdx index aa5f7ac8ae..2b384d52e9 100644 --- a/frontend/src/app/spot/components/tooltip/stories/Tooltip.stories.mdx +++ b/frontend/src/app/spot/components/tooltip/stories/Tooltip.stories.mdx @@ -83,7 +83,7 @@ However, due to technical limitations, there is a hard min-width of 20-rem and a The minimum width of the tooltip depends on the length of the text, and the maximum width depends on the width of the containing element. -A tooltip can be multi-line if necessary (?) It is never truncated. +A tooltip can be multi-line if necessary. It is never truncated. > Eg. A long multi-line tooltip diff --git a/frontend/src/stories/DropdownMenu.stories.mdx b/frontend/src/stories/DropdownMenu.stories.mdx index 60a69b688b..fdf5641a47 100644 --- a/frontend/src/stories/DropdownMenu.stories.mdx +++ b/frontend/src/stories/DropdownMenu.stories.mdx @@ -10,11 +10,14 @@ The dropdown menu is a contextual menu triggered by clicking on a dropdown butto ## Structure and Options -The dropdown menu consists of a list of items, generally *menu rows*, with an optional title. +The dropdown menu consists of a list of items, generally *menu rows* and an optional title. The title is not interactive. It serves to provide additional context, if necessary. -A menu item is interactive and generally represents an action. +A menu item is interactive and generally represents an action. The menu item can optionally have an icon on the left side. + +> Example of an existing more menu that has icons next to each menu row + ## States diff --git a/frontend/src/stories/SectionHeaders.stories.mdx b/frontend/src/stories/SectionHeaders.stories.mdx index 3f0d9e4521..b48ba455c8 100644 --- a/frontend/src/stories/SectionHeaders.stories.mdx +++ b/frontend/src/stories/SectionHeaders.stories.mdx @@ -20,12 +20,12 @@ However, they can be extended with a few additional features: **Left icon** This icon can be added to provide context. In a files list, for example, the left icon is used to indicate to which storage provider (for example, Nextcloud) that file storage is linked. -In some parts of the application, this icon is also used to indicate open/closed state when the section header functions as an accordian (see *Behaviour*). +In some parts of the application, this icon is also used to indicate open/closed state when the section header functions as an accordion (see *Behaviour*). *Note: Since this element is always all-caps, the baseline of the font requires the icon to be raised by a few pixels. See* Margins and Spacing *for more details.* **Right icon** -The icon can be placed to the right of the text too, if required. This should be used sparingly. +The icon can be placed to the right of the text too, if required. It can optionally also be used as a link (in icon-only mode). This should nevertheless be used sparingly. **Action** This is usually a button on the far edge (by default the right edge) of the component, but can also be a link. This is used to provide additional contextual action related to that whole section (to access the home directory in Nextcloud in a new tab, for example). @@ -37,9 +37,9 @@ The entire structure can be inverted, with the action buton on the left and the ## Behaviour -The section header behaves either as a regular header (static) or as an accordian, where clicking on the entire section header will expand and collapse the content underneath. +The section header behaves either as a regular header (static) or as an accordion, where clicking on the entire section header will expand and collapse the content underneath. -> Example: "Group by" accordian, like a cost report page +> Example: "Group by" accordion, like a cost report page ## Margins and Spacing From 073bf0f0167ff8f320f658cdc117537a1125309f Mon Sep 17 00:00:00 2001 From: Parimal Satyal <88370597+psatyal@users.noreply.github.com> Date: Wed, 23 Nov 2022 18:06:35 +0100 Subject: [PATCH 6/6] Minor changes after our daily today --- .../text-field/stories/TextField.stories.mdx | 2 +- frontend/src/stories/SectionHeaders.stories.mdx | 6 +++--- frontend/src/stories/Toast.stories.mdx | 10 +++++----- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/frontend/src/app/spot/components/text-field/stories/TextField.stories.mdx b/frontend/src/app/spot/components/text-field/stories/TextField.stories.mdx index 470b142b27..6465d937f0 100644 --- a/frontend/src/app/spot/components/text-field/stories/TextField.stories.mdx +++ b/frontend/src/app/spot/components/text-field/stories/TextField.stories.mdx @@ -104,7 +104,7 @@ The **Default** state indicates that a text field is ready to accept text input. The **Focus** state has a coloured outline, the same as any focused element in OpenProject. -The **Hover** element has a darker border (Basic/Gray 1: #333333). +The **Hover** element has a darker border (Basic/Gray 1). The **Disabled** state shows all elements (including icons and any placeholder or input text) in grey, and makes any interaction impossible. diff --git a/frontend/src/stories/SectionHeaders.stories.mdx b/frontend/src/stories/SectionHeaders.stories.mdx index b48ba455c8..9447018cba 100644 --- a/frontend/src/stories/SectionHeaders.stories.mdx +++ b/frontend/src/stories/SectionHeaders.stories.mdx @@ -20,7 +20,7 @@ However, they can be extended with a few additional features: **Left icon** This icon can be added to provide context. In a files list, for example, the left icon is used to indicate to which storage provider (for example, Nextcloud) that file storage is linked. -In some parts of the application, this icon is also used to indicate open/closed state when the section header functions as an accordion (see *Behaviour*). +In some parts of the application, this icon is also used to indicate open/closed state when the section header functions as an expandable/collapsible section (see *Behaviour*). *Note: Since this element is always all-caps, the baseline of the font requires the icon to be raised by a few pixels. See* Margins and Spacing *for more details.* @@ -37,9 +37,9 @@ The entire structure can be inverted, with the action buton on the left and the ## Behaviour -The section header behaves either as a regular header (static) or as an accordion, where clicking on the entire section header will expand and collapse the content underneath. +The section header behaves either as a regular header (static) or as an expandable/collapsible section, where clicking on the entire section header will expand and collapse the content underneath. -> Example: "Group by" accordion, like a cost report page +> Example: "Group by" expandable/collapsible section, like a cost report page ## Margins and Spacing diff --git a/frontend/src/stories/Toast.stories.mdx b/frontend/src/stories/Toast.stories.mdx index 2511ad77c7..0feaf775c4 100644 --- a/frontend/src/stories/Toast.stories.mdx +++ b/frontend/src/stories/Toast.stories.mdx @@ -18,19 +18,19 @@ The toast consists of: There are four types of toasts, each with a specific icon and colour associated with it: -An **Information** toast is blue and provides the user with helpful information about the current view. +An **Information** toast is blue (background: Feedback/Info/Light, stroke: Feedback/Info/Dark) and provides the user with helpful information about the current view. > Eg: a blue notification toast (as it exists today) -A **Success** toast is green and indicates to the user that an action has been successfully carried out. +A **Success** toast is green (background: Feedback/Success/Light, stroke: Feedback/Success/Dark)and indicates to the user that an action has been successfully carried out. > Eg: a green success toast (as it exists today) -A **Warning** toast is orange and indicates that there are potential risks or possibility of error. +A **Warning** toast is orange (background: Feedback/Warning/Light, stroke: Feedback/Warning/Dark) and indicates that there are potential risks or possibility of error. > Eg: an orange toast (is this used somewhere?) -An **Error** toast is red and indicates that something did not not go as expected, and that there is a problem. +An **Error** toast is red (background: Feedback/Error/Light, stroke: Feedback/Error/Dark) and indicates that something did not not go as expected, and that there is a problem. > Eg: a red toast (as it exists today, when moving an WP in GANTT view is not possible) @@ -42,7 +42,7 @@ The text is generally merely informational, although there might sometimes be a > Eg. Blue notification toast with "Load new notifications" link. -Toasts do not disappear automatically; they must be manually closed by the user. +Toasts generally disappear automatically; they must be manually closed by the user. The only exception is the Success toast, which _can_ disappear automatically, if the user has enabled this in their account settings. Ideally, only one toast should be visible at any time. Hoever, there are circumstances where multiple toasts might be generated and visible to the user; in this case, the toasts must "pile" vertically with a 1 rem (?) spacing between them.