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,9 @@ import {
     smallPadding,
     subtitleFont,
     subtitleFontColor,
-    elevation3BoxShadow
+    elevation3BoxShadow,
+    dialogSmallWidth,
+    dialogSmallMaxHeight
 } from '../theme-provider/design-tokens';
 import {
     modalBackdropColorThemeColorStatic,
@@ -32,8 +34,8 @@ export const styles = css`
         border: none;
         box-shadow: ${elevation3BoxShadow};
         padding: 0px;
-        width: 400px;
-        max-height: 600px;
+        width: ${dialogSmallWidth};
+        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="dialog"
             @cancel="${(x, c) => x.cancelHandler(c.event)}"
             aria-labelledby="header"
         >

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

@@ -1,10 +1,26 @@
 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 {
+    cssPropertyFromTokenName,
+    tokenNames
+} from '../../theme-provider/design-token-names';
+import {
+    dialogLargeHeight,
+    dialogLargeWidth,
+    dialogSmallMaxHeight,
+    dialogSmallWidth
+} from '../../theme-provider/design-tokens';
 
 const metadata: Meta = {
     title: 'Tests/Dialog',
@@ -28,6 +44,33 @@ const component = html`
     </${dialogTag}>
 `;
 
+const dialogSizingTestCase = (
+    [widthLabel, widthStyle]: [string, string],
+    [heightLabel, heightStyle]: [string, string],
+    [maxHeightLabel, maxHeightStyle]: [string, string]
+): ViewTemplate => html`
+    <p style="font: var(${cssPropertyFromTokenName(
+        tokenNames.bodyFont
+    )}); margin-bottom: 0px;">${() => widthLabel}; ${() => heightLabel} ${() => maxHeightLabel}</p>
+    <style>
+        ${dialogTag}::part(dialog) {
+            ${() => widthStyle};
+            ${() => heightStyle};
+            ${() => maxHeightStyle};
+        }
+    </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 +103,48 @@ export const dialogDarkThemeBlackBackground: StoryFn = createFixedThemeStory(
 );
 
 dialogDarkThemeBlackBackground.play = playFunction;
+
+export const smallDialogSizing: StoryFn = createStory(html`
+    ${createMatrix(dialogSizingTestCase, [
+        [
+            [
+                `Width ${dialogSmallWidth.getValueFor(document.body)}`,
+                `width: ${dialogSmallWidth.getValueFor(document.body)}`
+            ]
+        ],
+        [['Height fit-content', 'height: fit-content']],
+        [
+            [
+                `Max height ${dialogSmallMaxHeight.getValueFor(document.body)}`,
+                `max-height: ${dialogSmallMaxHeight.getValueFor(document.body)}`
+            ]
+        ]
+    ])}
+`);
+
+smallDialogSizing.play = playFunction;
+
+export const largeDialogSizing: StoryFn = createStory(html`
+    ${createMatrix(dialogSizingTestCase, [
+        [
+            [
+                `Width ${dialogLargeWidth.getValueFor(document.body)}`,
+                `width: ${dialogLargeWidth.getValueFor(document.body)}`
+            ]
+        ],
+        [
+            [
+                `Height ${dialogLargeHeight.getValueFor(document.body)}`,
+                `height: ${dialogLargeHeight.getValueFor(document.body)}`
+            ]
+        ],
+        [
+            [
+                `Max height ${dialogLargeHeight.getValueFor(document.body)}`,
+                `max-height: ${dialogLargeHeight.getValueFor(document.body)}`
+            ]
+        ]
+    ])}
+`);
+
+largeDialogSizing.play = playFunction;

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

