website: Update Expandable Block documentation

apps/website/src/components/LiveExample.astro

@@ -96,7 +96,7 @@ if (code.includes('Copyright (c) Bentley Systems')) {
     width: 100%;
     overflow: auto;
     display: grid;
-    align-content: center;
+    align-items: center;
     justify-items: center;
   }
 

apps/website/src/examples/ExpandableBlock.accordion.tsx

@@ -0,0 +1,16 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { ExpandableBlock } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <div style={{ width: 'min(100%, 300px)' }}>
+      <ExpandableBlock title='Block #1'>Content in block!</ExpandableBlock>
+      <ExpandableBlock title='Block #2'>Content in block!</ExpandableBlock>
+      <ExpandableBlock title='Block #3'>Content in block!</ExpandableBlock>
+    </div>
+  );
+};

apps/website/src/examples/ExpandableBlock.borderless.tsx

@@ -0,0 +1,16 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { ExpandableBlock } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <div style={{ width: 'min(100%, 300px)' }}>
+      <ExpandableBlock styleType='borderless' title='Borderless expandable block'>
+        Content in block!
+      </ExpandableBlock>
+    </div>
+  );
+};

apps/website/src/examples/ExpandableBlock.form.tsx

@@ -0,0 +1,47 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { ExpandableBlock, Label, Input, InputGroup, Radio } from '@itwin/itwinui-react';
+
+export default () => {
+  const nameSection = (
+    <>
+      <Label htmlFor='name' required>
+        Name
+      </Label>
+      <Input id='name' key='name' placeholder='Enter name' />
+      <Label htmlFor='occupation'>Occupation</Label>
+      <Input id='occupation' key='occupation' placeholder='Enter occupation' />
+    </>
+  );
+
+  const colorSection = (
+    <InputGroup key='color' label='Choose your favorite color' required>
+      <Radio name='color' value='Red' label='Red' />
+      <Radio name='color' value='Orange' label='Orange' />
+      <Radio name='color' value='Yellow' label='Yellow' />
+      <Radio name='color' value='Green' label='Green' />
+      <Radio name='color' value='Blue' label='Blue' />
+      <Radio name='color' value='Purple' label='Purple' />
+    </InputGroup>
+  );
+
+  const reasonSection = (
+    <>
+      <Label htmlFor='explanation' required>
+        Why is this your favorite color
+      </Label>
+      <Input id='explanation' key='explanation' placeholder='Enter text here...' />
+    </>
+  );
+
+  return (
+    <div style={{ width: 'min(100%, 300px)' }}>
+      <ExpandableBlock title='Name'>{nameSection}</ExpandableBlock>
+      <ExpandableBlock title='Favorite Color'>{colorSection}</ExpandableBlock>
+      <ExpandableBlock title='Reasoning'>{reasonSection}</ExpandableBlock>
+    </div>
+  );
+};

apps/website/src/examples/ExpandableBlock.main.tsx

@@ -8,9 +8,7 @@ import { ExpandableBlock } from '@itwin/itwinui-react';
 export default () => {
   return (
     <div style={{ width: 'min(100%, 300px)' }}>
-      <ExpandableBlock title='Block #1'>Content in block!</ExpandableBlock>
-      <ExpandableBlock title='Block #2'>Content in block!</ExpandableBlock>
-      <ExpandableBlock title='Block #3'>Content in block!</ExpandableBlock>
+      <ExpandableBlock title='Expandable Block'>Content in block!</ExpandableBlock>
     </div>
   );
 };

apps/website/src/examples/ExpandableBlock.small.tsx

@@ -0,0 +1,16 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { ExpandableBlock } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <div style={{ width: 'min(100%, 300px)' }}>
+      <ExpandableBlock size='small' title='Small expandable block'>
+        Content in block!
+      </ExpandableBlock>
+    </div>
+  );
+};

apps/website/src/examples/ExpandableBlock.status.tsx

