Add a title slot to the Card component (#1638)

# Pull Request

Add a title slot for the `nimble-card` component.

See #296 and the [`nimble-card`
spec](https://github.com/ni/nimble/blob/main/packages/nimble-components/src/card/specs/README.md)
for more information.

## 🤨 Rationale

The `title` slot in the `nimble-card` component will make it easy for
clients to add a title with the correct styling and to enforce
consistency across usages.

The style itself is still a placeholder. We'll apply styles from a
visual design in a future PR, before releasing the Routines UI with the
card component.

## 👩‍💻 Implementation

- Add a `slot` with `name="title"` to the `nimble-card` template
- Add a style to apply a title font to the title slot (placeholder, may
require additional styling from visual design)
- For accessibility, put a `section` at the root of the component
template
- Use `display: contents` to allow the `host` display settings to apply
directly to the slotted content.
- Add a title to the matrix stories
- Add a configurable title to the storybook page.
- Modeled after the `nimble-banner` with similar description text for
the title.

## 🧪 Testing

Updated storybook and matrix tests:


![image](https://github.com/ni/nimble/assets/35350751/9a7e5bd4-dd3e-4a48-b527-de924e2391b6)

![image](https://github.com/ni/nimble/assets/35350751/4606f41e-d499-435c-a5e3-0947ff2238c7)

## ✅ Checklist

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

change/@ni-nimble-components-604c9a3b-c917-4978-b425-167277e5097e.json

@@ -0,0 +1,7 @@
+{
+ "type": "patch",
+ "comment": "Add a title slot to the nimble-card",
+ "packageName": "@ni/nimble-components",
+ "email": "[email protected]",
+ "dependentChangeType": "patch"
+}

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

@@ -6,7 +6,9 @@ import {
  borderColor,
  borderWidth,
  sectionBackgroundColor,
- standardPadding
+ standardPadding,
+ titleFont,
+ titleFontColor
 } from '../theme-provider/design-tokens';
 
 export const styles = css`
@@ -21,4 +23,13 @@ export const styles = css`
  color: ${bodyFontColor};
  background-color: ${sectionBackgroundColor};
  }
+
+ section {
+ display: contents;
+ }
+
+ ::slotted([slot='title']) {
+ font: ${titleFont};
+ color: ${titleFontColor};
+ }
 `;

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

@@ -1,4 +1,9 @@
 import { html } from '@microsoft/fast-element';
 import type { Card } from '.';
 
-export const template = html<Card>`<slot></slot>`;
+export const template = html<Card>`
+ <section aria-labelledby="title-slot">
+ <slot name="title" id="title-slot"></slot>
+ <slot></slot>
+ </section>
+`;

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

@@ -25,6 +25,7 @@ export default metadata;
 
 const component = (): ViewTemplate => html`
  <${cardTag}>
+ <span slot="title">Title</span>
  <${numberFieldTag}>Numeric field 1</${numberFieldTag}>
  <${numberFieldTag}>Numeric field 2</${numberFieldTag}>
  <${selectTag}>

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

@@ -2,17 +2,22 @@ import { html } from '@microsoft/fast-element';
 import type { Meta, StoryObj } from '@storybook/html';
 import {
  createUserSelectedThemeStory,
+ disableStorybookZoomTransform,
  incubatingWarning
 } from '../../utilities/tests/storybook';
 import { listOptionTag } from '../../list-option';
 import { numberFieldTag } from '../../number-field';
 import { selectTag } from '../../select';
 import { cardTag } from '..';
 
+interface CardArgs {
+ title: string;
+}
+
 const overviewText = `The \`nimble-card\` is a container that is designed to contain arbitrary content that is specified by a client
 application. The \`nimble-card\` is intended for grouping related content.`;
 
-const metadata: Meta = {
+const metadata: Meta<CardArgs> = {
  title: 'Incubating/Card',
  tags: ['autodocs'],
  parameters: {
@@ -24,11 +29,13 @@ const metadata: Meta = {
  actions: {}
  },
  render: createUserSelectedThemeStory(html`
+ ${disableStorybookZoomTransform}
  ${incubatingWarning({
  componentName: 'card',
  statusLink: 'https://github.com/ni/nimble/issues/296'
  })}
  <${cardTag}>
+ <span slot="title">${x => x.title}</span>
  <${numberFieldTag}>Numeric field 1</${numberFieldTag}>
  <${numberFieldTag}>Numeric field 2</${numberFieldTag}>
  <${selectTag}>
@@ -37,9 +44,18 @@ const metadata: Meta = {
  <${listOptionTag} value="3">Option 3</${listOptionTag}>
  </${selectTag}>
  </${cardTag}>
- `)
+ `),
+ argTypes: {
+ title: {
+ description:
+ 'Text displayed as a title inside the card. Cards should **always include a title**. The title is used to provide an accessible name to assistive technologies.<br><br>Provide the title in an element targeted to the `title` slot.'
+ }
+ },
+ args: {
+ title: 'Title text'
+ }
 };
 
 export default metadata;
 
-export const card: StoryObj = {};
+export const card: StoryObj<CardArgs> = {};

packages/nimble-components/src/utilities/tests/storybook.ts

@@ -163,8 +163,8 @@ WARNING - The ${config.componentName} is still incubating. It is not recommended
 See the <a href="${config.statusLink}">incubating component status</a>.
 </div>`;
 
-// On Firefox, on the Docs page, there is a div with a scale(1) transform that causes the dropdown
-// to be confined to the div. We remove the transform to allow the dropdown to escape the div, but
+// On the Docs page, there is a div with a scale(1) transform that causes the dropdown to be
+// confined to the div. We remove the transform to allow the dropdown to escape the div, but
 // that also breaks zooming behavior, so we remove the zoom buttons on the docs page.
 export const disableStorybookZoomTransform = `
 <style class="code-hide">