Extend toolbar docs

Author: alex-c

docs/src/pages/page-home.tsx

@@ -102,10 +102,11 @@ export const HomePage = () => {
       <Section title="Usage">
         <p>
           A <strong>Blueprint Datagrid</strong> is created with the <Code>Datagrid</Code> component and by passing it an
-          array of objects as <Code>dataSource</Code>, which contain
+          array of objects as <Code>dataSource</Code>, which contains
           the data to use as the contents of the table. The <Code>Datagrid</Code> is mainy configured by passing
-          additional components to it's slot, like <Code>Column</Code>{" "}
-          components or the <Code>Pager</Code>:
+          additional components to it's slot, like <Code>Column</Code>s or the <Code>Toolbar</Code> component, which can
+          hold additional controls like
+          the <Code>Pager</Code>:
         </p>
         <Example code={usageExampleCode} showCode>
           <Datagrid dataSource={varieties}>

docs/src/pages/page-toolbars.tsx

@@ -4,6 +4,9 @@ import { Page } from "../components/page";
 import { Section } from "../components/section";
 import { Variety } from "../data/pepper-varieties/pepper-varieties";
 import { Example } from "../components/example";
+import { useAppSelector } from "../app/hooks";
+import React from "react";
+import { Link } from "react-router-dom";
 
 const positioningDemoCode = `<Datagrid dataSource={[] as Variety[]}>
   <Toolbar position={ToolbarPosition.TOP}>
@@ -23,13 +26,24 @@ const positioningDemoCode = `<Datagrid dataSource={[] as Variety[]}>
   </Toolbar>
 </Datagrid>`;
 
+const pagerPositioningExampleCode = `<Datagrid dataSource={varieties}>
+  <Column field="name" label="Name" />
+  <Column field="shuUpperBound" label="Heat (SHU)" type={ColumnType.NUMBER} />
+  <Column field="rare" label="Rare" type={ColumnType.BOOLEAN} />
+  <Toolbar position={ToolbarPosition.BOTTOM}>
+    <Pager elementsPerPage={5} align={Alignment.CENTER} />
+  </Toolbar>
+</Datagrid>`;
+
 const DemoBox = (props: { position: ToolbarPosition, align: Alignment }) => {
   return (
     <Tag intent={Intent.PRIMARY}>{props.position} {props.align}</Tag>
   );
 };
 
 export const ToolbarsPage = () => {
+  const { varieties } = useAppSelector(state => state.varieties);
+
   return (
     <Page title="Toolbars">
       <Section>
@@ -56,6 +70,30 @@ export const ToolbarsPage = () => {
           </Datagrid>
         </Example>
       </Section>
+      <Section title="Toolbar Components">
+        <p>Three types of components can be placed inside toolbars:
+          <ul>
+            <li>Special <strong>Blueprint Datagrid</strong> controls</li>
+            <li>Table-level actions</li>
+            <li>Any custom component</li>
+          </ul>
+        </p>
+        <p>Some <strong>Blueprint Datagrid</strong> controls can be placed in any of the toolbars with any alignment in
+          order to activate a feature. The <Code>Pager</Code> component, for example, activates pagination (see <Link to={"/pagination"}>Pagination</Link> for more information):</p>
+        <Example code={pagerPositioningExampleCode}>
+          <Datagrid dataSource={varieties}>
+            <Column field="name" label="Name" />
+            <Column field="shuUpperBound" label="Heat (SHU)" type={ColumnType.NUMBER} />
+            <Column field="rare" label="Rare" type={ColumnType.BOOLEAN} />
+            <Toolbar position={ToolbarPosition.BOTTOM}>
+              <Pager elementsPerPage={5} align={Alignment.CENTER} />
+            </Toolbar>
+          </Datagrid>
+        </Example>
+        <p>For table-level actions, check out the <Link to={"/pagination"}>Actions</Link> chapter.</p>
+        <p>Finally, any custom component can be passed to a toolbar, provided that it has an <Code>align</Code> prop of type <Code>Alignment</Code>. See the first example on this page for an example!</p>
+      </Section>
     </Page>
-  );
+  )
+    ;
 };