Expose width and height of nimble-dialog & add tokens

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,25 @@
 import type { StoryFn, Meta } from '@storybook/html';
-import { html } from '@microsoft/fast-element';
-import { createFixedThemeStory } from '../../utilities/tests/storybook';
-import { sharedMatrixParameters } from '../../utilities/tests/matrix';
+import { html, ViewTemplate } from '@microsoft/fast-element';
+import {
+    createFixedThemeStory,
+    createStory
+} from '../../utilities/tests/storybook';
+import {
+    createMatrix,
+    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',
@@ -28,6 +43,36 @@ const component = html`
     </${dialogTag}>
 `;
 
+const dialogSizingTestCase = (
+    [widthLabel, widthStyle]: [string, string],
+    [heightLabel, heightStyle]: [string, string],
+    [maxHeightLabel, maxHeightStyle]: [string, string]
+): ViewTemplate => html`
+    <p class="spacer">${() => widthLabel}; ${() => heightLabel} ${() => maxHeightLabel}</p>
+    <style>
+        ${dialogTag}::part(control) {
+            ${() => widthStyle};
+            ${() => heightStyle};
+            ${() => maxHeightStyle};
+        }
+
+        .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 +105,53 @@ export const dialogDarkThemeBlackBackground: StoryFn = createFixedThemeStory(
 );
 
 dialogDarkThemeBlackBackground.play = playFunction;
+
+export const smallDialogSizing: StoryFn = createStory(html`
+    ${createMatrix(dialogSizingTestCase, [
+        [
+            [
+                'Width Small Dialog',
+                `width: var(${dialogSmallWidth.cssCustomProperty})`
+            ]
+        ],
+        [
+            [
+                'Height Small Dialog',
+                `width: var(${dialogSmallHeight.cssCustomProperty})`
+            ]
+        ],
+        [
+            [
+                'Max Height Small Dialog',
+                `width: var(${dialogSmallMaxHeight.cssCustomProperty})`
+            ]
+        ]
+    ])}
+`);
+
+smallDialogSizing.play = playFunction;
+
+export const largeDialogSizing: StoryFn = createStory(html`
+    ${createMatrix(dialogSizingTestCase, [
+        [
+            [
+                'Width Large Dialog',
+                `width: var(${dialogLargeWidth.cssCustomProperty})`
+            ]
+        ],
+        [
+            [
+                'Height Large Dialog',
+                `width: var(${dialogLargeHeight.cssCustomProperty})`
+            ]
+        ],
+        [
+            [
+                'Max Height Large Dialog',
+                `width: var(${dialogLargeMaxHeight.cssCustomProperty})`
+            ]
+        ]
+    ])}
+`);
+
+largeDialogSizing.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,