Merge pull request #11577 from opf/additional-docs-for-storybook

Adding docs for more components and patterns on Storybook

.gitignore

@@ -135,3 +135,4 @@ structure.sql
 
 # lefthook.yml user override
 lefthook-local.yml
+frontend/package-lock.json

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.
 
 <Canvas>
   <Story
@@ -46,33 +52,83 @@ export const Template = (args) => ({
   },
 })
 
+
+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 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.
+
+> 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.
+
 <Canvas>
   <Story
-    name="Preset value"
+    name="Placeholder"
     args={{
-      value: 'I have a value set',
+      placeholder: 'Placeholders get cut off if they\'re too long',
     }}
   >
     {Template.bind({})}
   </Story>
 </Canvas>
+
+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.
+
+
 <Canvas>
   <Story
-    name="Disabled"
+    name="Preset value"
     args={{
-      disabled: true,
+      value: 'I have a value set',
     }}
   >
     {Template.bind({})}
   </Story>
 </Canvas>
+
+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).
+
+The **Disabled** state shows all elements (including icons and any placeholder or input text) in grey, and makes any interaction impossible.
+
 <Canvas>
   <Story
-    name="Placeholder"
+    name="Disabled"
     args={{
-      placeholder: 'Placeholders get cut off if they\'re too long',
+      disabled: true,
     }}
   >
     {Template.bind({})}
   </Story>
 </Canvas>
+
+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
+
+## 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). 
+
+
+
+

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({})}
   </Story>
 </Canvas>
+
+
+## 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
+

frontend/src/stories/DropdownButton.stories.mdx

@@ -0,0 +1,26 @@
+import { Meta, Story, Canvas } from '@storybook/addon-docs';
+
+<Meta title="Components/Dropdown button" />
+
+# 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+". 
+
+
+

frontend/src/stories/DropdownMenu.stories.mdx

@@ -0,0 +1,35 @@
+import { Meta, Story, Canvas } from '@storybook/addon-docs';
+
+<Meta title="Patterns/Dropdown menu" />
+
+# 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* 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. 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
+
+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
+
+
+

frontend/src/stories/SectionHeaders.stories.mdx

@@ -0,0 +1,50 @@
+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 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.*
+
+**Right icon**
+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).
+
+> 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 expandable/collapsible section, where clicking on the entire section header will expand and collapse the content underneath.
+
+> Example: "Group by" expandable/collapsible section, like a cost report page
+
+## Margins and Spacing
+
+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.
+
+

frontend/src/stories/Toast.stories.mdx

@@ -0,0 +1,51 @@
+import { Meta, Story, Canvas } from '@storybook/addon-docs';
+
+<Meta title="Components/Toast" />
+
+# 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 (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 (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 (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 (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)
+
+##  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 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.
+
+## 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.