Merge branch 'main' into r/private-css-vars

LICENSE.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright © 2021-2024 Bentley Systems, Incorporated. All rights reserved.
+Copyright © 2021-2025 Bentley Systems, Incorporated. All rights reserved.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

apps/website/src/components/LeftSidebarContent.astro

@@ -7,7 +7,10 @@ const currentPage = Astro.url.pathname.endsWith('/')
   : Astro.url.pathname;
 
 const introPages = await getCollection('docs', ({ data: { group } }) => group === 'intro');
-const mainComponents = await getCollection('docs', ({ data: { group } }) => group === undefined);
+const mainComponents = await getCollection(
+  'docs',
+  ({ data: { group, title } }) => group === undefined && title !== 'Typography',
+);
 const utilityComponents = await getCollection(
   'docs',
   ({ data: { group } }) => group === 'utilities',

apps/website/src/content/docs/anchor.mdx

@@ -61,7 +61,7 @@ If you do ultimately decide based on your research that it is beneficial to open
 
 By default, an anchor is only underlined when hovered, with a few exceptions:
 
-1. Anchors inside a [`Text`](https://itwinui.bentley.com/docs/typography#text) component are underlined by default.
+1. Anchors inside a [`Text`](/docs/text) component are underlined by default.
 2. All anchors are underlined by default when using a high-contrast theme.
 
 For [better accessibility](https://adrianroselli.com/2016/06/on-link-underlines.html#recommendation), it is recommended to explicitly make the anchor underlined in all themes, even when used outside `Text`. This can be achieved using the `underline` prop.

apps/website/src/content/docs/combobox.mdx

@@ -81,7 +81,7 @@ If you expect the combobox to have a very long list of items, you can set `enabl
 
 ### Labels
 
-You can use a [Label](typography#label) component alongside the combobox to add a label. Note that passing the same id to the label as `htmlFor` and to the combobox as `id` in `inputProps` will allow users to open the combobox by clicking on the label.
+You can use a [Label](/docs/label) component alongside the combobox to add a label. Note that passing the same id to the label as `htmlFor` and to the combobox as `id` in `inputProps` will allow users to open the combobox by clicking on the label.
 
 <LiveExample src='ComboBox.label.jsx'>
   <AllExamples.ComboBoxLabelExample client:load />

apps/website/src/content/docs/inputgrid.mdx

@@ -15,7 +15,7 @@ InputGrid is a layout component that allows to group label, form field and statu
 
 You can add any form field (eg. Select, ComboBox or InputWithDecorations).
 
-We recommend [Label](typography#label) and [StatusMessage](statusmessage) components with this layout.
+We recommend [Label](/docs/label) and [StatusMessage](statusmessage) components with this layout.
 
 <LiveExample src='InputGrid.select.jsx'>
   <AllExamples.InputGridSelectExample client:load />

apps/website/src/content/docs/label.mdx

@@ -0,0 +1,38 @@
+---
+title: Label
+description: Label components can be used to associate text with form inputs.
+thumbnail: #TODO
+---
+
+<p>{frontmatter.description}</p>
+
+## Usage
+
+`Label` corresponds to an HTML `<label>` and can be linked to an `Input` by matching `Label`'s `htmlFor` with `Input`'s `id` for better accessibility, ensuring assistive technologies correctly identify their relationship.
+
+<LiveExample src='Label.main.jsx'>
+  <AllExamples.LabelMainExample client:load />
+</LiveExample>
+
+### Required
+
+To make the form field required, you can pass the `required` prop. This also adds the `*` next to the label.
+
+<LiveExample src='Label.required.jsx'>
+  <AllExamples.LabelRequiredExample client:load />
+</LiveExample>
+
+### Display style
+
+There are two available display styles:
+
+- `"block"` (default): places the label and the other fields on separate lines without adding any extra spacing.
+- `"inline"`: displays the label inline with other elements by adding a right margin to it.
+
+<LiveExample src='Label.displayStyles.jsx'>
+  <AllExamples.LabelDisplayStylesExample client:load />
+</LiveExample>
+
+## Props
+
+<PropsTable path='@itwin/itwinui-react/esm/core/Label/Label.d.ts' />

apps/website/src/content/docs/text.mdx

@@ -0,0 +1,65 @@
+---
+title: Text
+description: Text components offer various text formatting options for applications.
+thumbnail: Typography
+---
+
+<p>{frontmatter.description}</p>
+
+## Usage
+
+`Text` is a [polymorphic](#polymorphic-only-semantics-and-not-size) typography component that can be used to render any kind of text as any kind of element.
+
+<LiveExample src='Text.main.jsx'>
+  <AllExamples.TextMainExample client:load />
+</LiveExample>
+
+By default, the `Text` component renders a `<div>` element with the regular `"body"` size. The visuals of this component are completely separate from its semantics, which helps ensure proper [heading structure](https://www.w3.org/WAI/tutorials/page-structure/headings/).
+
+- **Visuals**: The `variant` prop can be used to customize the the size (e.g. `variant="subheading"`).
+- **Semantics**: The polymorphic `as` prop can be used to render a different element (e.g. `as="h2"`).
+
+### Variant (Only size and not semantics)
+
+The `variant` prop can be used to determine the size of the text. The available variants are (from largest to smallest):
+
+1. `"headline"`.
+2. `"title"`.
+3. `"subheading"`.
+4. `"leading"`.
+5. `"body"` (default).
+6. `"smaller"`.
+
+<LiveExample src='Text.variant.jsx'>
+  <AllExamples.TextVariantExample client:load />
+</LiveExample>
+
+Please note that the `variant` prop only affects the visual size and is completely decoupled from the semantics, which can be controlled using the `as` prop (see below).
+
+### Polymorphic (Only semantics and not size)
+
+The `Text` component supports the polymorphic `as` prop, which can be used to change the underlying HTML element. This is useful when you want to render the text as a specific heading level while maintaining a desired size.
+
+<LiveExample src='Text.polymorphic.jsx' truncate={false}>
+  <AllExamples.TextPolymorphicExample client:load />
+</LiveExample>
+
+### Muted
+
+To achieve a muted or desaturated text effect, the `isMuted` prop can be passed into the component. Muted text helps differentiating less important information as well as enhancing the overall readability.
+
+<LiveExample src='Text.muted.jsx' truncate={false}>
+  <AllExamples.TextMutedExample client:load />
+</LiveExample>
+
+### Skeleton
+
+To indicate that content is loading and will be available soon, you can use the `isSkeleton` prop along with the `variant` prop. This will display a placeholder for any text that is still loading. If no `variant` is specified, the skeleton will default to the size of `"body"` text.
+
+<LiveExample src='Text.skeleton.jsx'>
+  <AllExamples.TextSkeletonExample client:load />
+</LiveExample>
+
+## Props
+
+<PropsTable path='@itwin/itwinui-react/esm/core/Typography/Text.d.ts' />

apps/website/src/content/docs/tree.mdx

@@ -65,7 +65,7 @@ The `getNode` function then needs to map the user `data` to a `NodeData`. The pr
 const getNode = React.useCallback(
   (node) => {
     return {
-      /*…*/
+      /* … */
       subNodes: node.subItems,
       hasSubNodes: node.subItems.length > 0,
     };
@@ -93,7 +93,7 @@ The `isExpanded` flag which indicates whether the node is expanded to display it
 const getNode = React.useCallback(
   (node) => {
     return {
-      /*…*/
+      /* … */
       isExpanded: expandedNodes[node.id],
     };
   },

apps/website/src/content/docs/typography.mdx

@@ -1,31 +1,14 @@
 ---
 title: Typography
-description:
+description: Typography components provide consistency in text styling across the application.
 thumbnail: Typography
 ---
 
 <p>{frontmatter.description}</p>
 
-<Placeholder componentPageName='text--basic' />
+## Components
 
-## Text
+The documentation for typography components has been split into the following pages:
 
-<LiveExample src='Text.main.jsx' truncate={false}>
-  <AllExamples.TextMainExample client:load />
-</LiveExample>
-
-### Props
-
-<PropsTable path='@itwin/itwinui-react/esm/core/Typography/Text.d.ts' />
-
-## Label
-
-<Placeholder componentPageName='label--basic' />
-
-<LiveExample src='Label.main.jsx' truncate={false}>
-  <AllExamples.LabelMainExample client:load />
-</LiveExample>
-
-### Props
-
-<PropsTable path='@itwin/itwinui-react/esm/core/Label/Label.d.ts' />
+- [Label](/docs/label)
+- [Text](/docs/text)

apps/website/src/pages/docs/components.astro

@@ -4,7 +4,10 @@ import Layout from './_layout.astro';
 import Card from '~/components/Card.astro';
 
 const componentPages = (
-  await getCollection('docs', ({ data: { group } }) => group !== 'intro')
+  await getCollection(
+    'docs',
+    ({ data: { group, title } }) => group !== 'intro' && title !== 'Typography',
+  )
 ).map(({ slug, data }) => ({ url: `/docs/${slug}`, ...data }));
 ---
 

examples/Label.displayStyles.css

@@ -0,0 +1,6 @@
+.demo-container {
+  display: flex;
+  flex-direction: column;
+  gap: var(--iui-size-xs);
+  width: 300px;
+}

examples/Label.displayStyles.jsx

@@ -0,0 +1,21 @@
+/*---------------------------------------------------------------------------------------------
+ * 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 { InputGrid, Input, Label, LabeledSelect } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <div className='demo-container'>
+      <InputGrid>
+        <Label displayStyle='block'>Block label</Label>
+        <Input />
+      </InputGrid>
+      <InputGrid labelPlacement='inline'>
+        <Label displayStyle='inline'>Inline label</Label>
+        <Input />
+      </InputGrid>
+    </div>
+  );
+};

examples/Label.main.css

@@ -0,0 +1,3 @@
+.demo-container {
+  width: 300px;
+}

examples/Label.main.jsx

@@ -3,8 +3,13 @@
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
-import { Label } from '@itwin/itwinui-react';
+import { Flex, Input, Label } from '@itwin/itwinui-react';
 
 export default () => {
-  return <Label>This is label.</Label>;
+  return (
+    <>
+      <Label htmlFor='text-input'>Name:</Label>
+      <Input id='text-input' placeholder='Enter name' />
+    </>
+  );
 };

examples/Label.required.jsx

@@ -0,0 +1,17 @@
+/*---------------------------------------------------------------------------------------------
+ * 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 { Input, Label } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <div className='demo-container'>
+      <Label htmlFor='text-input' required>
+        Name:
+      </Label>
+      <Input id='text-input' placeholder='Enter name' />
+    </div>
+  );
+};

examples/Text.main.jsx

@@ -6,5 +6,5 @@ import * as React from 'react';
 import { Text } from '@itwin/itwinui-react';
 
 export default () => {
-  return <Text variant='body'>This is text</Text>;
+  return <Text>This is a text</Text>;
 };

examples/Text.muted.jsx

@@ -0,0 +1,15 @@
+/*---------------------------------------------------------------------------------------------
+ * 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 { Flex, Text } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <Flex flexDirection='column'>
+      <Text>This is a regular text</Text>
+      <Text isMuted>This is a muted text</Text>
+    </Flex>
+  );
+};

examples/Text.polymorphic.jsx

@@ -0,0 +1,14 @@
+/*---------------------------------------------------------------------------------------------
+ * 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 { Text } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <Text variant='subheading' as='h1'>
+      This is a subheading rendered as an h1.
+    </Text>
+  );
+};

examples/Text.skeleton.jsx

@@ -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 { Flex, Text } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <Flex flexDirection='column'>
+      <Text isSkeleton variant='headline'>
+        This is a skeleton text
+      </Text>
+      <Text isSkeleton variant='title'>
+        This is a skeleton text
+      </Text>
+      <Text isSkeleton variant='subheading'>
+        This is a skeleton text
+      </Text>
+      <Text isSkeleton variant='leading'>
+        This is a skeleton text
+      </Text>
+      <Text isSkeleton>This is a skeleton text</Text>
+      <Text isSkeleton variant='small'>
+        This is a skeleton text
+      </Text>
+    </Flex>
+  );
+};

examples/Text.variant.jsx

@@ -0,0 +1,19 @@
+/*---------------------------------------------------------------------------------------------
+ * 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 { Flex, Text } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <Flex flexDirection='column'>
+      <Text variant='headline'>This is a headline</Text>
+      <Text variant='title'>This is a title</Text>
+      <Text variant='subheading'>This is a subheading</Text>
+      <Text variant='leading'>This is a leading</Text>
+      <Text>This is a body</Text>
+      <Text variant='small'>This is a small text</Text>
+    </Flex>
+  );
+};

examples/Tree.virtualization.css

@@ -1,5 +1,4 @@
 .demo-tree {
-  width: min(100%, 260px);
-  height: 100%;
+  width: 260px;
   overflow: auto;
 }

examples/Tree.virtualization.jsx

@@ -57,6 +57,7 @@ export default () => {
   return (
     <Tree
       className='demo-tree'
+      style={{ height: '400px' }}
       data={data}
       getNode={getNode}
       enableVirtualization