restore old ExpandableBlock api

.changeset/tidy-days-appear.md

@@ -1,7 +1,7 @@
 ---
-'@itwin/itwinui-react': major
+'@itwin/itwinui-react': minor
 ---
 
-Updated Expandable Block component to be composition of customizable subcomponents: <ExpandableBlock.Header/>, <ExpandableBlock.ExpandIcon/>, <ExpandableBlock.LabelArea/>, <ExpandableBlock.Title/>, <ExpandableBlock.Caption/>, <ExpandableBlock.EndIcon/>, <ExpandableBlock.Content/>
+Updated `ExpandableBlock` to support customizable subcomponents: `<ExpandableBlock.Wrapper/>`, `<ExpandableBlock.Trigger/>`, `<ExpandableBlock.ExpandIcon/>`, `<ExpandableBlock.LabelArea/>`, `<ExpandableBlock.Title/>`, `<ExpandableBlock.Caption/>`, `<ExpandableBlock.EndIcon/>`, `<ExpandableBlock.Content/>`
 
-The following props have been removed as they are now subcomponents: `title`, `caption`, `endIcon`
+The old api is still supported for backwards compatibility.

apps/storybook/src/ExpandableBlock.stories.tsx

@@ -28,25 +28,24 @@ export default {
 
 export const Basic: Story<Partial<ExpandableBlockProps>> = (args) => {
   return (
-    <ExpandableBlock {...args}>
-      <ExpandableBlock.Header label='Basic Block' />
-      <ExpandableBlock.Content>{args.children}</ExpandableBlock.Content>
+    <ExpandableBlock title='Basic Block' {...args}>
+      Content in block!
     </ExpandableBlock>
   );
 };
 
 export const WithCaption: Story<Partial<ExpandableBlockProps>> = (args) => {
   return (
-    <ExpandableBlock {...args}>
-      <ExpandableBlock.Header>
+    <ExpandableBlock.Wrapper {...args}>
+      <ExpandableBlock.Trigger>
         <ExpandableBlock.ExpandIcon />
         <ExpandableBlock.LabelArea>
           <ExpandableBlock.Title>Basic Block</ExpandableBlock.Title>
           <ExpandableBlock.Caption>basic caption</ExpandableBlock.Caption>
         </ExpandableBlock.LabelArea>
-      </ExpandableBlock.Header>
+      </ExpandableBlock.Trigger>
       <ExpandableBlock.Content>{args.children}</ExpandableBlock.Content>
-    </ExpandableBlock>
+    </ExpandableBlock.Wrapper>
   );
 };
 
@@ -58,10 +57,10 @@ export const Accordion: Story<Partial<ExpandableBlockProps>> = (args) => {
   return (
     <>
       {[...Array(3).fill(null)].map((_, index) => (
-        <ExpandableBlock key={index} {...args}>
-          <ExpandableBlock.Header label={`Basic Block #${index + 1}`} />
+        <ExpandableBlock.Wrapper key={index} {...args}>
+          <ExpandableBlock.Trigger label={`Basic Block #${index + 1}`} />
           <ExpandableBlock.Content>{args.children}</ExpandableBlock.Content>
-        </ExpandableBlock>
+        </ExpandableBlock.Wrapper>
       ))}
     </>
   );
@@ -74,16 +73,16 @@ Accordion.argTypes = {
 
 export const StatusIcon: Story<Partial<ExpandableBlockProps>> = (args) => {
   return (
-    <ExpandableBlock status='positive' {...args}>
-      <ExpandableBlock.Header>
+    <ExpandableBlock.Wrapper status='positive' {...args}>
+      <ExpandableBlock.Trigger>
         <ExpandableBlock.ExpandIcon />
         <ExpandableBlock.LabelArea>
           <ExpandableBlock.Title>Basic Block With Status</ExpandableBlock.Title>
         </ExpandableBlock.LabelArea>
         <ExpandableBlock.EndIcon />
-      </ExpandableBlock.Header>
+      </ExpandableBlock.Trigger>
       <ExpandableBlock.Content>{args.children}</ExpandableBlock.Content>
-    </ExpandableBlock>
+    </ExpandableBlock.Wrapper>
   );
 };
 
@@ -93,10 +92,10 @@ StatusIcon.args = {
 
 export const Small: Story<Partial<ExpandableBlockProps>> = (args) => {
   return (
-    <ExpandableBlock size='small' {...args}>
-      <ExpandableBlock.Header label='Basic Block' />
+    <ExpandableBlock.Wrapper size='small' {...args}>
+      <ExpandableBlock.Trigger label='Basic Block' />
       <ExpandableBlock.Content>{args.children}</ExpandableBlock.Content>
-    </ExpandableBlock>
+    </ExpandableBlock.Wrapper>
   );
 };
 
@@ -106,10 +105,10 @@ Small.args = {
 
 export const Borderless: Story<Partial<ExpandableBlockProps>> = (args) => {
   return (
-    <ExpandableBlock styleType='borderless' {...args}>
-      <ExpandableBlock.Header label='Basic Block' />
+    <ExpandableBlock.Wrapper styleType='borderless' {...args}>
+      <ExpandableBlock.Trigger label='Basic Block' />
       <ExpandableBlock.Content>{args.children}</ExpandableBlock.Content>
-    </ExpandableBlock>
+    </ExpandableBlock.Wrapper>
   );
 };
 
@@ -119,9 +118,9 @@ Borderless.args = {
 
 export const Disabled: Story<Partial<ExpandableBlockProps>> = (args) => {
   return (
-    <ExpandableBlock disabled {...args}>
-      <ExpandableBlock.Header label='Disabled Block' />
+    <ExpandableBlock.Wrapper disabled {...args}>
+      <ExpandableBlock.Trigger label='Disabled Block' />
       <ExpandableBlock.Content>{args.children}</ExpandableBlock.Content>
-    </ExpandableBlock>
+    </ExpandableBlock.Wrapper>
   );
 };

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

@@ -14,17 +14,22 @@ import * as AllExamples from 'examples';
 
 <p>{frontmatter.description}</p>
 
-<LiveExample src='ExpandableBlock.main.tsx'>
+<LiveExample src='ExpandableBlock.main.tsx' truncate={false}>
   <AllExamples.ExpandableBlockMainExample client:load />
 </LiveExample>
 
 The expandable block has a label reflecting its content. On click, it expands to reveal more content.
 
-## Variants
+## Usage
+
+The expandable block can be used in two ways:
+
+- Directly using `ExpandableBlock` along with `title`, `caption`, `endIcon` and children. This pattern can suffice for simple cases.
+- Using subcomponents (`ExpandableBlock.Wrapper`, `ExpandableBlock.Trigger`, `ExpandableBlock.Content`, etc). This pattern is more verbose but allows full customization over all the parts.
 
 ### With caption
 
-Users can optionally display descriptor text underneath the title.
+Descriptor text can be optionally displayed underneath the title, either using the `caption` prop or the `ExpandableBlock.Caption` subcomponent.
 
 <LiveExample src='ExpandableBlock.withcaption.tsx'>
   <AllExamples.ExpandableBlockWithCaptionExample client:load />
@@ -40,7 +45,7 @@ Expandable blocks can also stack on top of each other in an accordion to make la
 
 ### With status
 
-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, an icon, or other helpful information at a glance right aligned within the block header. The status can be set using the `status` prop, and the icon can be customized using either the `endIcon` prop or the `ExpandableBlock.EndIcon` subcomponent.
 
 <LiveExample src='ExpandableBlock.status.tsx'>
   <AllExamples.ExpandableBlockStatusExample client:load />
@@ -70,9 +75,9 @@ An expandable block can be disabled by using the `disabled` prop.
   <AllExamples.ExpandableBlockDisabledExample client:load />
 </LiveExample>
 
-## Usage
+## Guidelines
 
-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
+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
 

examples/ExpandableBlock.accordion.tsx

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

examples/ExpandableBlock.borderless.tsx

@@ -8,10 +8,10 @@ import { ExpandableBlock } from '@itwin/itwinui-react';
 export default () => {
   return (
     <div style={{ width: 'min(100%, 300px)' }}>
-      <ExpandableBlock styleType='borderless'>
-        <ExpandableBlock.Header label='Borderless expandable block' />
+      <ExpandableBlock.Wrapper styleType='borderless'>
+        <ExpandableBlock.Trigger label='Borderless expandable block' />
         <ExpandableBlock.Content>Content in block!</ExpandableBlock.Content>
-      </ExpandableBlock>
+      </ExpandableBlock.Wrapper>
     </div>
   );
 };

examples/ExpandableBlock.disabled.tsx

@@ -8,10 +8,10 @@ import { ExpandableBlock } from '@itwin/itwinui-react';
 export default () => {
   return (
     <div style={{ width: 'min(100%, 300px)' }}>
-      <ExpandableBlock disabled>
-        <ExpandableBlock.Header label='Disabled expandable block' />
+      <ExpandableBlock.Wrapper disabled>
+        <ExpandableBlock.Trigger label='Disabled expandable block' />
         <ExpandableBlock.Content>Content in block!</ExpandableBlock.Content>
-      </ExpandableBlock>
+      </ExpandableBlock.Wrapper>
     </div>
   );
 };

examples/ExpandableBlock.form.tsx

@@ -49,18 +49,18 @@ export default () => {
 
   return (
     <div style={{ width: 'min(100%, 300px)' }}>
-      <ExpandableBlock>
-        <ExpandableBlock.Header label='Name' />
+      <ExpandableBlock.Wrapper>
+        <ExpandableBlock.Trigger label='Name' />
         <ExpandableBlock.Content>{nameSection}</ExpandableBlock.Content>
-      </ExpandableBlock>
-      <ExpandableBlock>
-        <ExpandableBlock.Header label='Favorite Color' />
+      </ExpandableBlock.Wrapper>
+      <ExpandableBlock.Wrapper>
+        <ExpandableBlock.Trigger label='Favorite Color' />
         <ExpandableBlock.Content>{colorSection}</ExpandableBlock.Content>
-      </ExpandableBlock>
-      <ExpandableBlock>
-        <ExpandableBlock.Header label='Reasoning' />
+      </ExpandableBlock.Wrapper>
+      <ExpandableBlock.Wrapper>
+        <ExpandableBlock.Trigger label='Reasoning' />
         <ExpandableBlock.Content>{reasonSection}</ExpandableBlock.Content>
-      </ExpandableBlock>
+      </ExpandableBlock.Wrapper>
     </div>
   );
 };

examples/ExpandableBlock.main.tsx

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

examples/ExpandableBlock.small.tsx

@@ -8,10 +8,10 @@ import { ExpandableBlock } from '@itwin/itwinui-react';
 export default () => {
   return (
     <div style={{ width: 'min(100%, 300px)' }}>
-      <ExpandableBlock size='small'>
-        <ExpandableBlock.Header label='Small expandable Block' />
+      <ExpandableBlock.Wrapper size='small'>
+        <ExpandableBlock.Trigger label='Small expandable Block' />
         <ExpandableBlock.Content>Content in block!</ExpandableBlock.Content>
-      </ExpandableBlock>
+      </ExpandableBlock.Wrapper>
     </div>
   );
 };

examples/ExpandableBlock.status.tsx

@@ -9,58 +9,58 @@ import { SvgSmileyHappy } from '@itwin/itwinui-icons-react';
 export default () => {
   return (
     <div style={{ width: 'min(100%, 300px)' }}>
-      <ExpandableBlock status='positive'>
-        <ExpandableBlock.Header>
+      <ExpandableBlock.Wrapper status='positive'>
+        <ExpandableBlock.Trigger>
           <ExpandableBlock.ExpandIcon />
           <ExpandableBlock.LabelArea>
             <ExpandableBlock.Title>Positive block</ExpandableBlock.Title>
           </ExpandableBlock.LabelArea>
           <ExpandableBlock.EndIcon />
-        </ExpandableBlock.Header>
+        </ExpandableBlock.Trigger>
         <ExpandableBlock.Content>Content in block!</ExpandableBlock.Content>
-      </ExpandableBlock>
-      <ExpandableBlock status='negative'>
-        <ExpandableBlock.Header>
+      </ExpandableBlock.Wrapper>
+      <ExpandableBlock.Wrapper status='negative'>
+        <ExpandableBlock.Trigger>
           <ExpandableBlock.ExpandIcon />
           <ExpandableBlock.LabelArea>
             <ExpandableBlock.Title>Negative block</ExpandableBlock.Title>
           </ExpandableBlock.LabelArea>
           <ExpandableBlock.EndIcon />
-        </ExpandableBlock.Header>
+        </ExpandableBlock.Trigger>
         <ExpandableBlock.Content>Content in block!</ExpandableBlock.Content>
-      </ExpandableBlock>
-      <ExpandableBlock status='warning'>
-        <ExpandableBlock.Header>
+      </ExpandableBlock.Wrapper>
+      <ExpandableBlock.Wrapper status='warning'>
+        <ExpandableBlock.Trigger>
           <ExpandableBlock.ExpandIcon />
           <ExpandableBlock.LabelArea>
             <ExpandableBlock.Title>Warning block</ExpandableBlock.Title>
           </ExpandableBlock.LabelArea>
           <ExpandableBlock.EndIcon />
-        </ExpandableBlock.Header>
+        </ExpandableBlock.Trigger>
         <ExpandableBlock.Content>Content in block!</ExpandableBlock.Content>
-      </ExpandableBlock>
-      <ExpandableBlock status='informational'>
-        <ExpandableBlock.Header>
+      </ExpandableBlock.Wrapper>
+      <ExpandableBlock.Wrapper status='informational'>
+        <ExpandableBlock.Trigger>
           <ExpandableBlock.ExpandIcon />
           <ExpandableBlock.LabelArea>
             <ExpandableBlock.Title>Informational block</ExpandableBlock.Title>
           </ExpandableBlock.LabelArea>
           <ExpandableBlock.EndIcon />
-        </ExpandableBlock.Header>
+        </ExpandableBlock.Trigger>
         <ExpandableBlock.Content>Content in block!</ExpandableBlock.Content>
-      </ExpandableBlock>
-      <ExpandableBlock>
-        <ExpandableBlock.Header>
+      </ExpandableBlock.Wrapper>
+      <ExpandableBlock.Wrapper>
+        <ExpandableBlock.Trigger>
           <ExpandableBlock.ExpandIcon />
           <ExpandableBlock.LabelArea>
             <ExpandableBlock.Title>Happy block</ExpandableBlock.Title>
           </ExpandableBlock.LabelArea>
           <ExpandableBlock.EndIcon>
             <SvgSmileyHappy />
           </ExpandableBlock.EndIcon>
-        </ExpandableBlock.Header>
+        </ExpandableBlock.Trigger>
         <ExpandableBlock.Content>Content in block!</ExpandableBlock.Content>
-      </ExpandableBlock>
+      </ExpandableBlock.Wrapper>
     </div>
   );
 };

examples/ExpandableBlock.withcaption.tsx

@@ -8,16 +8,16 @@ import { ExpandableBlock } from '@itwin/itwinui-react';
 export default () => {
   return (
     <div style={{ width: 'min(100%, 300px)' }}>
-      <ExpandableBlock size='small'>
-        <ExpandableBlock.Header>
+      <ExpandableBlock.Wrapper size='small'>
+        <ExpandableBlock.Trigger>
           <ExpandableBlock.ExpandIcon />
           <ExpandableBlock.LabelArea>
             <ExpandableBlock.Title>Expandable Block</ExpandableBlock.Title>
             <ExpandableBlock.Caption>With caption!</ExpandableBlock.Caption>
           </ExpandableBlock.LabelArea>
-        </ExpandableBlock.Header>
+        </ExpandableBlock.Trigger>
         <ExpandableBlock.Content>Content in block!</ExpandableBlock.Content>
-      </ExpandableBlock>
+      </ExpandableBlock.Wrapper>
     </div>
   );
 };