@@ -0,0 +1,29 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { ExpandableBlock } from '@itwin/itwinui-react';
+import { SvgSmileyHappy } from '@itwin/itwinui-icons-react';
+
+export default () => {
+  return (
+    <div style={{ width: 'min(100%, 300px)' }}>
+      <ExpandableBlock status='positive' title='Positive block'>
+        Content in block!
+      </ExpandableBlock>
+      <ExpandableBlock status='negative' title='Negative block'>
+        Content in block!
+      </ExpandableBlock>
+      <ExpandableBlock status='warning' title='Warning block'>
+        Content in block!
+      </ExpandableBlock>
+      <ExpandableBlock status='informational' title='Informational block'>
+        Content in block!
+      </ExpandableBlock>
+      <ExpandableBlock endIcon={<SvgSmileyHappy />} title='Happy block'>
+        Content in block!
+      </ExpandableBlock>
+    </div>
+  );
+};

apps/website/src/examples/ExpandableBlock.withcaption.tsx

@@ -0,0 +1,16 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { ExpandableBlock } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <div style={{ width: 'min(100%, 300px)' }}>
+      <ExpandableBlock size='small' title='Expandable Block' caption='With caption!'>
+        Content in block!
+      </ExpandableBlock>
+    </div>
+  );
+};

apps/website/src/examples/index.tsx

@@ -85,6 +85,12 @@ export { default as DropdownButtonMainExample } from './DropdownButton.main';
 export { default as DropdownMenuMainExample } from './DropdownMenu.main';
 
 export { default as ExpandableBlockMainExample } from './ExpandableBlock.main';
+export { default as ExpandableBlockWithCaptionExample } from './ExpandableBlock.withcaption';
+export { default as ExpandableBlockAccordionExample } from './ExpandableBlock.accordion';
+export { default as ExpandableBlockStatusExample } from './ExpandableBlock.status';
+export { default as ExpandableBlockSmallExample } from './ExpandableBlock.small';
+export { default as ExpandableBlockBorderlessExample } from './ExpandableBlock.borderless';
+export { default as ExpandableBlockFormExample } from './ExpandableBlock.form';
 
 export { default as FieldsetMainExample } from './Fieldset.main';
 export { default as FieldsetDisabledExample } from './Fieldset.disabled';

apps/website/src/pages/docs/expandableblock.mdx

@@ -9,74 +9,96 @@ group: core
 
 import PropsTable from '~/components/PropsTable.astro';
 import LiveExample from '~/components/LiveExample.astro';
-import Placeholder from '~/components/Placeholder.astro';
+import RelatedComponents from '~/components/RelatedComponents.astro';
 import * as AllExamples from '~/examples';
 
 <p>{frontmatter.description}</p>
 
-<Placeholder componentPageName='core-expandableblock' />
-
 <LiveExample src='ExpandableBlock.main.tsx'>
   <AllExamples.ExpandableBlockMainExample client:load />
 </LiveExample>
 
-Expandable blocks, called expandable rows when inside a table, are used to progressively disclose information. Read this article to learn more about progressive disclosure. Expandable blocks and rows should not be used with flattened hierarchy or information panels. This type of navigation allows the user to see content inside a parent row or block.
+The expandable block has a label reflecting its content. On click, it expands to reveal more content.
 
-## Appearance
+## Variants
 
-### Expandable rows
+### With caption
 
-Expandable rows resemble normal table rows that can be expanded to reveal nested data. An expandable row could optionally be selectable. Because expandable rows are part of a table, the rows must sort based on the table column sort applied. This means expandable rows can not re-arranged, the user must interact with the table header to re-arrange.
+Users can optionally display descriptor text underneath the title.
 
-Expandable rows should not be confused with a tree hierarchy. Unlike trees, they follow a single branch pattern. If you have trouble telling the two apart, the Expandable block VS Hierarchy tree section explains what makes them different.
+<LiveExample src='ExpandableBlock.withcaption.tsx'>
+  <AllExamples.ExpandableBlockWithCaptionExample client:load />
+</LiveExample>
 
-There can be several child elements nested in an expandable row. These indented elements all coexist on the same level without further indentation. If you require more levels, a tree hierarchy is a better pattern for this interaction.
+### Accordion
 
-The child elements don’t reflect the column titles. They are expected to retain the same properties as the parent row (in the example below, the owner). It’s unnecessary to repeat the properties for the child items because of this, so do not include them in the expanded row area.
+Expandable blocks can also stack on top of each other in an accordion to make large sets of information easier to read.
 