@@ -3,10 +3,20 @@ 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,
+    dialogLargeWidth,
+    dialogSmallMaxHeight,
+    dialogSmallWidth
+} from '../../theme-provider/design-tokens';
+import {
+    scssPropertyFromTokenName,
+    tokenNames
+} from '../../theme-provider/design-token-names';
 
 interface DialogArgs {
     title: string;
@@ -16,6 +26,9 @@ interface DialogArgs {
     includeFooterButtons: boolean;
     preventDismiss: boolean;
     content: ExampleContentType;
+    width: DialogSizeOptions;
+    height: DialogSizeOptions;
+    maxHeight: DialogSizeOptions;
     show: undefined;
     close: undefined;
     dialogRef: Dialog<string>;
@@ -49,6 +62,51 @@ const content = {
     [ExampleContentType.longContent]: longContent
 } as const;
 
+const widthDescription = `
+Width of a nimble dialog.
+The default width that the dialog has is given by ${scssPropertyFromTokenName(
+        tokenNames.dialogSmallWidth
+    )}.
+
+The width can be overriden by setting a different value for the width attribute. For large dialogs, there is a nimble token available: ${scssPropertyFromTokenName(
+        tokenNames.dialogLargeWidth
+    )}
+`;
+
+const heightDescription = `
+Height of a nimble dialog.
+
+The height can be overriden by setting a different value for the height attribute. For large dialogs, there is a nimble token available: ${scssPropertyFromTokenName(
+        tokenNames.dialogLargeHeight
+    )}
+`;
+
+const maxHeightDescription = `
+Maximum height of a nimble dialog.
+The default maximum height that the dialog has is given by ${scssPropertyFromTokenName(
+        tokenNames.dialogSmallMaxHeight
+    )}.
+
+The maximum height can be overriden by setting a different value for the maximum height attribute.
+`;
+
+const widths = {
+    [DialogSizeOptions.default]: dialogSmallWidth.getValueFor(document.body),
+    [DialogSizeOptions.large]: dialogLargeWidth.getValueFor(document.body)
+} as const;
+
+const heights = {
+    [DialogSizeOptions.default]: 'fit-content',
+    [DialogSizeOptions.large]: dialogLargeHeight.getValueFor(document.body)
+} as const;
+
+const maxHeights = {
+    [DialogSizeOptions.default]: dialogSmallMaxHeight.getValueFor(
+        document.body
+    ),
+    [DialogSizeOptions.large]: dialogLargeHeight.getValueFor(document.body)
+} as const;
+
 const metadata: Meta<DialogArgs> = {
     title: 'Components/Dialog',
     tags: ['autodocs'],
@@ -65,6 +123,13 @@ const metadata: Meta<DialogArgs> = {
             .first-button {
                 margin-right: auto;
             }
+            ${dialogTag}::part(dialog) {
+                ${x => `
+                    width:${widths[x.width]};
+                    height:${heights[x.height]};
+                    max-height:${maxHeights[x.maxHeight]};
+                `}
+            }
         </style>
         <${dialogTag}
             ${ref('dialogRef')}
@@ -154,6 +219,49 @@ const metadata: Meta<DialogArgs> = {
                 }
             }
         },
+        width: {
+            description: widthDescription,
+            options: [DialogSizeOptions.default, DialogSizeOptions.large],
+            control: {
+                type: 'select',
+                labels: {
+                    [DialogSizeOptions.default]: `Default (${dialogSmallWidth.getValueFor(
+                        document.body
+                    )})`,
+                    [DialogSizeOptions.large]: `Large (${dialogLargeWidth.getValueFor(
+                        document.body
+                    )})`
+                }
+            }
+        },
+        height: {
+            description: heightDescription,
+            options: [DialogSizeOptions.default, DialogSizeOptions.large],
+            control: {
+                type: 'select',
+                labels: {
+                    [DialogSizeOptions.default]: 'Default (fit-content)',
+                    [DialogSizeOptions.large]: `Large (${dialogLargeHeight.getValueFor(
+                        document.body
+                    )})`
+                }
+            }
+        },
+        maxHeight: {
+            description: maxHeightDescription,
+            options: [DialogSizeOptions.default, DialogSizeOptions.large],
+            control: {
+                type: 'select',
+                labels: {
+                    [DialogSizeOptions.default]: `Default (${dialogSmallMaxHeight.getValueFor(
+                        document.body
+                    )})`,
+                    [DialogSizeOptions.large]: `Large (${dialogLargeHeight.getValueFor(
+                        document.body
+                    )})`
+                }
+            }
+        },
         show: {
             name: 'show()',
             description:
@@ -178,6 +286,9 @@ const metadata: Meta<DialogArgs> = {
         includeFooterButtons: true,
         preventDismiss: false,
         content: ExampleContentType.shortContent,
+        width: DialogSizeOptions.default,
+        height: DialogSizeOptions.default,
+        maxHeight: DialogSizeOptions.default,
         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 = {
+    default: 'Default',
+    large: 'Large'
+} as const;
+export type DialogSizeOptions =
+    (typeof DialogSizeOptions)[keyof typeof DialogSizeOptions];

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

@@ -61,6 +61,12 @@ 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.',
+    dialogSmallMaxHeight:
+        'Standard maximum height for small dialogs like a confirmation dialog.',
+    dialogLargeWidth: 'Standard width for large dialogs.',
+    dialogLargeHeight: 'Standard 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,10 @@ export const tokenNames: { readonly [key in TokenName]: string } = {
     iconSize: 'icon-size',
     groupHeaderTextTransform: 'group-header-text-transform',
     drawerWidth: 'drawer-width',
+    dialogSmallWidth: 'dialog-small-width',
+    dialogSmallMaxHeight: 'dialog-small-max-height',
+    dialogLargeWidth: 'dialog-large-width',
+    dialogLargeHeight: 'dialog-large-height',
     bannerGapSize: 'banner-gap-size',
     spinnerSmallHeight: 'spinner-small-height',
     spinnerMediumHeight: 'spinner-medium-height',

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

@@ -306,6 +306,18 @@ 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 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 bannerGapSize = DesignToken.create<string>(
     styleNameFromTokenName(tokenNames.bannerGapSize)
 ).withDefault('1px');