Expose width and height of nimble-dialog & add tokens (#1553)

# Pull Request

## 🤨 Rationale

<!---
Provide some background and a description of your work.
What problem does this change solve?

Include links to issues, work items, or other discussions.
-->

#1117

## 👩‍💻 Implementation

<!---
Describe how the change addresses the problem. Consider factors such as
complexity, alternative solutions, performance impact, etc.

Consider listing files with important changes or comment on them
directly in the pull request.
-->

- Performed the tasks that are enumerated in the issue linked above.
- Create 2 tokens for the existing (small) dialog: width & max-height
- Create 2 tokens for the large dialog: width & height
- Have the small dialog as the default (width & max-height of small
dialog; height set to `fit-content`, this was the default height that
was applied to the dialog until now)
- Added storybook documentation.

## 🧪 Testing

<!---
Detail the testing done to ensure this submission meets requirements. 

Include automated/manual test additions or modifications, testing done
on a local build, private CI run results, and additional testing not
covered by automatic pull request validation. If any functionality is
not covered by automated testing, provide justification.
-->
Manually thorugh the storybook tests & matrix tests in chromatic. The
sizes are configurable in the storybook similarly to how the width is
configurable for the nimble drawer. For the matrix tests, I added 2
stories: one for the small dialog and one for the large dialog:
https://www.chromatic.com/build?appId=60e89457a987cf003efc0a5b&number=7776


## ✅ Checklist

<!--- Review the list and put an x in the boxes that apply or ~~strike
through~~ around items that don't (along with an explanation). -->

- [X] I have updated the project documentation to reflect my changes or
determined no changes are needed.

change/@ni-nimble-components-1e4a5579-af4c-4960-8cfc-32d8417d1a34.json

@@ -0,0 +1,7 @@
+{
+ "type": "minor",
+ "comment": "Expose width and height of nimble-dialog & add tokens",
+ "packageName": "@ni/nimble-components",
+ "email": "[email protected]",
+ "dependentChangeType": "patch"
+}

packages/nimble-components/src/dialog/styles.ts

@@ -12,7 +12,10 @@ import {
  smallPadding,
  subtitleFont,
  subtitleFontColor,
- elevation3BoxShadow
+ elevation3BoxShadow,
+ dialogSmallWidth,
+ dialogSmallHeight,
+ dialogSmallMaxHeight
 } from '../theme-provider/design-tokens';
 import {
  modalBackdropColorThemeColorStatic,
@@ -32,8 +35,9 @@ export const styles = css`
  border: none;
  box-shadow: ${elevation3BoxShadow};
  padding: 0px;
- width: 400px;
- max-height: 600px;
+ width: ${dialogSmallWidth};
+ height: ${dialogSmallHeight};
+ max-height: ${dialogSmallMaxHeight};
  }
 
  dialog[open] {

packages/nimble-components/src/dialog/template.ts

@@ -6,6 +6,7 @@ export const template = html<Dialog>`
  <dialog
  ${ref('dialogElement')}
  role="dialog"
+ part="control"
  @cancel="${(x, c) => x.cancelHandler(c.event)}"
  aria-labelledby="header"
  >

packages/nimble-components/src/dialog/tests/dialog-matrix.stories.ts

@@ -1,10 +1,19 @@
 import type { StoryFn, Meta } from '@storybook/html';
-import { html } from '@microsoft/fast-element';
+import { html, ViewTemplate } from '@microsoft/fast-element';
 import { createFixedThemeStory } from '../../utilities/tests/storybook';
 import { sharedMatrixParameters } from '../../utilities/tests/matrix';
 import { backgroundStates } from '../../utilities/tests/states';
 import { dialogTag } from '..';
 import { buttonTag } from '../../button';
+import {
+ bodyFont,
+ dialogLargeHeight,
+ dialogLargeMaxHeight,
+ dialogLargeWidth,
+ dialogSmallHeight,
+ dialogSmallMaxHeight,
+ dialogSmallWidth
+} from '../../theme-provider/design-tokens';
 
 const metadata: Meta = {
  title: 'Tests/Dialog',
@@ -15,6 +24,12 @@ const metadata: Meta = {
 
 export default metadata;
 
+const sizeStates = [
+ `width: var(${dialogSmallWidth.cssCustomProperty}); height: var(${dialogSmallHeight.cssCustomProperty}); max-height: var(${dialogSmallMaxHeight.cssCustomProperty});`,
+ `width: var(${dialogLargeWidth.cssCustomProperty}); height: var(${dialogLargeHeight.cssCustomProperty}); max-height: var(${dialogLargeMaxHeight.cssCustomProperty});`
+] as const;
+type SizeState = (typeof sizeStates)[number];
+
 const component = html`
  <${dialogTag}>
  <span slot="title">This is my dialog's title. It is pretty long.</span>
@@ -28,6 +43,30 @@ const component = html`
  </${dialogTag}>
 `;
 
+const dialogSizingTestCase = (size: SizeState): ViewTemplate => html`
+ <p class="spacer">${() => size};</p>
+ <style>
+ ${dialogTag}::part(control) {
+ ${() => size};
+ }
+
+ .spacer {
+ font: var(${bodyFont.cssCustomProperty});
+ padding-bottom: 1000px;
+ }
+ </style>
+ <${dialogTag}>
+ <span slot="title">This is my dialog's title. It is pretty long.</span>
+ <span slot="subtitle">The dialog has a subtitle here.</span>
+ <div>Here is the first piece of content in the dialog</div>
+ <div>
+ Here is another piece of content in the dialog. It is a bit longer.
+ </div>
+ <${buttonTag} slot="footer">Cancel</${buttonTag}>
+ <${buttonTag} slot="footer">OK</${buttonTag}>
+ </${dialogTag}>
+`;
+
 const [
  lightThemeWhiteBackground,
  colorThemeDarkGreenBackground,
@@ -60,3 +99,17 @@ export const dialogDarkThemeBlackBackground: StoryFn = createFixedThemeStory(
 );
 
 dialogDarkThemeBlackBackground.play = playFunction;
+
+export const dialogSmallSize: StoryFn = createFixedThemeStory(
+ dialogSizingTestCase(sizeStates[0]),
+ lightThemeWhiteBackground
+);
+
+dialogSmallSize.play = playFunction;
+
+export const dialogLargeSize: StoryFn = createFixedThemeStory(
+ dialogSizingTestCase(sizeStates[1]),
+ lightThemeWhiteBackground
+);
+
+dialogLargeSize.play = playFunction;

packages/nimble-components/src/dialog/tests/dialog.mdx

@@ -0,0 +1,46 @@
+import {
+ DocsStory,
+ Meta,
+ Controls,
+ Stories,
+ Title,
+ Description
+} from '@storybook/blocks';
+import * as dialogStories from './dialog.stories';
+
+<Meta of={dialogStories} />
+
+<Title of={dialogStories} />
+<Description of={dialogStories} />
+
+<DocsStory of={dialogStories.dialog} expanded={false} />
+<Controls of={dialogStories.dialog} />
+
+# Usage Docs
+
+<br />
+
+## Sizing
+
+The dialog size can be customized by modyfing the width, height and max-height properties of `nimble-dialog::part(control)`.
+
+By default, the dialog is sized to be small and growable. This should be used for small dialogs like a confirmation dialog.
+This is equivalent of using the following style configuration:
+
+```scss
+nimble-dialog::part(control) {
+ width: $ni-nimble-dialog-small-width;
+ height: $ni-nimble-dialog-small-height;
+ max-height: $ni-nimble-dialog-small-max-height;
+}
+```
+
+For larger dialogs, for example a wizard-like dialog, the following style configuration should be used:
+
+```scss
+nimble-dialog::part(control) {
+ width: $ni-nimble-dialog-large-width;
+ height: $ni-nimble-dialog-large-height;
+ max-height: $ni-nimble-dialog-large-max-height;
+}
+```

packages/nimble-components/src/dialog/tests/dialog.stories.ts

@@ -3,10 +3,18 @@ import type { Meta, StoryObj } from '@storybook/html';
 import { createUserSelectedThemeStory } from '../../utilities/tests/storybook';
 import { Dialog, dialogTag, UserDismissed } from '..';
 import { TextField, textFieldTag } from '../../text-field';
-import { ExampleContentType } from './types';
+import { DialogSizeOptions, ExampleContentType } from './types';
 import { loremIpsum } from '../../utilities/tests/lorem-ipsum';
 import { buttonTag } from '../../button';
 import { checkboxTag } from '../../checkbox';
+import {
+ dialogLargeHeight,
+ dialogLargeMaxHeight,
+ dialogLargeWidth,
+ dialogSmallHeight,
+ dialogSmallMaxHeight,
+ dialogSmallWidth
+} from '../../theme-provider/design-tokens';
 
 interface DialogArgs {
  title: string;
@@ -16,6 +24,7 @@ interface DialogArgs {
  includeFooterButtons: boolean;
  preventDismiss: boolean;
  content: ExampleContentType;
+ size: DialogSizeOptions;
  show: undefined;
  close: undefined;
  dialogRef: Dialog<string>;
@@ -49,9 +58,29 @@ const content = {
  [ExampleContentType.longContent]: longContent
 } as const;
 
+const sizeDescription = `
+Size of a nimble dialog.
+
+See the Sizing section of the Usage Docs for information on controlling the size of the dialog.
+`;
+
+const widths = {
+ [DialogSizeOptions.smallGrowable]: `var(${dialogSmallWidth.cssCustomProperty})`,
+ [DialogSizeOptions.largeFixed]: `var(${dialogLargeWidth.cssCustomProperty})`
+} as const;
+
+const heights = {
+ [DialogSizeOptions.smallGrowable]: `var(${dialogSmallHeight.cssCustomProperty})`,
+ [DialogSizeOptions.largeFixed]: `var(${dialogLargeHeight.cssCustomProperty})`
+} as const;
+
+const maxHeights = {
+ [DialogSizeOptions.smallGrowable]: `var(${dialogSmallMaxHeight.cssCustomProperty})`,
+ [DialogSizeOptions.largeFixed]: `var(${dialogLargeMaxHeight.cssCustomProperty})`
+} as const;
+
 const metadata: Meta<DialogArgs> = {
  title: 'Components/Dialog',
- tags: ['autodocs'],
  parameters: {
  docs: {
  description: {
@@ -65,6 +94,13 @@ const metadata: Meta<DialogArgs> = {
  .first-button {
  margin-right: auto;
  }
+ ${dialogTag}::part(control) {
+ ${x => `
+ width:${widths[x.size]};
+ height:${heights[x.size]};
+ max-height:${maxHeights[x.size]};
+ `}
+ }
  </style>
  <${dialogTag}
  ${ref('dialogRef')}
@@ -154,6 +190,20 @@ const metadata: Meta<DialogArgs> = {
  }
  }
  },
+ size: {
+ description: sizeDescription,
+ options: [
+ DialogSizeOptions.smallGrowable,
+ DialogSizeOptions.largeFixed
+ ],
+ control: {
+ type: 'radio',
+ labels: {
+ [DialogSizeOptions.smallGrowable]: 'Small growable',
+ [DialogSizeOptions.largeFixed]: 'Large fixed'
+ }
+ }
+ },
  show: {
  name: 'show()',
  description:
@@ -178,6 +228,7 @@ const metadata: Meta<DialogArgs> = {
  includeFooterButtons: true,
  preventDismiss: false,
  content: ExampleContentType.shortContent,
+ size: DialogSizeOptions.smallGrowable,
  openAndHandleResult: (dialogRef, textFieldRef) => {
  void (async () => {
  const reason = await dialogRef.show();

packages/nimble-components/src/dialog/tests/types.ts

@@ -4,3 +4,10 @@ export const ExampleContentType = {
 } as const;
 export type ExampleContentType =
  (typeof ExampleContentType)[keyof typeof ExampleContentType];
+
+export const DialogSizeOptions = {
+ smallGrowable: 'Small growable',
+ largeFixed: 'Large growable'
+} as const;
+export type DialogSizeOptions =
+ (typeof DialogSizeOptions)[keyof typeof DialogSizeOptions];

packages/nimble-components/src/theme-provider/design-token-comments.ts

@@ -61,6 +61,15 @@ export const comments: { readonly [key in TokenName]: string | null } = {
  iconSize: 'Standard layout height for all icons',
  groupHeaderTextTransform: 'CSS text-transform string to use for headers',
  drawerWidth: 'TODO: delete when able',
+ dialogSmallWidth:
+ 'Standard width for small dialogs like a confirmation dialog.',
+ dialogSmallHeight:
+ 'Standard height for small dialogs like a confirmation dialog.',
+ dialogSmallMaxHeight:
+ 'Standard maximum height for small dialogs like a confirmation dialog.',
+ dialogLargeWidth: 'Standard width for large dialogs.',
+ dialogLargeHeight: 'Standard height for large dialogs.',
+ dialogLargeMaxHeight: 'Standard maximum height for large dialogs.',
  bannerGapSize: 'Space between stacked banners',
  spinnerSmallHeight: 'Small height (16px) for a spinner component',
  spinnerMediumHeight: 'Medium height (32px) for a spinner component',

packages/nimble-components/src/theme-provider/design-token-names.ts

@@ -47,6 +47,12 @@ export const tokenNames: { readonly [key in TokenName]: string } = {
  iconSize: 'icon-size',
  groupHeaderTextTransform: 'group-header-text-transform',
  drawerWidth: 'drawer-width',
+ dialogSmallWidth: 'dialog-small-width',
+ dialogSmallHeight: 'dialog-small-height',
+ dialogSmallMaxHeight: 'dialog-small-max-height',
+ dialogLargeWidth: 'dialog-large-width',
+ dialogLargeHeight: 'dialog-large-height',
+ dialogLargeMaxHeight: 'dialog-large-max-height',
  bannerGapSize: 'banner-gap-size',
  spinnerSmallHeight: 'spinner-small-height',
  spinnerMediumHeight: 'spinner-medium-height',
@@ -249,6 +255,7 @@ const tokenSuffixes = [
  'TextTransform',
  'FontFamily',
  'BoxShadow',
+ 'MaxHeight',
  'Font',
  'Size',
  'Width',

packages/nimble-components/src/theme-provider/design-tokens.ts

@@ -306,6 +306,24 @@ export const iconSize = DesignToken.create<string>(
 export const drawerWidth = DesignToken.create<string>(
  styleNameFromTokenName(tokenNames.drawerWidth)
 ).withDefault('784px');
+export const dialogSmallWidth = DesignToken.create<string>(
+ styleNameFromTokenName(tokenNames.dialogSmallWidth)
+).withDefault('400px');
+export const dialogSmallHeight = DesignToken.create<string>(
+ styleNameFromTokenName(tokenNames.dialogSmallHeight)
+).withDefault('fit-content');
+export const dialogSmallMaxHeight = DesignToken.create<string>(
+ styleNameFromTokenName(tokenNames.dialogSmallMaxHeight)
+).withDefault('600px');
+export const dialogLargeWidth = DesignToken.create<string>(
+ styleNameFromTokenName(tokenNames.dialogLargeWidth)
+).withDefault('1024px');
+export const dialogLargeHeight = DesignToken.create<string>(
+ styleNameFromTokenName(tokenNames.dialogLargeHeight)
+).withDefault('680px');
+export const dialogLargeMaxHeight = DesignToken.create<string>(
+ styleNameFromTokenName(tokenNames.dialogLargeMaxHeight)
+).withDefault('680px');
 export const bannerGapSize = DesignToken.create<string>(
  styleNameFromTokenName(tokenNames.bannerGapSize)
 ).withDefault('1px');

packages/nimble-components/src/theme-provider/tests/tokens.stories.ts

@@ -109,6 +109,7 @@ const tokenTemplates: {
  TextTransform: stringValueTemplate,
  FontFamily: stringValueTemplate,
  BoxShadow: stringValueTemplate,
+ MaxHeight: stringValueTemplate,
  Font: fontTemplate,
  Size: stringValueTemplate,
  Width: stringValueTemplate,