-Child items are not interchangeable between rows, e.g. you cannot drag a child item from row A and drag it in row B like you would move files to a folder.
+<LiveExample src='ExpandableBlock.accordion.tsx'>
+  <AllExamples.ExpandableBlockAccordionExample client:load />
+</LiveExample>
 
-### Expandable blocks
+### With status
 
-The main block has a label reflecting its content. On click, it expands to reveal more content.
+An expandable block could display status, an icon, or other helpful information at a glance right aligned within the block header.
 
-An expandable block could display status, a total count, or other helpful information at a glance right aligned within the block header. You may also optionally display descriptor text underneath the title.
+<LiveExample src='ExpandableBlock.status.tsx'>
+  <AllExamples.ExpandableBlockStatusExample client:load />
+</LiveExample>
 
-Expandable blocks don’t always need to be sorted alphabetically, unlike an expandable row which would be sorted based on the table column sort. You may optionally allow expandable blocks to be re-ordered by the user.
+### Small
 
-The visual appearance of an expandable block is different from an expandable row. An expandable block can not be selected / checked like an expandable row can, therefore it is visually styled differently.
+A small expandable block is achieved by using the `size` prop.
 
-## Usage
+<LiveExample src='ExpandableBlock.small.tsx'>
+  <AllExamples.ExpandableBlockSmallExample client:load />
+</LiveExample>
 
-### Expandable rows
+### Borderless
 
-Expandable rows are used in tables. The layout inside expanded rows varies according to requirements. Child rows can be selectable and be an entry point to more content (ex.: downloadable files), or only contain metadata about the parent file. If at least one row within a table is expandable, all rows should follow the same pattern. Avoid mixing regular table rows with expandable rows.
+The borderless expandable block is useful in tighter areas where using a default expandable block would visibly cause too many blocks. The borderless expandable block is achieved by using the `styleType` prop.
 
-### Expandable blocks
+<LiveExample src='ExpandableBlock.borderless.tsx'>
+  <AllExamples.ExpandableBlockBorderlessExample client:load />
+</LiveExample>
+
+## Usage
+
+Expandable blocks are used to progressively disclose information. [Read this article to learn more about progressive disclosure.](https://www.nngroup.com/articles/progressive-disclosure/) Expandable blocks should not be used with flattened hierarchy or information panels. [Table](table) rows can also expand similarly to expandable block
+
+### Forms
 
 Expandable blocks are used in pages to divide up content in sections, in forms for example. If each section has many fields, using expandable blocks will help alleviate the UI and prevent the user from scrolling endlessly to get to the section they are looking for.
 
-Expanded block containing form elements within an interface.
+<LiveExample src='ExpandableBlock.form.tsx'>
+  <AllExamples.ExpandableBlockFormExample client:load />
+</LiveExample>
 
-### Expandable blocks VS hierarchy tree
+### Expandable blocks vs hierarchy tree
 
-While these two patterns may appear similar, they both fulfill a different role and are not interchangeable. Here are some tips to determine if an expandable block or row is what you need.
+While these two patterns may appear similar, they both fulfill a different role and are not interchangeable. Here are some tips to determine if an expandable block is what you need.
 
-Use an expandable rows/blocks when:
+Use an expandable block when:
 
-- You need a row in a table to display additional metadata that doesn’t align with the column content;
-- You have a page with different sections all containing user-generated content that would benefit from being split up;
-- There is only one level of indentation possible at all times;
-- The content you want to be expandable varies from simple list items to more complex form components (such as text fields, buttons, etc.).
+- You have a page with different sections all containing user-generated content that would benefit from being split up
+- There is only one level of indentation possible at all times
+- The content you want to be expandable varies from simple list items to more complex form components (such as text fields, buttons, etc.)
 
-Use a hierarchy tree when:
+Use a [hierarchy tree](tree) when:
 
-- You require a pattern that works with several levels of data (folder drilling);
-- There are only list items in the pattern;
-- The hierarchy is not necessarily linear and may branch out.
+- You require a pattern that works with several levels of data (folder drilling)
+- There are only list items in the pattern
+- The hierarchy is not necessarily linear and may branch out
 
 ## Props
 
 <PropsTable path={frontmatter.propsPath} />
 
-## Related resources
+## Related components
+
+<RelatedComponents
+  components={[
+    { title: 'Table', url: 'table' },
+    { title: 'Tree', url: 'tree' },
+  ]}
+/>