Add listbox component (#65)

* Add listbox

* Custom style for listbox focus

* Add reference snapshots

Author: fcollonval

packages/components/docs/Introduction.mdx

@@ -22,6 +22,7 @@ Here is the list of components part of the Jupyter UI toolkit:
 | `data-grid`       | [Grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/)                                 | [Stories](?path=/story/components-data-grid--documentation)       |
 | `date-field`      | [Date input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date)     | [Stories](?path=/story/components-date-field--documentation)      |
 | `divider`         | [Horizontal or vertical rule](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hr)    | [Stories](?path=/story/components-divider--documentation)         |
+| `listbox`         | [Listbox](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/)                                   | [Stories](?path=/story/components-listbox--documentation)         |
 | `menu`            | [Menu](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/)                                      | [Stories](?path=/story/components-menu--documentation)            |
 | `number-field`    | [Number input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number) | [Stories](?path=/story/components-number-field--documentation)    |
 | `progress`        | [Meter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/meter/) as line                       | [Stories](?path=/story/components-progress--documentation)        |

packages/components/docs/api-report.md

@@ -17,6 +17,7 @@ import { jpCombobox } from './combobox/index';
 import { jpDataGrid, jpDataGridCell, jpDataGridRow } from './data-grid/index';
 import { jpDateField } from './date-field/index';
 import { jpDivider } from './divider/index';
+import { jpListbox } from './listbox/index';
 import { jpMenu } from './menu/index';
 import { jpMenuItem } from './menu-item/index';
 import { jpNumberField } from './number-field/index';
@@ -58,6 +59,7 @@ import type { Combobox } from './combobox/index';
 import type { DataGrid, DataGridCell, DataGridRow } from './data-grid/index';
 import type { DateField } from './date-field/index';
 import type { Divider } from './divider/index';
+import type { ListboxElement } from './listbox/index';
 import type { Menu } from './menu/index';
 import type { MenuItem } from './menu-item/index';
 import type { NumberField } from './number-field/index';
@@ -100,6 +102,7 @@ export {
   jpDataGridRow,
   jpDateField,
   jpDivider,
+  jpListbox,
   jpMenu,
   jpMenuItem,
   jpNumberField,
@@ -149,6 +152,7 @@ export const allComponents = {
   jpDataGridRow,
   jpDateField,
   jpDivider,
+  jpListbox,
   jpMenu,
   jpMenuItem,
   jpNumberField,

packages/components/src/custom-elements.ts

@@ -24,6 +24,7 @@ export * from './combobox/index';
 export * from './date-field/index';
 export * from './data-grid/index';
 export * from './divider/index';
+export * from './listbox/index';
 export * from './menu/index';
 export * from './menu-item/index';
 export * from './number-field/index';

packages/components/src/index.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import {
+  ListboxElement,
+  listboxTemplate as template
+} from '@microsoft/fast-foundation';
+import { listboxStyles as styles } from './listbox.styles';
+
+/**
+ * The Jupyter listbox Custom Element. Implements, {@link @microsoft/fast-foundation#Listbox}
+ * {@link @microsoft/fast-foundation#ListboxTemplate}
+ *
+ *
+ * @public
+ * @remarks
+ * HTML Element: \<jp-listbox\>
+ *
+ */
+export const jpListbox = ListboxElement.compose({
+  baseName: 'listbox',
+  template,
+  styles
+});
+
+/**
+ * Base class for ListBox
+ * @public
+ */
+export { ListboxElement };
+
+export { styles as listboxStyles };

packages/components/src/listbox/index.ts

@@ -0,0 +1,47 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import type { StoryFn, Meta, StoryObj } from '@storybook/html';
+import { setTheme } from '../utilities/storybook';
+
+export default {
+  title: 'Components/Listbox',
+  argTypes: {
+    isDisabled: { control: 'boolean' },
+    multiple: { control: 'boolean' }
+  },
+  parameters: {
+    actions: {
+      disabled: true
+    }
+  }
+} as Meta;
+
+const Template: StoryFn = (args, context): string => {
+  const {
+    globals: { backgrounds, accent },
+    parameters
+  } = context;
+  setTheme(accent, parameters.backgrounds, backgrounds);
+
+  return `<jp-listbox
+    ${args.isDisabled ? 'disabled' : ''}
+    ${args.multiple ? 'multiple' : ''}
+  >
+    <jp-option value="1">Option 1</jp-option>
+    <jp-option value="2">Option 2</jp-option>
+    <jp-option value="3">Option 3</jp-option>
+  </jp-listbox>`;
+};
+
+export const Default: StoryObj = { render: Template.bind({}) };
+Default.args = {
+  isDisabled: false,
+  multiple: false
+};
+
+export const WithDisabled: StoryObj = { render: Template.bind({}) };
+WithDisabled.args = {
+  ...Default.args,
+  isDisabled: true
+};

packages/components/src/listbox/listbox.stories.ts

@@ -0,0 +1,108 @@
+// Copyright (c) Jupyter Development Team.
+// Copyright (c) Microsoft Corporation.
+// Distributed under the terms of the Modified BSD License.
+
+import type { ElementStyles } from '@microsoft/fast-element';
+import { css } from '@microsoft/fast-element';
+import type { FoundationElementTemplate } from '@microsoft/fast-foundation';
+import {
+  disabledCursor,
+  display,
+  focusVisible,
+  forcedColorsStylesheetBehavior,
+  ListboxElement,
+  ListboxOption
+} from '@microsoft/fast-foundation';
+import { SystemColors } from '@microsoft/fast-web-utilities';
+import {
+  controlCornerRadius,
+  designUnit,
+  disabledOpacity,
+  fillColor,
+  focusStrokeOuter,
+  focusStrokeWidth,
+  neutralStrokeRest,
+  strokeWidth
+} from '@microsoft/fast-components';
+import { heightNumber } from '../styles/size';
+
+/**
+ * Styles for Listbox
+ * @public
+ */
+export const listboxStyles: FoundationElementTemplate<ElementStyles> = (
+  context,
+  definition
+) => {
+  const ListboxOptionTag = context.tagFor(ListboxOption);
+  const hostContext =
+    context.name === context.tagFor(ListboxElement) ? '' : '.listbox';
+
+  // The expression interpolations present in this block cause Prettier to generate
+  // various formatting bugs.
+  // prettier-ignore
+  return css`
+        ${!hostContext ? display('inline-flex') : ''}
+
+        :host ${hostContext} {
+            background: ${fillColor};
+            border: calc(${strokeWidth} * 1px) solid ${neutralStrokeRest};
+            border-radius: calc(${controlCornerRadius} * 1px);
+            box-sizing: border-box;
+            flex-direction: column;
+            padding: calc(${designUnit} * 1px) 0;
+        }
+
+        ${!hostContext ? css`
+            :host(:${focusVisible}:not([disabled])) {
+                outline: none;
+            }
+
+            :host(:focus-within:not([disabled])) {
+                border-color: ${focusStrokeOuter};
+                box-shadow: 0 0 0
+                    calc((${focusStrokeWidth} - ${strokeWidth}) * 1px)
+                    ${focusStrokeOuter} inset;
+            }
+
+            :host([disabled]) ::slotted(*) {
+                cursor: ${disabledCursor};
+                opacity: ${disabledOpacity};
+                pointer-events: none;
+            }
+        ` : ''}
+
+        ${hostContext || ':host([size])'} {
+            max-height: calc(
+                (var(--size) * ${heightNumber} + (${designUnit} * ${strokeWidth} * 2)) * 1px
+            );
+            overflow-y: auto;
+        }
+
+        :host([size="0"]) ${hostContext} {
+            max-height: none;
+        }
+    `.withBehaviors(
+        forcedColorsStylesheetBehavior(
+            css`
+                :host(:not([multiple]):${focusVisible}) ::slotted(${ListboxOptionTag}[aria-selected="true"]),
+                :host([multiple]:${focusVisible}) ::slotted(${ListboxOptionTag}[aria-checked="true"]) {
+                    border-color: ${SystemColors.ButtonText};
+                    box-shadow: 0 0 0 calc(${focusStrokeWidth} * 1px) inset ${SystemColors.HighlightText};
+                }
+
+                :host(:not([multiple]):${focusVisible}) ::slotted(${ListboxOptionTag}[aria-selected="true"]) {
+                    background: ${SystemColors.Highlight};
+                    color: ${SystemColors.HighlightText};
+                    fill: currentcolor;
+                }
+
+                ::slotted(${ListboxOptionTag}[aria-selected="true"]:not([aria-checked="true"])) {
+                    background: ${SystemColors.Highlight};
+                    border-color: ${SystemColors.HighlightText};
+                    color: ${SystemColors.HighlightText};
+                }
+            `
+        )
+    );
+};

packages/components/src/listbox/listbox.styles.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { test, expect } from '@playwright/test';
+
+test('Default', async ({ page }) => {
+  await page.goto('/iframe.html?id=components-listbox--default');
+
+  expect(await page.locator('jp-listbox').screenshot()).toMatchSnapshot(
+    'listbox-default.png'
+  );
+});
+
+test('Disabled', async ({ page }) => {
+  await page.goto('/iframe.html?id=components-listbox--with-disabled');
+
+  expect(await page.locator('jp-listbox').screenshot()).toMatchSnapshot(
+    'listbox-disabled.png'
+  );
+});

packages/components/src/listbox/listbox.test.ts

@@ -16,6 +16,7 @@ import {
   DataGrid,
   DateField,
   Divider,
+  Listbox,
   Menu,
   MenuItem,
   NumberField,
@@ -146,6 +147,9 @@ const plugin: JupyterFrontEndPlugin<void> = {
     const select = widget.node.querySelector('jp-select');
     select?.addEventListener('change', changeListener('Select'));
 
+    const listbox = widget.node.querySelector('jp-listbox');
+    listbox?.addEventListener('change', changeListener('Listbox'));
+
     const combobox = widget.node.querySelector('jp-combobox');
     combobox?.addEventListener('change', changeListener('Combobox'));
     combobox?.addEventListener('input', changeConsoleListener('Combobox'));
@@ -282,6 +286,14 @@ function Artwork(props: { dataRef: React.Ref<WebDataGrid> }): JSX.Element {
             <Option>Option Label #3</Option>
           </Select>
         </div>
+        <div className="jp-FlexColumn">
+          <label>Listbox</label>
+          <Listbox onChange={onChange}>
+            <Option>Option Label #1</Option>
+            <Option>Option Label #2</Option>
+            <Option>Option Label #3</Option>
+          </Listbox>
+        </div>
         <div className="jp-FlexColumn">
           <label>Combobox</label>
           <Combobox onChange={onChange} onInput={onChangeConsole}>
@@ -477,6 +489,16 @@ function createNode(): HTMLElement {
           <jp-option>Option Label #3</jp-option>
         </jp-select>
       </div>
+      <div class="jp-FlexColumn">
+        <label>
+          Listbox
+        </label>
+        <jp-listbox>
+          <jp-option>Option Label #1</jp-option>
+          <jp-option>Option Label #2</jp-option>
+          <jp-option>Option Label #3</jp-option>
+        </jp-listbox>
+      </div>
       <div class="jp-FlexColumn">
         <label>
           Combobox

packages/components/tests-out/listbox/listbox.test.js-snapshots/listbox-default-chromium-linux.png

@@ -16,6 +16,7 @@ export * from './combobox';
 export * from './data-grid';
 export * from './date-field';
 export * from './divider';
+export * from './listbox';
 export * from './menu';
 export * from './menu-item';
 export * from './number-field';

packages/components/tests-out/listbox/listbox.test.js-snapshots/listbox-default-firefox-linux.png

@@ -0,0 +1,19 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { provideJupyterDesignSystem, jpListbox } from '@jupyter/web-components';
+import { provideReactWrapper } from '@microsoft/fast-react-wrapper';
+import React from 'react';
+
+const { wrap } = provideReactWrapper(React, provideJupyterDesignSystem());
+
+export const Listbox: React.DetailedHTMLFactory<
+  React.HTMLAttributes<HTMLElement> & {
+    disabled?: boolean;
+    multiple?: boolean;
+    size?: number;
+  },
+  HTMLElement
+> = wrap(jpListbox()) as any;
+// @ts-expect-error unknown property
+Listbox.displayName = 'Jupyter.Listbox';