Documentation: Tile

.changeset/polite-walls-rush.md

@@ -2,6 +2,4 @@
 '@itwin/itwinui-react': major
 ---
 
-Updated Tile component to allow composition of customizable subcomponents: <Tile.Wrapper/>, <Tile.Name/>, <Tile.NameIcon/>, <Tile.NameLabel/>, <Tile.ThumbnailArea/>, <Tile.ThumbnailPicture/>, <Tile.BadgeContainer/>, <Tile.TypeIndicator/>, <Tile.QuickAction/>, <Tile.ContentArea/>, <Tile.Description/>, <Tile.MoreOptions/>, <Tile.Metadata/>, <Tile.Buttons/>
-
-<IconButton /> used in a <Tile /> must be replaced with <Tile.IconButton />.
+Updated Tile component to allow composition of customizable subcomponents: <Tile.Wrapper/>, <Tile.Name/>, <Tile.NameIcon/>, <Tile.NameLabel/>, <Tile.ThumbnailArea/>, <Tile.ThumbnailPicture/>, <Tile.BadgeContainer/>, <Tile.TypeIndicator/>, <Tile.QuickAction/>, <Tile.ContentArea/>, <Tile.Description/>, <Tile.MoreOptions/>, <Tile.Metadata/>, <Tile.Buttons/>.

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

@@ -14,14 +14,130 @@ import * as AllExamples from 'examples';
 
 <p>{frontmatter.description}</p>
 
-<Placeholder componentPageName='core-tile' />
-
 <LiveExample src='Tile.main.tsx'>
   <AllExamples.TileMainExample client:load />
 </LiveExample>
 
 Tiles are containers that display content and actions pertaining to a single item or project. They should be easy to scan for relevant and actionable information. All text should be concise and placed in a way that clearly indicates informational hierarchy.
 
