Create how to compose a toolbar guide

aries-site/src/data/structures/learn.js

@@ -3,6 +3,7 @@ import { Grommet } from 'grommet-icons';
 import {
   BoxPreview,
   DataHowTo,
+  DataHowToAddAdditionalControls,
   GridPreview,
 } from '../../examples/cardPreviews';
 
@@ -54,6 +55,21 @@ export const learn = [
     relatedContent: [],
     tags: [],
   },
+  {
+    name: 'How to add additional controls to a toolbar',
+    description:
+      'This how-to guide shows you how compose a Toolbar when controls beyond search and filter are needed.',
+    type: 'How-to guides',
+    preview: {
+      component: () => <DataHowToAddAdditionalControls />,
+      background: 'background-front',
+    },
+    seoDescription:
+      'This how-to guide shows you how compose a Toolbar when controls beyond search and filter are needed.',
+    sections: [],
+    relatedContent: [],
+    tags: [],
+  },
   {
     name: 'Tshirt sizing',
     render: 'T-shirt sizing',

aries-site/src/examples/cardPreviews/data-how-to-add-additional-controls.js

@@ -0,0 +1,17 @@
+import React from 'react';
+import { Box, Button, TextInput } from 'grommet';
+import { Filter, Search, Descend, Columns } from 'grommet-icons';
+
+export const DataHowToAddAdditionalControls = () => (
+  <Box direction="row" align="center" gap="small">
+    <TextInput icon={<Search />} placeholder="Search" tabIndex={-1} />
+    <Button a11yTitle="Sort" icon={<Descend />} kind="toolbar" tabIndex={-1} />
+    <Button a11yTitle="Filter" icon={<Filter />} kind="toolbar" tabIndex={-1} />
+    <Button
+      a11yTitle="Manage columns"
+      icon={<Columns />}
+      kind="toolbar"
+      tabIndex={-1}
+    />
+  </Box>
+);

aries-site/src/examples/cardPreviews/index.js

@@ -8,6 +8,7 @@ export * from './code-blocks';
 export * from './content-layouts';
 export * from './emptystate';
 export * from './data-how-to';
+export * from './data-how-to-add-additional-controls';
 export * from './dateinput';
 export * from './feedback';
 export * from './footer';

aries-site/src/pages/learn/how-to-add-additional-controls-to-a-toolbar.mdx

@@ -0,0 +1,191 @@
+import { Box, Image } from 'grommet';
+
+## Prerequisites
+
+This guide builds off the ["How to add search and filter to DataTable" how-to guide](/learn/how-to-add-search-and-filter-to-datatable-with-data). While it's not necessary to complete that guide first, it may be helpful for additional context.
+
+Let’s get started!
+
+Use this [CodeSandbox template](https://codesandbox.io/p/devbox/how-to-add-additional-controls-to-a-toolbar-gn9q9j?file=%2Fsrc%2FApp.js%3A46%2C20) to start. The template is populated with a paginated DataTable configured to display SpaceX data with search and filter controls.
+
+## Importing the components
+
+In `App.js`, start by importing the Toolbar component and the Data controls you'll include in your toolbar.
+
+```
+import { Box, Data, DataTable, Grommet, DataFilters, DataSearch, DataSort, DataSummary, DataTableColumns, Toolbar } from "grommet";
+
+```
+
+## Compose the toolbar
+
+### Render the controls in the toolbar
+
+Remove the `toolbar` property from Data. Insert the Toolbar and Data controls above the DataTable.
+
+Apply `drop` to DataSort to render the sort controls in a drop and `layer` to DataFilters to render the filters in a side drawer layer.
+
+```
+<Data
+  data={data}
+  properties={{
+    type: {
+      label: "Type",
+      options: [
+        "Dragon 1.0",
+        "Dragon 1.1",
+        "Dragon Boilerplate",
+        "Satellite",
+      ],
+    },
+    mass_lbs: {
+      label: "Mass",
+      range: { min: 0, max: 1400 },
+    },
+  }}
+  view={view}
+  onView={setView}
+  total={numberItems}
+>
+  <Toolbar>
+    <DataSearch />
+    <DataSort drop />
+    <DataFilters layer />
+  </Toolbar>
+  <DataTable columns={columns} />
+  <Pagination />
+</Data>
+```
+
+### Allow user to define column visibility and order
+
+Create a variable, `options`, which defines which properties should be part of the DataTableColumns experience. In this case, we'll dynamically generate these options based on the `columns` of the DataTable.
+
+```
+const options = columns.map(column => ({
+  property: column.property,
+  label: column.header
+}));
+```
+
+Next, add DataTableColumns to the toolbar, passing the `options` variable you created to the `options` property. Similar to the other controls, specify `drop` to render the control in a drop.
+
+```
+<Data
+  data={data}
+  properties={{
+    type: {
+      label: "Type",
+      options: [
+        "Dragon 1.0",
+        "Dragon 1.1",
+        "Dragon Boilerplate",
+        "Satellite",
+      ],
+    },
+    mass_lbs: {
+      label: "Mass",
+      range: { min: 0, max: 1400 },
+    },
+  }}
+  view={view}
+  onView={setView}
+  total={numberItems}
+>
+  <Toolbar>
+    <DataSearch />
+    <DataSort drop />
+    <DataFilters layer />
+    <DataTableColumns options={options} drop />
+  </Toolbar>
+  <DataTable columns={columns} />
+  <Pagination />
+</Data>
+```
+
+### Group controls into sections
+
+Next, create subsections of the toolbar controls in alignment with [data collection toolbar guidance]().
+
+First, group all of the "find" controls (DataSearch, DataSort, and DataFilters) together by wrapping them in their own Toolbar.
+
+Then, add `gap="medium"` to the outermost Toolbar to create more distinction between toolbar sections.
+
+```
+<Data
+  data={data}
+  properties={{
+    type: {
+      label: "Type",
+      options: [
+        "Dragon 1.0",
+        "Dragon 1.1",
+        "Dragon Boilerplate",
+        "Satellite",
+      ],
+    },
+    mass_lbs: {
+      label: "Mass",
+      range: { min: 0, max: 1400 },
+    },
+  }}
+  view={view}
+  onView={setView}
+  total={numberItems}
+>
+  <Toolbar gap="medium">
+    <Toolbar>
+      <DataSearch />
+      <DataSort drop />
+      <DataFilters layer />
+    </Toolbar>
+    <DataTableColumns options={options} drop />
+  </Toolbar>
+  <DataTable columns={columns} />
+  <Pagination />
+</Data>
+```
+
+### Add the data summary
+
+Lastly, add the DataSummary below the toolbar.
+
+```
+<Data
+  data={data}
+  properties={{
+    type: {
+      label: "Type",
+      options: [
+        "Dragon 1.0",
+        "Dragon 1.1",
+        "Dragon Boilerplate",
+        "Satellite",
+      ],
+    },
+    mass_lbs: {
+      label: "Mass",
+      range: { min: 0, max: 1400 },
+    },
+  }}
+  view={view}
+  onView={setView}
+  total={numberItems}
+>
+  <Toolbar gap="medium">
+    <Toolbar>
+      <DataSearch />
+      <DataSort drop />
+      <DataFilters layer />
+    </Toolbar>
+    <DataTableColumns options={options} drop />
+  </Toolbar>
+  <DataSummary />
+  <DataTable columns={columns} />
+  <Pagination />
+</Data>
+```
+
+Congratulations! You’ve used Data subcomponents to compose a toolbar with a variety of controls.
+
+To reference a completed implementation, check out this [CodeSandbox with completed code](https://codesandbox.io/p/devbox/how-to-add-additional-controls-to-a-toolbar-completed-l5nr54?file=%2Fsrc%2FApp.js%3A14%2C15).