From 3533a5a12f2cb3d824e6b9c06edee07610b64ad4 Mon Sep 17 00:00:00 2001 From: Parimal Satyal <88370597+psatyal@users.noreply.github.com> Date: Tue, 1 Apr 2025 18:54:48 +0200 Subject: [PATCH 01/13] First draft of docs for BorderBox --- lookbook/docs/components/borderBox.md.erb | 40 +++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 lookbook/docs/components/borderBox.md.erb diff --git a/lookbook/docs/components/borderBox.md.erb b/lookbook/docs/components/borderBox.md.erb new file mode 100644 index 00000000000..5d08b83e85c --- /dev/null +++ b/lookbook/docs/components/borderBox.md.erb @@ -0,0 +1,40 @@ +The Border Box element is used to display structured items in a list, each with a set of actions. It is used for example: + +- to display a list of meetings +- to display individual meeting agenda items in a meeting +- to display the a list of project attributes +- to display a list of configured OAuth applications + +## Anatomy + +The Border Box element is made up of + +1. The **header** acts as a container for the items below it. It's often to distinguish between sections. It is optional. +2. Individual **items** below can vary in what information they show. + +If a page uses a Border Box with a header, all sections must use headers. + +## Options + +- **Collapsible header**: A collapsible header has an arrow next to the title and allows collapsing and expanding the contents below. When collapsed, the bottom border is slightly thicker to indicate something is hidden. +- **Header description**: When collapsed, the optional header description is hidden. +- **Header counter**: The counter can display the number of items that that particular section contains. +- **Draggable**: Both header and items can have drag handles. Individual items can be dragged up and down and into other sections. The sections themselves can also be moved up and down. +- **More button**: A more button can have contextual actions such as edit, delete and move (move up, move to top, move down, move to the end). + +## Best practices + +**Do** + +- Use sections (with headers) to better organise content if they have logical categories (eg. Open and Planned meetings). + +**Don't** + +- Don't mix sections with and without headers. If one section has a header, they must all have headers. +- Don't make sections collapsible if they do not need to be. + + +## Technical notes + + +### Code structure From 01c9afcf106822412e82fbd914e6dd76f90c64f9 Mon Sep 17 00:00:00 2001 From: Parimal Satyal <88370597+psatyal@users.noreply.github.com> Date: Tue, 1 Apr 2025 19:01:37 +0200 Subject: [PATCH 02/13] Filename update --- lookbook/docs/components/{borderBox.md.erb => border-box.md.erb} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename lookbook/docs/components/{borderBox.md.erb => border-box.md.erb} (100%) diff --git a/lookbook/docs/components/borderBox.md.erb b/lookbook/docs/components/border-box.md.erb similarity index 100% rename from lookbook/docs/components/borderBox.md.erb rename to lookbook/docs/components/border-box.md.erb From 8a522f577ac50426f3c5056c3550d79122e7a8c1 Mon Sep 17 00:00:00 2001 From: Henriette Darge Date: Wed, 2 Apr 2025 10:51:06 +0200 Subject: [PATCH 03/13] Split tables documentation into TableComponent and BorderBoxComponent --- .../docs/components/borde-box-table.md.erb | 81 +++++++++ lookbook/docs/components/tables.md.erb | 120 ++++---------- .../deprecated/table_preview/default.html.erb | 156 +++++++----------- 3 files changed, 169 insertions(+), 188 deletions(-) create mode 100644 lookbook/docs/components/borde-box-table.md.erb diff --git a/lookbook/docs/components/borde-box-table.md.erb b/lookbook/docs/components/borde-box-table.md.erb new file mode 100644 index 00000000000..c633001424e --- /dev/null +++ b/lookbook/docs/components/borde-box-table.md.erb @@ -0,0 +1,81 @@ +## Overview + +<%= embed OpPrimer::BorderBoxTableComponentPreview, :default %> + +## Anatomy + +**Note:** The BorderBoxTable is based on the `Primer::Beta::BorderBox` with a CSS grid applied inside to align the individual rows and make it look like a table. Please note, that it is technically not a table and has therefore none of the benefits a normal HTML table would have (e.g automatic column width adjustments or accessibility support). If you want or need that, please use the [TableComponent docs](./tables)) + +## Best practices + +**Do** + +- Use a BorderBox table if you have a *few* entries of unsorted data, that does not require pagination +- Use up to two actions using the `:secondary` scheme of `Primer::Beta::Button` and `Primer::Beta::IconButton`. +- OR: Use an action menu with `:invisible` scheme + +**Don't** + +- Use the BorderBox table for a lot of items that require sorting or pagination + +## Technical notes + +Since the `BorderBoxTable` is a sub-class of our normal `TableComponent` it follows the same architecture. For the basic usage please visit the [TableComponent docs](./tables). The following docs are only about the additional specifics of the `BorderBoxTable`. + +### Mobile behavior + +On mobile, the BorderBoxTable does not scroll, but collapse into two columns (content columns and actions). You can control which columns are shown using the `mobile_columns` method. + +As the columns are collapsed, some information might need an additional label, which you can prepend with `mobile_labels`. + +```ruby +# On desktop, show these columns +columns :title, :users, :created_at + +# On mobile, only two columns are visible +mobile_columns :title, :users + +# For users, show the label using the header caption +mobile_labels :users +``` + +### Mobile headers + +On mobile, the usual table headers are replaced with a single `mobile_title` property that you have to set on the table. + +### Text wrapping behaviour + +By default, text longer than the column width will truncate with ellipsis. Only the main column has text that wraps around to display the full string. + +### Main column + +Use the `main_column` helper to make a column 2 times as wide as the others and also display the full text: + +```ruby +# On desktop, show these columns +columns :title, :users, :created_at + +# Make title column wider than the others (factor 2 using grid span) +main_column :title +``` +Note: Ideally, one one main column will be present for each table. + +### Footer + +Set `has_footer?` to true to add a footer to the table, defining the component/content to be rendered with the `footer` method. + +```ruby +def has_footer? + true +end + +def footer + render CustomFooterComponent.new(...) +end +``` + +### Examples + +<%= embed OpPrimer::BorderBoxTableComponentPreview, :default, panels: %i[source] %> + +For detailed examples have a look at the other [preview examples](/lookbook/inspect/OpenProject/Primer/border_box_table/default) of the component. diff --git a/lookbook/docs/components/tables.md.erb b/lookbook/docs/components/tables.md.erb index 447a3e0ba4d..bf466391a56 100644 --- a/lookbook/docs/components/tables.md.erb +++ b/lookbook/docs/components/tables.md.erb @@ -1,104 +1,46 @@ ## Overview -### Border Box Table +We currently have two components for implementing a table view: -<%= embed OpPrimer::BorderBoxTableComponentPreview, :default %> +* a (sortable) `TableComponent` +* a (unsortable, primer based) `BorderBoxTableComponent` -### Sortable table +**Sortable table** <%= embed OpenProject::Deprecated::TablePreview, :default %> -## Usage +**Border Box Table** -To use either table implementation, you need to subclass into your own namespace: +<%= embed OpPrimer::BorderBoxTableComponentPreview, :default %> + +For the specifics of that component please have a look at the [BorderBoxTableComponent docs](./border_box_table). + +## Anatomy + +**Sortable table** + +* The Sortable Table results in a standard HTML table with some classes applied for styling. +* If `sortable` is set to true, all sortable column headers are clickable to change the sort order. When a sort is applied, that is indicated via an arrow. + +**Border Box Table** + +* The BorderBoxTable is based on the `Primer::Beta::BorderBox` with a CSS grid applied inside to align the individual rows and make it look like a table. + +## Technical notes + +The `BorderBoxTableComponent` is a subclass of the `TableComponent`, so the following notes apply to both components. There are however some additional things to consider, for that please visit the [BorderBoxTableComponent docs](./border_box_table). + +To use either table implementation, you need to subclass the following classes onto your own namespace: - **Regular table:** `TableComponent` and `RowComponent` - **BorderBox table:** `OpPrimer::BorderBoxTableComponent` and `OpPrimer::BorderBoxRowComponent` -**Columns:** Define the columns of the table as class method `columns :a, :b, :c` +**Columns** -**Headers:** Define the headers of the component like so +Define the columns of the table as class method: ```ruby -def headers - [ - [:a, { caption: 'Column A' }], - [:b, { caption: 'Column B' }], - [:c, { caption: 'Column C' }] - ] -end -``` - -**Actions:** Define the actions in the row component as `button_links`. See the example code - -<%= embed OpPrimer::BorderBoxTableComponentPreview, :default, panels: %i[source] %> - -### Border Box Table specifics - -#### Mobile behavior - -On mobile, the BorderBoxTable does not scroll, but collapse into two columns (content columns and actions). You can control which columns are shown using the `mobile_columns` method. - -As the columns are collapsed, some information might need an additional label, which you can prepend with `mobile_labels`. - -```ruby -# On desktop, show these columns -columns :title, :users, :created_at - -# On mobile, only two columns are visible -mobile_columns :title, :users - -# For users, show the label using the header caption -mobile_labels :users -``` - -#### Mobile headers - -On mobile, the usual table headers are replaced with a single `mobile_title` property that you have to set on the table. - -#### Text wrapping behaviour - -By default, text longer than the column width will truncate with ellipsis. Only the main column has text that wraps around to display the full string. - -#### Main column - -Use the `main_column` helper to make a column 2 times as wide as the others and also display the full text: - -```ruby -# On desktop, show these columns -columns :title, :users, :created_at - -# Make title column wider than the others (factor 2 using grid span) -main_column :title -``` -Note: Ideally, one one main column will be present for each table. - -#### Footer - -Set `has_footer?` to true to add a footer to the table, defining the component/content to be rendered with the `footer` method. - -```ruby -def has_footer? - true -end - -def footer - render CustomFooterComponent.new(...) -end -``` - -## Best practices - -**Do** - -- Use a BorderBox table if you have a *few* entries of unsorted data, that does not require pagination -- Use up to two actions using the `:secondary` scheme of `Primer::Beta::Button` and `Primer::Beta::IconButton`. -- OR: Use an action menu with `:invisible` scheme - -**Don't** - -- Use the BorderBox table for a lot of items that require sorting or pagination - -## Examples - -For detailed examples have a look at the other [preview examples](/lookbook/inspect/OpenProject/Primer/border_box_table/default) of the component. +module ModuleA + class TableComponent <::TableComponent + columns :name +<%= embed OpenProject::Deprecated::TablePreview, :default, panels: %i[source] %> diff --git a/lookbook/previews/open_project/deprecated/table_preview/default.html.erb b/lookbook/previews/open_project/deprecated/table_preview/default.html.erb index 66bd797a8d8..5cd87af4c8c 100644 --- a/lookbook/previews/open_project/deprecated/table_preview/default.html.erb +++ b/lookbook/previews/open_project/deprecated/table_preview/default.html.erb @@ -1,100 +1,58 @@ -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-
-
- - First - -
-
- 		-
-
- - Second - -
-
- 		-
-
- - Third - -
-
- 		-
-
- - Fourth - -
-
- 		-
-
- - Fifth - -
-
-
Lorem ipsum dolor sit amet, consectetur adipiscing elitNullam a sem et metus congue placerat.Mauris ut augue viverra, consequat eros eu, maximus quam.Maecenas elementum orci a varius suscipit.Nunc molestie neque sit amet eros semper dapibus.
Nullam a sem et metus congue placerat.Lorem ipsum dolor sit amet, consectetur adipiscing elitMauris ut augue viverra, consequat eros eu, maximus quam.Maecenas elementum orci a varius suscipit.Nunc molestie neque sit amet eros semper dapibus.
Nullam a sem et metus congue placerat.Mauris ut augue viverra, consequat eros eu, maximus quam.Lorem ipsum dolor sit amet, consectetur adipiscing elitMaecenas elementum orci a varius suscipit.Nunc molestie neque sit amet eros semper dapibus.
Nullam a sem et metus congue placerat.Mauris ut augue viverra, consequat eros eu, maximus quam.Maecenas elementum orci a varius suscipit.Lorem ipsum dolor sit amet, consectetur adipiscing elitNunc molestie neque sit amet eros semper dapibus.
Nullam a sem et metus congue placerat.Mauris ut augue viverra, consequat eros eu, maximus quam.Maecenas elementum orci a varius suscipit.Lorem ipsum dolor sit amet, consectetur adipiscing elitNunc molestie neque sit amet eros semper dapibus.
+<%= + table = Class.new(TableComponent) do + columns :foo, :bar -
-
+ def self.name + "MyTable" + end + + ## This method is just a hack used for the preview + ## Create your components under your namespace like so instead + ## MyNamespace::TableComponent + ## MyNamespace::RowComponent + ## and the other class will be autoloaded + def row_class + @row_class ||= Class.new(RowComponent) do + def self.name + "Row" + end + + def button_links + [ + delete_button + ] + end + + def delete_button + render(Primer::Beta::IconButton.new(icon: :trash, scheme: :danger, tag: :a, href: "#", "aria-label": "Delete")) + end + + def foo + render(Primer::Beta::Text.new(tag: :p)) { "Hello there" } + end + + def bar + "bar" + end + end + end + + def has_actions? + true + end + + def headers + [ + [:foo, { caption: "Foo column" }], + [:bar, { caption: "Bar column" }] + ] + end + + def sortable? + # True per default but for this preview disabled + false + end + end + + render(table.new(rows: [1, 2])) +%> From 0ffc60cb2409e40b0e88c8c2e5fd1d930a392ba2 Mon Sep 17 00:00:00 2001 From: Henriette Darge Date: Wed, 2 Apr 2025 12:18:38 +0200 Subject: [PATCH 04/13] Undo rubocop changes which messed up the preview --- ...x-table.md.erb => border-box-table.md.erb} | 9 +++-- lookbook/docs/components/border-box.md.erb | 18 +++++---- lookbook/docs/components/tables.md.erb | 37 ++++++++++++++++++- .../deprecated/table_preview/default.html.erb | 4 +- 4 files changed, 54 insertions(+), 14 deletions(-) rename lookbook/docs/components/{borde-box-table.md.erb => border-box-table.md.erb} (88%) diff --git a/lookbook/docs/components/borde-box-table.md.erb b/lookbook/docs/components/border-box-table.md.erb similarity index 88% rename from lookbook/docs/components/borde-box-table.md.erb rename to lookbook/docs/components/border-box-table.md.erb index c633001424e..63d40fc521c 100644 --- a/lookbook/docs/components/borde-box-table.md.erb +++ b/lookbook/docs/components/border-box-table.md.erb @@ -4,19 +4,19 @@ ## Anatomy -**Note:** The BorderBoxTable is based on the `Primer::Beta::BorderBox` with a CSS grid applied inside to align the individual rows and make it look like a table. Please note, that it is technically not a table and has therefore none of the benefits a normal HTML table would have (e.g automatic column width adjustments or accessibility support). If you want or need that, please use the [TableComponent docs](./tables)) +**Note:** The BorderBoxTable is based on the `Primer::Beta::BorderBox` with a CSS grid applied inside to align the individual rows and make it look like a table. Please note, that it is technically not a table and has therefore none of the benefits a normal HTML table would have (e.g automatic column width adjustments or accessibility short cuts). If you want or need that, please use the [TableComponent docs](./tables)) ## Best practices **Do** -- Use a BorderBox table if you have a *few* entries of unsorted data, that does not require pagination +- Use a BorderBoxTable if you have a *few* entries of unsorted data, that does not require pagination - Use up to two actions using the `:secondary` scheme of `Primer::Beta::Button` and `Primer::Beta::IconButton`. - OR: Use an action menu with `:invisible` scheme **Don't** -- Use the BorderBox table for a lot of items that require sorting or pagination +- Use the BorderBoxTable for a lot of items that require sorting or pagination ## Technical notes @@ -79,3 +79,6 @@ end <%= embed OpPrimer::BorderBoxTableComponentPreview, :default, panels: %i[source] %> For detailed examples have a look at the other [preview examples](/lookbook/inspect/OpenProject/Primer/border_box_table/default) of the component. + +Note for Henriette: +Example with CollapsibleHeader??? diff --git a/lookbook/docs/components/border-box.md.erb b/lookbook/docs/components/border-box.md.erb index 5d08b83e85c..eff5dc17faa 100644 --- a/lookbook/docs/components/border-box.md.erb +++ b/lookbook/docs/components/border-box.md.erb @@ -1,7 +1,7 @@ The Border Box element is used to display structured items in a list, each with a set of actions. It is used for example: -- to display a list of meetings -- to display individual meeting agenda items in a meeting +- to display a list of meetings +- to display individual meeting agenda items in a meeting - to display the a list of project attributes - to display a list of configured OAuth applications @@ -14,12 +14,15 @@ The Border Box element is made up of If a page uses a Border Box with a header, all sections must use headers. -## Options +## Header + +Note for Parimal: +You can chose between a collapsibleHeader and a free-chosen Header. The collapsible Header consists of Title, counter(optional) and description(optional). - **Collapsible header**: A collapsible header has an arrow next to the title and allows collapsing and expanding the contents below. When collapsed, the bottom border is slightly thicker to indicate something is hidden. -- **Header description**: When collapsed, the optional header description is hidden. -- **Header counter**: The counter can display the number of items that that particular section contains. -- **Draggable**: Both header and items can have drag handles. Individual items can be dragged up and down and into other sections. The sections themselves can also be moved up and down. + - **Header description**: When collapsed, the optional header description is hidden. + - **Header counter**: The counter can display the number of items that that particular section contains. + - **More button**: A more button can have contextual actions such as edit, delete and move (move up, move to top, move down, move to the end). ## Best practices @@ -27,11 +30,12 @@ If a page uses a Border Box with a header, all sections must use headers. **Do** - Use sections (with headers) to better organise content if they have logical categories (eg. Open and Planned meetings). +- - **Draggable**: Both header and items can have drag handles. Individual items can be dragged up and down and into other sections. The sections themselves can also be moved up and down. **Don't** - Don't mix sections with and without headers. If one section has a header, they must all have headers. -- Don't make sections collapsible if they do not need to be. +- Don't make sections collapsible if they do not need to be. ## Technical notes diff --git a/lookbook/docs/components/tables.md.erb b/lookbook/docs/components/tables.md.erb index bf466391a56..559ffea6bb6 100644 --- a/lookbook/docs/components/tables.md.erb +++ b/lookbook/docs/components/tables.md.erb @@ -41,6 +41,39 @@ Define the columns of the table as class method: ```ruby module ModuleA - class TableComponent <::TableComponent - columns :name + class TableComponent < ::TableComponent + columns :name, :description, :sort + # ... + end +end +``` + +**Headers** + +Define the headers of the component as a method retu + +```ruby +module ModuleA + class TableComponent < ::TableComponent + # ... + + def headers + [ + [:a, { caption: 'Column A' }], + [:b, { caption: 'Column B' }], + [:c, { caption: 'Column C' }] + ] + end + + # ... + end +end +``` + +**Actions** + +Define the actions in the row component as `button_links`. See the example code + +### Full example + <%= embed OpenProject::Deprecated::TablePreview, :default, panels: %i[source] %> diff --git a/lookbook/previews/open_project/deprecated/table_preview/default.html.erb b/lookbook/previews/open_project/deprecated/table_preview/default.html.erb index 5cd87af4c8c..882ef8f21ca 100644 --- a/lookbook/previews/open_project/deprecated/table_preview/default.html.erb +++ b/lookbook/previews/open_project/deprecated/table_preview/default.html.erb @@ -28,11 +28,11 @@ end def foo - render(Primer::Beta::Text.new(tag: :p)) { "Hello there" } + render(Primer::Beta::Text.new(tag: :p)) { "Lorem ipsum dolor sit amet, consetetur sadipscing elitr" } end def bar - "bar" + "At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum." end end end From 4c6e0ea599289a8cfbe423ed199b46732612d89d Mon Sep 17 00:00:00 2001 From: Henriette Darge Date: Wed, 2 Apr 2025 15:01:16 +0200 Subject: [PATCH 05/13] Clean-up comments --- lookbook/docs/components/border-box-table.md.erb | 3 --- .../op_primer/border_box_table_component_preview.rb | 6 +++--- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/lookbook/docs/components/border-box-table.md.erb b/lookbook/docs/components/border-box-table.md.erb index 63d40fc521c..72a53164520 100644 --- a/lookbook/docs/components/border-box-table.md.erb +++ b/lookbook/docs/components/border-box-table.md.erb @@ -79,6 +79,3 @@ end <%= embed OpPrimer::BorderBoxTableComponentPreview, :default, panels: %i[source] %> For detailed examples have a look at the other [preview examples](/lookbook/inspect/OpenProject/Primer/border_box_table/default) of the component. - -Note for Henriette: -Example with CollapsibleHeader??? diff --git a/lookbook/previews/op_primer/border_box_table_component_preview.rb b/lookbook/previews/op_primer/border_box_table_component_preview.rb index d37449ccfe1..48402b2a59e 100644 --- a/lookbook/previews/op_primer/border_box_table_component_preview.rb +++ b/lookbook/previews/op_primer/border_box_table_component_preview.rb @@ -4,17 +4,17 @@ module OpPrimer # @logical_path OpenProject/Primer # @display min_height 300px class BorderBoxTableComponentPreview < Lookbook::Preview - # See the [component documentation](/lookbook/pages/components/tables) for more details. + # See the [component documentation](/lookbook/pages/components/border_box_table) for more details. def default render_with_template end - # See the [component documentation](/lookbook/pages/components/tables) for more details. + # See the [component documentation](/lookbook/pages/components/border_box_table) for more details. def custom_column_widths render_with_template end - # See the [component documentation](/lookbook/pages/components/tables) for more details. + # See the [component documentation](/lookbook/pages/components/border_box_table) for more details. def with_action_menu render_with_template end From 1f68d176c3d6efeb611d96b7fdd2ccc60ef25e91 Mon Sep 17 00:00:00 2001 From: Parimal Satyal <88370597+psatyal@users.noreply.github.com> Date: Thu, 3 Apr 2025 13:53:31 +0200 Subject: [PATCH 06/13] Update to the docs --- .../docs/components/border-box-table.md.erb | 8 +++-- lookbook/docs/components/border-box.md.erb | 31 +++++++++++++------ 2 files changed, 26 insertions(+), 13 deletions(-) diff --git a/lookbook/docs/components/border-box-table.md.erb b/lookbook/docs/components/border-box-table.md.erb index 72a53164520..16ed52ee1af 100644 --- a/lookbook/docs/components/border-box-table.md.erb +++ b/lookbook/docs/components/border-box-table.md.erb @@ -4,19 +4,21 @@ ## Anatomy -**Note:** The BorderBoxTable is based on the `Primer::Beta::BorderBox` with a CSS grid applied inside to align the individual rows and make it look like a table. Please note, that it is technically not a table and has therefore none of the benefits a normal HTML table would have (e.g automatic column width adjustments or accessibility short cuts). If you want or need that, please use the [TableComponent docs](./tables)) +**Note:** The BorderBoxTable is based on the `Primer::Beta::BorderBox` with a CSS grid applied inside to align the individual rows and make it look like a table. Please note, that it is technically not a table and has therefore none of the benefits a normal HTML table would have (e.g automatic column width adjustments or accessibility short cuts). + +If you want or need that, please use the [TableComponent docs](./tables)) ## Best practices **Do** -- Use a BorderBoxTable if you have a *few* entries of unsorted data, that does not require pagination +- Use a BorderBoxTable if you have a *few* entries of unsorted data that does not require pagination - Use up to two actions using the `:secondary` scheme of `Primer::Beta::Button` and `Primer::Beta::IconButton`. - OR: Use an action menu with `:invisible` scheme **Don't** -- Use the BorderBoxTable for a lot of items that require sorting or pagination +- Don't use the BorderBoxTable when the table consists of a large number of items that require sorting or pagination ## Technical notes diff --git a/lookbook/docs/components/border-box.md.erb b/lookbook/docs/components/border-box.md.erb index eff5dc17faa..ebac0d79411 100644 --- a/lookbook/docs/components/border-box.md.erb +++ b/lookbook/docs/components/border-box.md.erb @@ -1,15 +1,11 @@ The Border Box element is used to display structured items in a list, each with a set of actions. It is used for example: -- to display a list of meetings -- to display individual meeting agenda items in a meeting -- to display the a list of project attributes -- to display a list of configured OAuth applications ## Anatomy The Border Box element is made up of -1. The **header** acts as a container for the items below it. It's often to distinguish between sections. It is optional. +1. The **header**, which acts as a container for the items below and helps distinguish between sections. It is optional. 2. Individual **items** below can vary in what information they show. If a page uses a Border Box with a header, all sections must use headers. @@ -19,18 +15,33 @@ If a page uses a Border Box with a header, all sections must use headers. Note for Parimal: You can chose between a collapsibleHeader and a free-chosen Header. The collapsible Header consists of Title, counter(optional) and description(optional). -- **Collapsible header**: A collapsible header has an arrow next to the title and allows collapsing and expanding the contents below. When collapsed, the bottom border is slightly thicker to indicate something is hidden. - - **Header description**: When collapsed, the optional header description is hidden. - - **Header counter**: The counter can display the number of items that that particular section contains. +The header can either be static or collapsible. -- **More button**: A more button can have contextual actions such as edit, delete and move (move up, move to top, move down, move to the end). +The collapsibleHeader brings additional functionality: + +- an **arrow indicator** next to the title indicates if the section is collapsed or expanded. +- a **header description** (optional) to give additional context to the content of that section. Hidden when collapsed. +- a **counter** (optional) displays the number of items that that particular section contains. + +When collapsed, the bottom border is slightly thicker to indicate something is hidden. + +Both the collapsible header and static heads can accept additional actions. For example, a **more button** can offer additional contextual actions such as edit, delete and move (move up, move to top, move down, move to the end). + +## Uses + +- to display a list of meetings +- to display individual meeting agenda items in a meeting +- to display the a list of project attributes +- to display a list of configured OAuth applications + +If the content needs to be more structured (with columns and column headers), please use the [Border Box Table](border-box-table) component instead. ## Best practices **Do** - Use sections (with headers) to better organise content if they have logical categories (eg. Open and Planned meetings). -- - **Draggable**: Both header and items can have drag handles. Individual items can be dragged up and down and into other sections. The sections themselves can also be moved up and down. +- Do make the header and items draggable if the user should be able to drag individual items up and down and into other sections. The sections themselves can also be dragged up and down to change order. **Don't** From 7a0a04da31f7c3736c10acd3b945e593a80347f2 Mon Sep 17 00:00:00 2001 From: Parimal Satyal <88370597+psatyal@users.noreply.github.com> Date: Thu, 3 Apr 2025 13:56:45 +0200 Subject: [PATCH 07/13] Update to uses --- lookbook/docs/components/border-box-table.md.erb | 10 ++++++++++ lookbook/docs/components/border-box.md.erb | 3 +-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/lookbook/docs/components/border-box-table.md.erb b/lookbook/docs/components/border-box-table.md.erb index 16ed52ee1af..349eb098882 100644 --- a/lookbook/docs/components/border-box-table.md.erb +++ b/lookbook/docs/components/border-box-table.md.erb @@ -20,6 +20,16 @@ If you want or need that, please use the [TableComponent docs](./tables)) - Don't use the BorderBoxTable when the table consists of a large number of items that require sorting or pagination +## Uses + +- to display a list of meetings +- to display a list of configured SAML providers +- to display a list of configured OpenID providers +- to display a list of configured SCIM clients + +If the content does not need a table structure with column headers and grids, please use the simpler [Border Box](border-box-table) component instead. + + ## Technical notes Since the `BorderBoxTable` is a sub-class of our normal `TableComponent` it follows the same architecture. For the basic usage please visit the [TableComponent docs](./tables). The following docs are only about the additional specifics of the `BorderBoxTable`. diff --git a/lookbook/docs/components/border-box.md.erb b/lookbook/docs/components/border-box.md.erb index ebac0d79411..4f72d012134 100644 --- a/lookbook/docs/components/border-box.md.erb +++ b/lookbook/docs/components/border-box.md.erb @@ -29,9 +29,8 @@ Both the collapsible header and static heads can accept additional actions. For ## Uses -- to display a list of meetings - to display individual meeting agenda items in a meeting -- to display the a list of project attributes +- to display the a list of project attributes in Project settings - to display a list of configured OAuth applications If the content needs to be more structured (with columns and column headers), please use the [Border Box Table](border-box-table) component instead. From 3eda83fcd7dd8222840d8acf133c3857610f2703 Mon Sep 17 00:00:00 2001 From: Henriette Darge Date: Thu, 3 Apr 2025 15:27:48 +0200 Subject: [PATCH 08/13] Add a code example for the collapsibleHeader and do some cleanup --- lookbook/docs/components/border-box.md.erb | 18 +++---- .../{ => tables}/border-box-table.md.erb | 7 ++- .../components/{ => tables}/tables.md.erb | 0 .../op_primer/border_box_component_preview.rb | 22 +++++++++ .../collapsible.html.erb | 49 +++++++++++++++++++ 5 files changed, 83 insertions(+), 13 deletions(-) rename lookbook/docs/components/{ => tables}/border-box-table.md.erb (96%) rename lookbook/docs/components/{ => tables}/tables.md.erb (100%) create mode 100644 lookbook/previews/op_primer/border_box_component_preview.rb create mode 100644 lookbook/previews/op_primer/border_box_component_preview/collapsible.html.erb diff --git a/lookbook/docs/components/border-box.md.erb b/lookbook/docs/components/border-box.md.erb index 4f72d012134..da05770e02e 100644 --- a/lookbook/docs/components/border-box.md.erb +++ b/lookbook/docs/components/border-box.md.erb @@ -1,5 +1,6 @@ -The Border Box element is used to display structured items in a list, each with a set of actions. It is used for example: +The Border Box element is used to display structured items in a list, each with a set of actions. +<%= embed OpPrimer::BorderBoxComponentPreview, :default %> ## Anatomy @@ -12,21 +13,20 @@ If a page uses a Border Box with a header, all sections must use headers. ## Header -Note for Parimal: -You can chose between a collapsibleHeader and a free-chosen Header. The collapsible Header consists of Title, counter(optional) and description(optional). - -The header can either be static or collapsible. +The header can either be static or collapsible. The collapsibleHeader brings additional functionality: -- an **arrow indicator** next to the title indicates if the section is collapsed or expanded. +- an **arrow indicator** next to the title indicates if the section is collapsed or expanded. - a **header description** (optional) to give additional context to the content of that section. Hidden when collapsed. - a **counter** (optional) displays the number of items that that particular section contains. - + When collapsed, the bottom border is slightly thicker to indicate something is hidden. Both the collapsible header and static heads can accept additional actions. For example, a **more button** can offer additional contextual actions such as edit, delete and move (move up, move to top, move down, move to the end). +<%= embed OpPrimer::BorderBoxComponentPreview, :collapsible %> + ## Uses - to display individual meeting agenda items in a meeting @@ -47,8 +47,8 @@ If the content needs to be more structured (with columns and column headers), pl - Don't mix sections with and without headers. If one section has a header, they must all have headers. - Don't make sections collapsible if they do not need to be. - ## Technical notes +<%= embed OpPrimer::BorderBoxComponentPreview, :collapsible, panels: %i[source] %> -### Code structure +For detailed examples have a look at the other [border box preview examples](/lookbook/inspect/primer/beta/border_box/playground) or the [collapsible header preview examples](/lookbook/inspect/primer/open_project/border_box/collapsible_header/playground). diff --git a/lookbook/docs/components/border-box-table.md.erb b/lookbook/docs/components/tables/border-box-table.md.erb similarity index 96% rename from lookbook/docs/components/border-box-table.md.erb rename to lookbook/docs/components/tables/border-box-table.md.erb index 349eb098882..52202789d4f 100644 --- a/lookbook/docs/components/border-box-table.md.erb +++ b/lookbook/docs/components/tables/border-box-table.md.erb @@ -4,9 +4,9 @@ ## Anatomy -**Note:** The BorderBoxTable is based on the `Primer::Beta::BorderBox` with a CSS grid applied inside to align the individual rows and make it look like a table. Please note, that it is technically not a table and has therefore none of the benefits a normal HTML table would have (e.g automatic column width adjustments or accessibility short cuts). +**Note:** The BorderBoxTable is based on the `Primer::Beta::BorderBox` with a CSS grid applied inside to align the individual rows and make it look like a table. Please note, that it is technically not a table and has therefore none of the benefits a normal HTML table would have (e.g automatic column width adjustments or accessibility short cuts). -If you want or need that, please use the [TableComponent docs](./tables)) +If you want or need that, please use the [TableComponent docs](./tables) ## Best practices @@ -27,8 +27,7 @@ If you want or need that, please use the [TableComponent docs](./tables)) - to display a list of configured OpenID providers - to display a list of configured SCIM clients -If the content does not need a table structure with column headers and grids, please use the simpler [Border Box](border-box-table) component instead. - +If the content does not need a table structure with column headers and grids, please use the simpler [Border Box](../border_box) component instead. ## Technical notes diff --git a/lookbook/docs/components/tables.md.erb b/lookbook/docs/components/tables/tables.md.erb similarity index 100% rename from lookbook/docs/components/tables.md.erb rename to lookbook/docs/components/tables/tables.md.erb diff --git a/lookbook/previews/op_primer/border_box_component_preview.rb b/lookbook/previews/op_primer/border_box_component_preview.rb new file mode 100644 index 00000000000..0e5e5c55e90 --- /dev/null +++ b/lookbook/previews/op_primer/border_box_component_preview.rb @@ -0,0 +1,22 @@ +# frozen_string_literal: true + +module OpPrimer + # @hidden + # @display min_height 400px + class BorderBoxComponentPreview < Lookbook::Preview + def default + render(Primer::Beta::BorderBox.new) do |component| + component.with_header { "Header" } + component.with_body { "Body" } + component.with_row { "Row one" } + component.with_row { "Row two" } + component.with_row { "Row three" } + component.with_footer { "Footer" } + end + end + + def collapsible + render_with_template + end + end +end diff --git a/lookbook/previews/op_primer/border_box_component_preview/collapsible.html.erb b/lookbook/previews/op_primer/border_box_component_preview/collapsible.html.erb new file mode 100644 index 00000000000..f9e33ee6d13 --- /dev/null +++ b/lookbook/previews/op_primer/border_box_component_preview/collapsible.html.erb @@ -0,0 +1,49 @@ +<%= render(Primer::Beta::BorderBox.new) do |component| %> + <% component.with_header do %> + <%= render( + Primer::OpenProject::BorderBox::CollapsibleHeader.new( + box: component, + title: "Collapsible header", + count: 3 + ) + ) %> + <% end %> + <% component.with_body { "Body" } %> + <% component.with_row do %> + <%= render(Primer::OpenProject::FlexLayout.new(justify_content: :space_between, align_items: :center)) do |flex| %> + <%= flex.with_column { "Row 1" } %> + <%= flex.with_column do %> + <%= render(Primer::Alpha::ActionMenu.new) do |menu| + menu.with_show_button(icon: "kebab-horizontal", "aria-label": "More", scheme: :invisible) + menu.with_item( + tag: :a, + label: "Edit", + href: "#" + ) do |item| + item.with_leading_visual_icon(icon: :pencil) + "foo" + end + end %> + <% end %> + <% end %> + <% end %> + <% component.with_row do %> + <%= render(Primer::OpenProject::FlexLayout.new(justify_content: :space_between, align_items: :center)) do |flex| %> + <%= flex.with_column { "Row 2" } %> + <%= flex.with_column do %> + <%= render(Primer::Alpha::ActionMenu.new) do |menu| + menu.with_show_button(icon: "kebab-horizontal", "aria-label": "More", scheme: :invisible) + menu.with_item( + tag: :a, + label: "Edit", + href: "#" + ) do |item| + item.with_leading_visual_icon(icon: :pencil) + "foo" + end + end %> + <% end %> + <% end %> + <% end %> + <% component.with_footer { "Footer" } %> +<% end %> From 83d37b135a35f4107892460627e280f75373c533 Mon Sep 17 00:00:00 2001 From: Parimal Satyal <88370597+psatyal@users.noreply.github.com> Date: Thu, 3 Apr 2025 15:47:45 +0200 Subject: [PATCH 09/13] Minor update --- lookbook/docs/components/tables/border-box-table.md.erb | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lookbook/docs/components/tables/border-box-table.md.erb b/lookbook/docs/components/tables/border-box-table.md.erb index 52202789d4f..449221682ba 100644 --- a/lookbook/docs/components/tables/border-box-table.md.erb +++ b/lookbook/docs/components/tables/border-box-table.md.erb @@ -22,6 +22,8 @@ If you want or need that, please use the [TableComponent docs](./tables) ## Uses +Some examples of where we already use the Border Box table: + - to display a list of meetings - to display a list of configured SAML providers - to display a list of configured OpenID providers From d44c0f8642ed42635f102ea7d4ec7368db2b0a23 Mon Sep 17 00:00:00 2001 From: Parimal Satyal <88370597+psatyal@users.noreply.github.com> Date: Thu, 3 Apr 2025 15:48:54 +0200 Subject: [PATCH 10/13] Minor --- lookbook/docs/components/border-box.md.erb | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lookbook/docs/components/border-box.md.erb b/lookbook/docs/components/border-box.md.erb index da05770e02e..c3176219af1 100644 --- a/lookbook/docs/components/border-box.md.erb +++ b/lookbook/docs/components/border-box.md.erb @@ -29,6 +29,8 @@ Both the collapsible header and static heads can accept additional actions. For ## Uses +Some places in which we already use the Border Box: + - to display individual meeting agenda items in a meeting - to display the a list of project attributes in Project settings - to display a list of configured OAuth applications From 2974b02a72ef8be832915a4481e49142b4d33b31 Mon Sep 17 00:00:00 2001 From: Mir Bhatia Date: Thu, 3 Apr 2025 16:36:03 +0200 Subject: [PATCH 11/13] Add with_footer example for BorderBoxTable --- .../border_box_table_component_preview.rb | 5 ++ .../with_footer.html.erb | 66 +++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 lookbook/previews/op_primer/border_box_table_component_preview/with_footer.html.erb diff --git a/lookbook/previews/op_primer/border_box_table_component_preview.rb b/lookbook/previews/op_primer/border_box_table_component_preview.rb index 48402b2a59e..c9c4365cc78 100644 --- a/lookbook/previews/op_primer/border_box_table_component_preview.rb +++ b/lookbook/previews/op_primer/border_box_table_component_preview.rb @@ -18,5 +18,10 @@ module OpPrimer def with_action_menu render_with_template end + + # See the [component documentation](/lookbook/pages/components/border_box_table) for more details. + def with_footer + render_with_template + end end end diff --git a/lookbook/previews/op_primer/border_box_table_component_preview/with_footer.html.erb b/lookbook/previews/op_primer/border_box_table_component_preview/with_footer.html.erb new file mode 100644 index 00000000000..50077e2dbeb --- /dev/null +++ b/lookbook/previews/op_primer/border_box_table_component_preview/with_footer.html.erb @@ -0,0 +1,66 @@ +<%= + table = Class.new(OpPrimer::BorderBoxTableComponent) do + columns :foo, :bar + + mobile_labels :bar + + def self.name + "MyTable" + end + + def mobile_title + "Mobile foo" + end + + def row_class + @row_class ||= Class.new(OpPrimer::BorderBoxRowComponent) do + def self.name + "MyRow" + end + + def button_links + [ + edit_button, + delete_button + ] + end + + def edit_button + render(Primer::Beta::Button.new(scheme: :secondary, tag: :a, href: "#")) { "Edit" } + end + + def delete_button + render(Primer::Beta::IconButton.new(icon: :trash, scheme: :danger, tag: :a, href: "#", "aria-label": "Delete")) + end + + def foo + "foo" + end + + def bar + "bar" + end + end + end + + def has_footer? + true + end + + def footer + render(Primer::BaseComponent.new(tag: :span)) do + concat render(Primer::Beta::Text.new) { "This can be a custom footer component " } + concat render(Primer::Beta::Link.new(href: "#")) { "with all sorts of things" } + end + end + + def headers + [ + [:foo, { caption: "Foo column" }], + [:bar, { caption: "Bar column" }] + ] + end + end + + render(table.new(rows: [1, 2])) +%> From 951ae05cd6f395369bdb43a5d6b87cf1cecaa524 Mon Sep 17 00:00:00 2001 From: Mir Bhatia Date: Thu, 3 Apr 2025 16:38:49 +0200 Subject: [PATCH 12/13] Clean up --- lookbook/docs/components/border-box.md.erb | 4 ++-- lookbook/docs/components/tables/border-box-table.md.erb | 2 +- lookbook/docs/components/tables/tables.md.erb | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/lookbook/docs/components/border-box.md.erb b/lookbook/docs/components/border-box.md.erb index c3176219af1..176cae0e1ac 100644 --- a/lookbook/docs/components/border-box.md.erb +++ b/lookbook/docs/components/border-box.md.erb @@ -15,7 +15,7 @@ If a page uses a Border Box with a header, all sections must use headers. The header can either be static or collapsible. -The collapsibleHeader brings additional functionality: +The CollapsibleHeader brings additional functionality: - an **arrow indicator** next to the title indicates if the section is collapsed or expanded. - a **header description** (optional) to give additional context to the content of that section. Hidden when collapsed. @@ -23,7 +23,7 @@ The collapsibleHeader brings additional functionality: When collapsed, the bottom border is slightly thicker to indicate something is hidden. -Both the collapsible header and static heads can accept additional actions. For example, a **more button** can offer additional contextual actions such as edit, delete and move (move up, move to top, move down, move to the end). +Both the collapsible and static headers can accept additional actions. For example, a **more button** can offer additional contextual actions such as edit, delete and move (move up, move to top, move down, move to the end). <%= embed OpPrimer::BorderBoxComponentPreview, :collapsible %> diff --git a/lookbook/docs/components/tables/border-box-table.md.erb b/lookbook/docs/components/tables/border-box-table.md.erb index 449221682ba..ed4c30bed60 100644 --- a/lookbook/docs/components/tables/border-box-table.md.erb +++ b/lookbook/docs/components/tables/border-box-table.md.erb @@ -71,7 +71,7 @@ columns :title, :users, :created_at # Make title column wider than the others (factor 2 using grid span) main_column :title ``` -Note: Ideally, one one main column will be present for each table. +Note: Ideally, only one main column will be present for each table. ### Footer diff --git a/lookbook/docs/components/tables/tables.md.erb b/lookbook/docs/components/tables/tables.md.erb index 559ffea6bb6..08a226eb140 100644 --- a/lookbook/docs/components/tables/tables.md.erb +++ b/lookbook/docs/components/tables/tables.md.erb @@ -50,7 +50,7 @@ end **Headers** -Define the headers of the component as a method retu +Define the headers of the component as a method: ```ruby module ModuleA @@ -72,7 +72,7 @@ end **Actions** -Define the actions in the row component as `button_links`. See the example code +Define the actions in the row component as `button_links`. See the example code: ### Full example From bb7f75cb19c2c0989307c18835372cdda3428bc1 Mon Sep 17 00:00:00 2001 From: Henriette Darge Date: Fri, 4 Apr 2025 08:22:44 +0200 Subject: [PATCH 13/13] Fix some links --- lookbook/docs/components/border-box.md.erb | 2 +- .../op_primer/border_box_table_component_preview.rb | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/lookbook/docs/components/border-box.md.erb b/lookbook/docs/components/border-box.md.erb index 176cae0e1ac..6cbd9852c16 100644 --- a/lookbook/docs/components/border-box.md.erb +++ b/lookbook/docs/components/border-box.md.erb @@ -35,7 +35,7 @@ Some places in which we already use the Border Box: - to display the a list of project attributes in Project settings - to display a list of configured OAuth applications -If the content needs to be more structured (with columns and column headers), please use the [Border Box Table](border-box-table) component instead. +If the content needs to be more structured (with columns and column headers), please use the [Border Box Table](./tables/border_box_table) component instead. ## Best practices diff --git a/lookbook/previews/op_primer/border_box_table_component_preview.rb b/lookbook/previews/op_primer/border_box_table_component_preview.rb index c9c4365cc78..02121b17095 100644 --- a/lookbook/previews/op_primer/border_box_table_component_preview.rb +++ b/lookbook/previews/op_primer/border_box_table_component_preview.rb @@ -4,22 +4,22 @@ module OpPrimer # @logical_path OpenProject/Primer # @display min_height 300px class BorderBoxTableComponentPreview < Lookbook::Preview - # See the [component documentation](/lookbook/pages/components/border_box_table) for more details. + # See the [component documentation](/lookbook/pages/components/tables/border_box_table) for more details. def default render_with_template end - # See the [component documentation](/lookbook/pages/components/border_box_table) for more details. + # See the [component documentation](/lookbook/pages/components/tables/border_box_table) for more details. def custom_column_widths render_with_template end - # See the [component documentation](/lookbook/pages/components/border_box_table) for more details. + # See the [component documentation](/lookbook/pages/components/tables/border_box_table) for more details. def with_action_menu render_with_template end - # See the [component documentation](/lookbook/pages/components/border_box_table) for more details. + # See the [component documentation](/lookbook/pages/components/tables/border_box_table) for more details. def with_footer render_with_template end