-## Props
+### Composition API
+
+Users can build Tiles with subcomponents that are fully customizable.
+
+We provide:
+
+- `Tile.Wrapper`
+- `Tile.ThumbnailArea`
+- `Tile.ThumbnailPicture`
+- `Tile.QuickAction`
+- `Tile.TypeIndicator`
+- `Tile.BadgeContainer`
+- `Tile.IconButton`
+- `Tile.Name`
+- `Tile.NameIcon`
+- `Tile.NameLabel`
+- `Tile.Action`
+- `Tile.ContentArea`
+- `Tile.Description`
+- `Tile.Metadata`
+- `Tile.MoreOptions`
+- `Tile.Buttons`
+
+<LiveExample src='Tile.composition.tsx'>
+  <AllExamples.TileCompositionExample client:load />
+</LiveExample>
+
+### Props API
+
+Users can also take advantage of properties provided for `Tile`. A list of available properties can be found [at the end](#props) of this documentation.
+
+<LiveExample src='Tile.props.tsx'>
+  <AllExamples.TilePropsExample client:load />
+</LiveExample>
+
+## Variants
+
+### Actionable
+
+Click on an actionable tile triggers an action.
+
+<LiveExample src='Tile.actionable.tsx'>
+  <AllExamples.TileActionableExample client:load />
+</LiveExample>
+
+Tile can also link to another page.
+
+<LiveExample src='Tile.anchorlink.tsx'>
+  <AllExamples.TileAnchorLinkExample client:load style={{ padding: 50 }} />
+</LiveExample>
+
+A tile might have one or two buttons to perform actions. There cannot be more than two button actions.
+
+<LiveExample src='Tile.quickactions.tsx'>
+  <AllExamples.TileQuickActionsExample client:load />
+</LiveExample>
+
+### Avatar
+
+Avatar tile may look a little different from the rest of the tiles as the thumbnail area instead displays an avatar icon and online status indicator.
+
+<LiveExample src='Tile.avatar.tsx'>
+  <AllExamples.TileAvatarExample client:load />
+</LiveExample>
+
+### Condensed
+
+A condensed tile may include as little as the title, thumbnail, and more menu.
+
+<LiveExample src='Tile.condensed.tsx'>
+  <AllExamples.TileCondensedExample client:load />
+</LiveExample>
+
+### Folder
+
+A folder tile has a slightly unique visual appearance to differentiate it from the rest of the tiles. The folder is very short compared to other tiles, therefore folders can not appear mixed in with the other tiles & must be separated like the example below. It is up to the development team to decide what metadata makes the most sense to display in the corner of the tile.
+
+<LiveExample src='Tile.folder.tsx'>
+  <AllExamples.TileFolderExample client:load />
+</LiveExample>
+
+## State
+
+### Status
+
+Tiles can have `positive`, `warning` and `negative` status.
+
+<LiveExample src='Tile.status.tsx'>
+  <AllExamples.TileStatusExample client:load />
+</LiveExample>
+
+### Disabled
+
+<LiveExample src='Tile.disabled.tsx'>
+  <AllExamples.TileDisabledExample client:load />
+</LiveExample>
+
+### Loading
+
+<LiveExample src='Tile.loading.tsx'>
+  <AllExamples.TileLoadingExample client:load />
+</LiveExample>
+
+### Selected
+
+A tile may be selected by the user to perform certain bulk tasks, such as moving them to another location, reordering them, duplicating projects, or deleting multiple at once.
+
+<LiveExample src='Tile.selected.tsx'>
+  <AllExamples.TileSelectedExample client:load />
+</LiveExample>
+
+## Usage
+
+- Users may use [FluidGrid](https://itwin.github.io/iTwinUI-layouts/#/fluid-grid) from [`itwinui-layouts`](https://github.com/iTwin/iTwinUI-layouts) package to display an array of Tiles.
+- All tiles must include a title plus additional information: an image or description text are the most common two.
+- [Folders](#folder) can not appear mixed in with the other tiles & must be separated in their own group.
+- The thumbnail area of a tile will not always display an image by default. Depending on app settings, some tiles may require the user to set that thumbnail photo themselves. If an app does not automatically generate a thumbnail image for the tile upon its creation, use a placeholder icon to populate the thumbnail area. Do not leave this area empty, as it may leave the impression that the content is unable to load.
+
+### Props
 
 <PropsTable path={frontmatter.propsPath} />

examples/Tile.actionable.tsx

@@ -7,7 +7,7 @@ import { Tile, TagContainer, Tag, Badge } from '@itwin/itwinui-react';
 import { SvgTag } from '@itwin/itwinui-icons-react';
 
 export default () => {
-  const [selected, setSelected] = React.useState(true);
+  const [selected, setSelected] = React.useState(false);
   return (
     <Tile.Wrapper isSelected={selected}>
       <Tile.Name>
@@ -25,16 +25,7 @@ export default () => {
         </Tile.BadgeContainer>
       </Tile.ThumbnailArea>
       <Tile.ContentArea>
-        <Tile.Description>
-          If you click on this stadium, it is going to be selected.
-        </Tile.Description>
-        <Tile.Metadata>
-          <SvgTag />
-          <TagContainer>
-            <Tag variant='basic'>tag 1</Tag>
-            <Tag variant='basic'>tag 2</Tag>
-          </TagContainer>
-        </Tile.Metadata>
+        <Tile.Description>This Tile is going to be selected.</Tile.Description>
       </Tile.ContentArea>
     </Tile.Wrapper>
   );

examples/Tile.anchorlink.tsx

@@ -24,15 +24,8 @@ export default () => {
       </Tile.ThumbnailArea>
       <Tile.ContentArea>
         <Tile.Description>
-          If you click on this stadium, it is going to open another page.
+          This Tile is going to open another page.
         </Tile.Description>
-        <Tile.Metadata>
-          <SvgTag />
-          <TagContainer>
-            <Tag variant='basic'>tag 1</Tag>
-            <Tag variant='basic'>tag 2</Tag>
-          </TagContainer>
-        </Tile.Metadata>
       </Tile.ContentArea>
     </Tile.Wrapper>
   );

examples/Tile.composition.tsx

@@ -0,0 +1,39 @@
+/*---------------------------------------------------------------------------------------------
+ * 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 { Tile, TagContainer, Tag } from '@itwin/itwinui-react';
+import { SvgStar, SvgInfo } from '@itwin/itwinui-icons-react';
+
+export default () => {
+  return (
+    <Tile.Wrapper>
+      <Tile.Name name='Tile name' />
+      <Tile.ThumbnailArea>
+        <Tile.ThumbnailPicture url='https://itwinplatformcdn.azureedge.net/iTwinUI/stadium.png' />
+        <Tile.TypeIndicator>
+          <Tile.IconButton label='Favorite'>
+            <SvgStar />
+          </Tile.IconButton>
+        </Tile.TypeIndicator>
+        <Tile.QuickAction>
+          <Tile.IconButton label='More info'>
+            <SvgInfo />
+          </Tile.IconButton>
+        </Tile.QuickAction>
+      </Tile.ThumbnailArea>
+      <Tile.ContentArea>
+        <Tile.Description>
+          This tile is constructed using composition API.
+        </Tile.Description>
+        <Tile.Metadata>
+          <TagContainer>
+            <Tag variant='basic'>Tag 1</Tag>
+            <Tag variant='basic'>Tag 2</Tag>
+          </TagContainer>
+        </Tile.Metadata>
+      </Tile.ContentArea>
+    </Tile.Wrapper>
+  );
+};

examples/Tile.folder.tsx

@@ -8,7 +8,7 @@ import { SvgFolder } from '@itwin/itwinui-icons-react';
 
 export default () => {
   return (
-    <Tile.Wrapper>
+    <Tile.Wrapper variant='folder'>
       <Tile.ThumbnailArea>
         <Tile.ThumbnailPicture>
           <SvgFolder />

examples/Tile.loading.tsx

@@ -9,7 +9,10 @@ import { SvgImodelHollow } from '@itwin/itwinui-icons-react';
 export default () => {
   return (
     <Tile.Wrapper isLoading={true}>
-      <Tile.Name name='Tile Name' />
+      <Tile.Name>
+        <Tile.NameIcon />
+        <Tile.NameLabel>Loading Tile</Tile.NameLabel>
+      </Tile.Name>
       <Tile.ThumbnailArea>
         <Tile.ThumbnailPicture>
           <SvgImodelHollow />

examples/Tile.props.tsx

@@ -0,0 +1,31 @@
+/*---------------------------------------------------------------------------------------------
+ * 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 { Tile, TagContainer, Tag, IconButton } from '@itwin/itwinui-react';
+import { SvgStar, SvgInfo } from '@itwin/itwinui-icons-react';
+
+export default () => {
+  return (
+    <Tile
+      name='Tile Name'
+      thumbnail='https://itwinplatformcdn.azureedge.net/iTwinUI/stadium.png'
+      leftIcon={
+        <IconButton styleType='borderless' size='small' label='Favorite'>
+          <SvgStar />
+        </IconButton>
+      }
+      rightIcon={
+        <IconButton styleType='borderless' size='small' label='More info'>
+          <SvgInfo />
+        </IconButton>
+      }
+      description='This tile is using props.'
+      metadata={[
+        <Tag variant='basic'>Tag 1</Tag>,
+        <Tag variant='basic'>Tag 2</Tag>,
+      ]}
+    />
+  );
+};

examples/Tile.quickactions.tsx

@@ -0,0 +1,30 @@
+/*---------------------------------------------------------------------------------------------
+ * 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 { Tile, Button, Badge } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <Tile.Wrapper>
+      <Tile.Name>
+        <Tile.NameIcon />
+        <Tile.NameLabel>Stadium</Tile.NameLabel>
+      </Tile.Name>
+      <Tile.ThumbnailArea>
+        <Tile.ThumbnailPicture url='https://itwinplatformcdn.azureedge.net/iTwinUI/stadium.png' />
+        <Tile.BadgeContainer>
+          <Badge backgroundColor='skyblue'>Badge</Badge>
+        </Tile.BadgeContainer>
+      </Tile.ThumbnailArea>
+      <Tile.ContentArea>
+        <Tile.Description>This tile has two quick actions.</Tile.Description>
+      </Tile.ContentArea>
+      <Tile.Buttons>
+        <Button>Action 1</Button>
+        <Button>Action 2</Button>
+      </Tile.Buttons>
+    </Tile.Wrapper>
+  );
+};

examples/Tile.selected.tsx

@@ -0,0 +1,31 @@
+/*---------------------------------------------------------------------------------------------
+ * 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 { Tile, Badge } from '@itwin/itwinui-react';
+
+export default () => {
+  const [selected, setSelected] = React.useState(true);
+  return (
+    <Tile.Wrapper isSelected={selected}>
+      <Tile.Name>
+        <Tile.NameIcon />
+        <Tile.NameLabel>
+          <Tile.Action onClick={() => setSelected((prev) => !prev)}>
+            Selected Tile
+          </Tile.Action>
+        </Tile.NameLabel>
+      </Tile.Name>
+      <Tile.ThumbnailArea>
+        <Tile.ThumbnailPicture url='https://itwinplatformcdn.azureedge.net/iTwinUI/stadium.png' />
+        <Tile.BadgeContainer>
+          <Badge backgroundColor='skyblue'>Badge</Badge>
+        </Tile.BadgeContainer>
+      </Tile.ThumbnailArea>
+      <Tile.ContentArea>
+        <Tile.Description>This tile is selected.</Tile.Description>
+      </Tile.ContentArea>
+    </Tile.Wrapper>
+  );
+};

examples/Tile.status.tsx

@@ -9,7 +9,7 @@ import { SvgImodelHollow } from '@itwin/itwinui-icons-react';
 export default () => {
   return (
     <Tile.Wrapper status='positive'>
-      <Tile.Name name='Tile Name' />
+      <Tile.Name name='Positive Tile' />
       <Tile.ThumbnailArea>
         <Tile.ThumbnailPicture>
           <SvgImodelHollow />