[libadwaita/wip/exalm/docs: 12/14] doc: Add Boxed Lists page

[Alexander Mikhaylenko <alexm src gnome org>]

commit cbea153f7189b1d38462a14a7149aebc2edf0c78
Author: Alexander Mikhaylenko <alexm gnome org>
Date:   Sun Dec 26 21:36:05 2021 +0500

    doc: Add Boxed Lists page

 doc/boxed-lists.md     | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/libadwaita.toml.in |  2 ++
 doc/meson.build        |  1 +
 doc/style-classes.md   |  4 +--
 4 files changed, 95 insertions(+), 2 deletions(-)
---
diff --git a/doc/boxed-lists.md b/doc/boxed-lists.md
new file mode 100644
index 00000000..640c8309
--- /dev/null
+++ b/doc/boxed-lists.md
@@ -0,0 +1,90 @@
+Title: Boxed Lists
+Slug: boxed-lists
+
+# Boxed Lists
+
+Libadwaita provides API to implement the [boxed 
lists](https://developer.gnome.org/hig/patterns/containers/boxed-lists.html)
+pattern.
+
+Boxed lists are composed of a [class@Gtk.ListBox] with the
+[property@Gtk.ListBox:selection-mode] set to `GTK_SELECTION_NONE` and with the
+[`.boxed-list`](style-classes.html#boxed-lists-cards) style class.
+
+[class@Gtk.ListView] cannot be used as a boxed list at the moment.
+
+An example boxed list:
+
+```xml
+<object class="GtkListBox">
+  <property name="selection-mode">none</property>
+  <style>
+    <class name="boxed-list"/>
+  </style>
+  <child>
+    <object class="AdwActionRow">
+      <property name="title">Item 1</property>
+    </object>
+  </child>
+  <child>
+    <object class="AdwActionRow">
+      <property name="title">Item 2</property>
+    </object>
+  </child>
+  <child>
+    <object class="AdwActionRow">
+      <property name="title">Item 3</property>
+    </object>
+  </child>
+</object>
+```
+
+<picture>
+  <source srcset="boxed-lists-dark.png" media="(prefers-color-scheme: dark)">
+  <img src="boxed-lists.png" alt="boxed-lists">
+</picture>
+
+# Rows
+
+A number of predefined list row classes are available and intended to be used
+inside boxed lists:
+
+## Action Rows
+
+[class@ActionRow] is a basic row. It has a title, a subtitle, an icon, and can
+have prefix and suffix children.
+
+<picture>
+  <source srcset="action-row-dark.png" media="(prefers-color-scheme: dark)">
+  <img src="action-row.png" alt="action-row">
+</picture>
+
+## Expander Rows
+
+[class@ExpanderRow] is similar to [class@ActionRow], but can expand to show
+other rows.
+
+<picture>
+  <source srcset="expander-row-dark.png" media="(prefers-color-scheme: dark)">
+  <img src="expander-row.png" alt="expander-row">
+</picture>
+
+## Combo Rows
+
+[class@ComboRow] is a row with an embedded drop down menu, similar to
+[class@Gtk.DropDown].
+
+<picture>
+  <source srcset="combo-row-dark.png" media="(prefers-color-scheme: dark)">
+  <img src="combo-row.png" alt="combo-row">
+</picture>
+
+## Preferences Group
+
+[class@PreferencesGroup] provides a boxed list along with a title and a
+description. It's mainly meant to be used as a child of [class@PreferencesPage],
+but can also be used separately.
+
+<picture>
+  <source srcset="preferences-group-dark.png" media="(prefers-color-scheme: dark)">
+  <img src="preferences-group.png" alt="preferences-group">
+</picture>
diff --git a/doc/libadwaita.toml.in b/doc/libadwaita.toml.in
index ffca0ffd..592fe2fe 100644
--- a/doc/libadwaita.toml.in
+++ b/doc/libadwaita.toml.in
@@ -40,6 +40,8 @@ urlmap_file = "urlmap.js"
 content_files = [
   "build-howto.md",
 
+  "boxed-lists.md",
+
   "styles-and-appearance.md",
   "named-colors.md",
   "style-classes.md",
diff --git a/doc/meson.build b/doc/meson.build
index 77e83b31..f8b73a00 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -3,6 +3,7 @@ if get_option('gtk_doc')
 subdir('tools')
 
 expand_content_md_files = [
+  'boxed-lists.md',
   'build-howto.md',
   'migrating-between-development-versions.md',
   'migrating-libhandy-1-4-to-libadwaita.md',
diff --git a/doc/style-classes.md b/doc/style-classes.md
index 9e2ff917..e2704904 100644
--- a/doc/style-classes.md
+++ b/doc/style-classes.md
@@ -348,8 +348,8 @@ state.
 </picture>
 
 The `.boxed-list` style class can be applied to a [class@Gtk.ListBox] to make it
-a boxed list. The list box should have [property@Gtk.ListBox:selection-mode] set
-to `GTK_SELECTION_NONE`.
+a [boxed list](boxed-lists.html). The list box should have
+[property@Gtk.ListBox:selection-mode] set to `GTK_SELECTION_NONE`.
 
 <picture>
   <source srcset="cards-dark.png" media="(prefers-color-scheme: dark)">