chore: Re-Added Select in Preview

modules/docs/mdx/12.0-UPGRADE-GUIDE.mdx

@@ -42,7 +42,6 @@ A note to the reader:
 - [Deprecations](#deprecations)
 - [Removals](#removals)
   - [InputIconContainer](#inputiconcontainer)
-  - [Select (Preview)](#select-preview)
 - [Component Updates](#component-updates)
   - [Styling API and CSS Tokens](#styling-api-and-css-tokens)
   - [Avatar](#avatar)
@@ -80,13 +79,6 @@ deprecated code is removed.
 Removals are deletions from our codebase and you can no longer consume this component. We've either
 promoted or replaced a component or utility.
 
-### Select (Preview)
-
-**PR:** [#2796](https://github.com/Workday/canvas-kit/pull/2796)
-
-We've removed the `Select` component that was in Preview. Please use the compound
-[Select component from Main](https://workday.github.io/canvas-kit/?path=/docs/components-inputs-select--basic).
-
 ### InputIconContainer
 
 **PR:** [#2838](https://github.com/Workday/canvas-kit/pull/2838)

modules/preview-react/index.ts

@@ -6,6 +6,7 @@ export * from './menu';
 export * from './pill';
 export * from './radio';
 export * from './segmented-control';
+export * from './select';
 export * from './side-panel';
 export * from './status-indicator';
 export * from './text-area';

modules/preview-react/select/LICENSE

@@ -0,0 +1,126 @@
+Apache License, Version 2.0 Apache License Version 2.0, January 2004
+
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and
+   distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the
+   copyright owner or entity authorized by the copyright owner that is granting the License. "Legal
+   Entity" shall mean the union of the acting entity and all other entities that control, are
+   controlled by, or are under common control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the direction or management of such
+   entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an
+   individual or Legal Entity exercising permissions granted by this License. "Source" form shall
+   mean the preferred form for making modifications, including but not limited to software source
+   code, documentation source, and configuration files. "Object" form shall mean any form resulting
+   from mechanical transformation or translation of a Source form, including but not limited to
+   compiled object code, generated documentation, and conversions to other media types. "Work" shall
+   mean the work of authorship, whether in Source or Object form, made available under the License,
+   as indicated by a copyright notice that is included in or attached to the work (an example is
+   provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or
+   Object form, that is based on (or derived from) the Work and for which the editorial revisions,
+   annotations, elaborations, or other modifications represent, as a whole, an original work of
+   authorship. For the purposes of this License, Derivative Works shall not include works that
+   remain separable from, or merely link (or bind by name) to the interfaces of, the Work and
+   Derivative Works thereof. "Contribution" shall mean any work of authorship, including the
+   original version of the Work and any modifications or additions to that Work or Derivative Works
+   thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright
+   owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner.
+   For the purposes of this definition, "submitted" means any form of electronic, verbal, or written
+   communication sent to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems, and issue tracking
+   systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and
+   improving the Work, but excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean
+   Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by
+   Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor
+   hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform,
+   sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor
+   hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made, use, offer to sell, sell,
+   import, and otherwise transfer the Work, where such license applies only to those patent claims
+   licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or
+   by combination of their Contribution(s) with the Work to which such Contribution(s) was
+   submitted. If You institute patent litigation against any entity (including a cross-claim or
+   counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work
+   constitutes direct or contributory patent infringement, then any patent licenses granted to You
+   under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof
+   in any medium, with or without modifications, and in Source or Object form, provided that You
+   meet the following conditions: You must give any other recipients of the Work or Derivative Works
+   a copy of this License; and You must cause any modified files to carry prominent notices stating
+   that You changed the files; and You must retain, in the Source form of any Derivative Works that
+   You distribute, all copyright, patent, trademark, and attribution notices from the Source form of
+   the Work, excluding those notices that do not pertain to any part of the Derivative Works; and If
+   the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works
+   that You distribute must include a readable copy of the attribution notices contained within such
+   NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in
+   at least one of the following places: within a NOTICE text file distributed as part of the
+   Derivative Works; within the Source form or documentation, if provided along with the Derivative
+   Works; or, within a display generated by the Derivative Works, if and wherever such third-party
+   notices normally appear. The contents of the NOTICE file are for informational purposes only and
+   do not modify the License. You may add Your own attribution notices within Derivative Works that
+   You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such
+   additional attribution notices cannot be construed as modifying the License. You may add Your own
+   copyright statement to Your modifications and may provide additional or different license terms
+   and conditions for use, reproduction, or distribution of Your modifications, or for any such
+   Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work
+   otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution
+   intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms
+   and conditions of this License, without any additional terms or conditions. Notwithstanding the
+   above, nothing herein shall supersede or modify the terms of any separate license agreement you
+   may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service
+   marks, or product names of the Licensor, except as required for reasonable and customary use in
+   describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor
+   provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT
+   WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation,
+   any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or
+   redistributing the Work and assume any risks associated with Your exercise of permissions under
+   this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including
+   negligence), contract, or otherwise, unless required by applicable law (such as deliberate and
+   grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for
+   damages, including any direct, indirect, special, incidental, or consequential damages of any
+   character arising as a result of this License or out of the use or inability to use the Work
+   (including but not limited to damages for loss of goodwill, work stoppage, computer failure or
+   malfunction, or any and all other commercial damages or losses), even if such Contributor has
+   been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works
+   thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty,
+   indemnity, or other liability obligations and/or rights consistent with this License. However, in
+   accepting such obligations, You may act only on Your own behalf and on Your sole responsibility,
+   not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each
+   Contributor harmless for any liability incurred by, or claims asserted against, such Contributor
+   by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+©2020. Workday, Inc. All rights reserved. Workday and the Workday logo are registered trademarks of
+Workday, Inc. All other brand and product names are trademarks or registered trademarks of their
+respective holders.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
+compliance with the License. You may obtain a copy of the License at
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is
+distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied. See the License for the specific language governing permissions and limitations under the
+License.

modules/preview-react/select/README.MD

@@ -0,0 +1,236 @@
+# Canvas Kit Select (with Canvas-styled Menu)
+
+<a href="https://github.com/Workday/canvas-kit/tree/master/modules/preview-react/README.md">
+  <img src="https://img.shields.io/badge/PREVIEW-beta-blueviolet" alt="PREVIEW: Beta" />
+</a> This component is in Preview because it has not been converted to a [Compound Component](../../docs/mdx/COMPOUND_COMPONENTS.mdx) yet.
+
+A Canvas-styled Select with a Canvas-styled menu. This is a
+[_controlled_](https://reactjs.org/docs/forms.html#controlled-components) component.
+
+Undocumented props (`disabled`, `name`, etc.) should behave similarly to how you would expect from a
+standard `<select>` element.
+
+The menu is rendered using a portal by way of the Canvas Kit Popper.
+
+**Note:** There is also a non-Labs Select. The non-Labs Select uses the standard browser-provided
+menu whereas the Labs Select uses a custom Canvas-styled menu.
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-preview-react
+```
+
+## Usage
+
+#### Example
+
+In this example, `options` is an array of objects. Each option contains a `label` (analagous to the
+text content of an `<option>`) and a `value` (analagous to the `value` attribute of an `<option>`).
+
+**Note:** While a base Select component is provided in this package, it is **not accessible** when
+used as is. It should be used in tandem with [`FormField`](../../../form-field/react) to be made
+fully accessible (see below).
+
+```tsx
+import * as React from 'react';
+import {Select} from '@workday/canvas-kit-preview-react/select';
+
+function Example() {
+  const options = [
+    {label: 'E-mail', value: 'email'},
+    {label: 'Phone', value: 'phone'},
+    {label: 'Fax (disabled)', value: 'fax', disabled: true},
+    {label: 'Mail', value: 'mail'},
+  ];
+
+  const [value, setValue] = React.useState('email');
+
+  const handleChange = event => {
+    setValue(event.currentTarget.value);
+  };
+
+  return <Select onChange={handleChange} options={options} value={value} />;
+}
+```
+
+#### Accessible Example
+
+```tsx
+import * as React from 'react';
+import {Select} from '@workday/canvas-kit-preview-react/select';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+
+function Example() {
+  const options = [
+    {label: 'E-mail', value: 'email'},
+    {label: 'Phone', value: 'phone'},
+    {label: 'Fax (disabled)', value: 'fax', disabled: true},
+    {label: 'Mail', value: 'mail'},
+  ];
+
+  const [value, setValue] = React.useState('email');
+
+  const handleChange = event => {
+    setValue(event.currentTarget.value);
+  };
+
+  return (
+    <FormField label="My Select Field" inputId="my-select-field">
+      <Select onChange={handleChange} options={options} value={value} />
+    </FormField>
+  );
+}
+```
+
+#### Example with Array of Strings
+
+`options` may also be formatted as an array of strings rather than an array of objects.
+
+```tsx
+import * as React from 'react';
+import {Select} from '@workday/canvas-kit-preview-react/select';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+
+function Example() {
+  const options = ['California', 'Florida', 'New York', 'Pennsylvania', 'Texas'];
+
+  const [value, setValue] = React.useState('California');
+
+  const handleChange = event => {
+    setValue(event.currentTarget.value);
+  };
+
+  return (
+    <FormField label="My Select Field" inputId="my-select-field">
+      <Select onChange={handleChange} options={options} value={value} />
+    </FormField>
+  );
+}
+```
+
+#### Example with Custom Options Data
+
+Each option in `options` may contain a `data` object with any number of key/value pairs. This `data`
+object is carried over to the `option` passed into the `renderOption` function where it may then be
+used to customize how each option is rendered.
+
+```tsx
+import * as React from 'react';
+import {Select} from '@workday/canvas-kit-preview-react/select';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {colors, typeColors} from '@workday/canvas-kit-react/tokens';
+import {
+  activityStreamIcon,
+  avatarIcon,
+  uploadCloudIcon,
+  userIcon,
+} from '@workday/canvas-system-icons-web';
+import {SystemIcon} from '@workday/canvas-kit-react/icon';
+
+function Example() {
+  const options = [
+    {value: 'Activity Stream', data: {icon: activityStreamIcon}},
+    {value: 'Avatar', data: {icon: avatarIcon}},
+    {value: 'Upload Cloud', data: {icon: uploadCloudIcon}},
+    {value: 'User', data: {icon: userIcon}},
+  ];
+
+  const renderOption = option => {
+    const iconColor = option.focused ? typeColors.inverse : colors.blackPepper100;
+    return (
+      <div style={{alignItems: 'center', display: 'flex', padding: '3px 0'}}>
+        <SystemIcon icon={option.data.icon} color={iconColor} colorHover={iconColor} />
+        <div style={{marginLeft: 5}}>{option.value}</div>
+      </div>
+    );
+  };
+
+  const [value, setValue] = React.useState('Activity Stream');
+
+  const handleChange = event => {
+    setValue(event.currentTarget.value);
+  };
+
+  return (
+    <FormField label="My Select Field" inputId="my-select-field">
+      <Select onChange={handleChange} options={options} renderOption={renderOption} value={value} />
+    </FormField>
+  );
+}
+```
+
+## Static Properties
+
+#### `ErrorType: ErrorType`
+
+```tsx
+<Select error={Select.ErrorType.Alert} />
+```
+
+## Component Props
+
+### Required
+
+#### `options: (Option | string)[]`
+
+> The options of the Select. `options` may be an array of objects or an array of strings.
+>
+> If `options` is an array of objects, each object must adhere to the `Option` interface:
+>
+> - `data: object` (optional)
+> - `disabled: boolean` (optional)
+> - `id: string` (optional, a random `id` will be assigned to the object if one isn't provided)
+> - `label: string` (optional, analagous to the text content of an `<option>`)
+> - `value: string` (required, analagous to the `value` attribute of an `<option>`)
+>
+> If `label` is omitted, the `value` will be used to render the option.
+>
+> The `data` object is carried over to the `option` passed into the `renderOption` function where it
+> may then be used to customize how each option is rendered.
+
+### Optional
+
+#### `error: ErrorType`
+
+> The type of error associated with the Select (if applicable).
+
+| Type  | Description     |
+| ----- | --------------- |
+| Error | Red outline.    |
+| Alert | Orange outline. |
+
+---
+
+#### `ref: React.Ref<HTMLButtonElement>`
+
+> A ref to be forwarded to the underlying `<button>` element (the collapsed form of the Select
+> component is rendered as a `<button>`). Use this to imperatively modify the button element.
+
+Default: `undefined`
+
+---
+
+#### `renderOption: (option: RenderableOption) => React.ReactNode`
+
+> The function called to render the content of each option.
+>
+> The `option` argument passed to the function is an object which contains the following:
+>
+> - `data: object` (data object carried over from the corresponding option originally passed into
+>   the component)
+> - `disabled: boolean`
+> - `focused: boolean` (set to `true` if the option has keyboard focus)
+> - `id: string`
+> - `label: string`
+> - `selected: boolean` (set to `true` if the option is selected)
+> - `value: string`
+>
+> If you omit the `renderOption` prop, each option will be rendered using a default `renderOption`
+> function provided by the component.
+
+---
+
+#### `value: string`
+
+> The value of the Select.