@instructure/ui-simple-select 11.7.2-snapshot-48 → 11.7.2-snapshot-49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-simple-select",
-  "version": "11.7.2-snapshot-48",
+  "version": "11.7.2-snapshot-49",
   "description": "A component for standard select element behavior.",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -15,22 +15,22 @@
   "license": "MIT",
   "dependencies": {
     "@babel/runtime": "^7.27.6",
-    "@instructure/console": "11.7.2-snapshot-48",
-    "@instructure/shared-types": "11.7.2-snapshot-48",
-    "@instructure/ui-form-field": "11.7.2-snapshot-48",
-    "@instructure/ui-position": "11.7.2-snapshot-48",
-    "@instructure/ui-react-utils": "11.7.2-snapshot-48",
-    "@instructure/ui-select": "11.7.2-snapshot-48"
+    "@instructure/console": "11.7.2-snapshot-49",
+    "@instructure/shared-types": "11.7.2-snapshot-49",
+    "@instructure/ui-position": "11.7.2-snapshot-49",
+    "@instructure/ui-react-utils": "11.7.2-snapshot-49",
+    "@instructure/ui-form-field": "11.7.2-snapshot-49",
+    "@instructure/ui-select": "11.7.2-snapshot-49"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "15.0.7",
     "@testing-library/user-event": "^14.6.1",
     "vitest": "^3.2.2",
-    "@instructure/ui-icons": "11.7.2-snapshot-48",
-    "@instructure/ui-color-utils": "11.7.2-snapshot-48",
-    "@instructure/ui-utils": "11.7.2-snapshot-48",
-    "@instructure/ui-babel-preset": "11.7.2-snapshot-48"
+    "@instructure/ui-babel-preset": "11.7.2-snapshot-49",
+    "@instructure/ui-color-utils": "11.7.2-snapshot-49",
+    "@instructure/ui-icons": "11.7.2-snapshot-49",
+    "@instructure/ui-utils": "11.7.2-snapshot-49"
   },
   "peerDependencies": {
     "react": ">=18 <=19"
@@ -60,18 +60,18 @@
       "default": "./es/exports/a.js"
     },
     "./v11_7": {
-      "src": "./src/exports/a.ts",
-      "types": "./types/exports/a.d.ts",
-      "import": "./es/exports/a.js",
-      "require": "./lib/exports/a.js",
-      "default": "./es/exports/a.js"
+      "src": "./src/exports/b.ts",
+      "types": "./types/exports/b.d.ts",
+      "import": "./es/exports/b.js",
+      "require": "./lib/exports/b.js",
+      "default": "./es/exports/b.js"
     },
     "./latest": {
-      "src": "./src/exports/a.ts",
-      "types": "./types/exports/a.d.ts",
-      "import": "./es/exports/a.js",
-      "require": "./lib/exports/a.js",
-      "default": "./es/exports/a.js"
+      "src": "./src/exports/b.ts",
+      "types": "./types/exports/b.d.ts",
+      "import": "./es/exports/b.js",
+      "require": "./lib/exports/b.js",
+      "default": "./es/exports/b.js"
     }
   },
   "scripts": {

package/src/SimpleSelect/v2/Group/index.tsx

@@ -0,0 +1,51 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Component } from 'react'
+
+import type { SimpleSelectGroupProps } from './props'
+import { allowedProps } from './props'
+
+/**
+---
+parent: SimpleSelect
+id: SimpleSelect.Group
+---
+**/
+class Group extends Component<SimpleSelectGroupProps> {
+  static readonly componentId = 'SimpleSelect.Group'
+
+  static allowedProps = allowedProps
+  static defaultProps = {}
+
+  /* istanbul ignore next */
+  render() {
+    // this component is only used for prop validation. Select.Group children
+    // are parsed in Select and rendered as Options components
+    return null
+  }
+}
+
+export default Group
+export { Group }

package/src/SimpleSelect/v2/Group/props.ts

@@ -0,0 +1,49 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import React from 'react'
+
+import type { OtherHTMLAttributes } from '@instructure/shared-types'
+
+type SimpleSelectGroupOwnProps = {
+  /**
+   * The label associated with the group options.
+   */
+  renderLabel: React.ReactNode | (() => React.ReactNode)
+  /**
+   * Children of type `<SimpleSelect.Option />` that will be considered part of the group.
+   */
+  children?: React.ReactNode // TODO: ChildrenPropTypes.oneOf([Option])
+}
+
+type PropKeys = keyof SimpleSelectGroupOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type SimpleSelectGroupProps = SimpleSelectGroupOwnProps &
+  OtherHTMLAttributes<SimpleSelectGroupOwnProps>
+const allowedProps: AllowedPropKeys = ['renderLabel', 'children']
+
+export type { SimpleSelectGroupProps }
+export { allowedProps }

package/src/SimpleSelect/v2/Option/index.tsx

@@ -0,0 +1,52 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Component } from 'react'
+import type { SimpleSelectOptionProps } from './props'
+import { allowedProps } from './props'
+
+/**
+---
+parent: SimpleSelect
+id: SimpleSelect.Option
+---
+**/
+class Option extends Component<SimpleSelectOptionProps> {
+  static readonly componentId = 'SimpleSelect.Option'
+
+  static allowedProps = allowedProps
+  static defaultProps = {
+    isDisabled: false
+  }
+
+  /* istanbul ignore next */
+  render() {
+    // this component is only used for prop validation. SimpleSelect.Option children
+    // are parsed in Select and rendered as Options.Item components
+    return null
+  }
+}
+
+export default Option
+export { Option }

package/src/SimpleSelect/v2/Option/props.ts

@@ -0,0 +1,83 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import React from 'react'
+import type { OtherHTMLAttributes } from '@instructure/shared-types'
+import { Renderable } from '@instructure/shared-types'
+
+type OptionProps = {
+  id: SimpleSelectOptionOwnProps['id']
+  isDisabled?: SimpleSelectOptionOwnProps['isDisabled']
+  isSelected?: boolean
+  isHighlighted?: boolean
+  children?: React.ReactNode
+}
+
+type RenderSimpleSelectOptionLabel = Renderable<OptionProps>
+
+type SimpleSelectOptionOwnProps = {
+  /**
+   * The id for the option. **Must be globally unique**, it will be translated
+   * to an `id` prop in the DOM.
+   */
+  id: string
+  /**
+   * The value for the option.
+   */
+  value: string | number
+  /**
+   * Whether or not this option is disabled.
+   */
+  isDisabled?: boolean
+  /**
+   * Content to display as the option label.
+   */
+  children?: string
+  /**
+   * Content to display before the option label, such as an icon.
+   */
+  renderBeforeLabel?: RenderSimpleSelectOptionLabel
+  /**
+   * Content to display after the option label, such as an icon.
+   */
+  renderAfterLabel?: RenderSimpleSelectOptionLabel
+}
+
+type PropKeys = keyof SimpleSelectOptionOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type SimpleSelectOptionProps = SimpleSelectOptionOwnProps &
+  OtherHTMLAttributes<SimpleSelectOptionOwnProps>
+const allowedProps: AllowedPropKeys = [
+  'id',
+  'value',
+  'isDisabled',
+  'renderBeforeLabel',
+  'renderAfterLabel',
+  'children'
+]
+
+export type { SimpleSelectOptionProps, RenderSimpleSelectOptionLabel }
+export { allowedProps }

package/src/SimpleSelect/v2/README.md

@@ -0,0 +1,157 @@
+---
+describes: SimpleSelect
+---
+
+`SimpleSelect` is a higher level abstraction of [Select](Select) that closely parallels the functionality of standard HTML `<select>` elements. It does not support autocomplete behavior and is much less configurable than [Select](Select). However, because it is more opinionated, `SimpleSelect` can be implemented with very little boilerplate.
+
+> Note: The `id` prop on options must be globally unique, it will be translated to an `id` prop
+> in the DOM.
+
+### Uncontrolled
+
+For the most basic implementations, `SimpleSelect` can be uncontrolled. If desired, the `defaultValue` prop can be used to set the initial selection.
+
+```javascript
+---
+type: example
+---
+<SimpleSelect renderLabel="Uncontrolled Select">
+  <SimpleSelect.Option id="foo" value="foo"
+                       renderBeforeLabel={(props) => {
+                         console.log(props)
+                         return <CheckInstUIIcon />
+                       }}>
+    Foo
+  </SimpleSelect.Option>
+  <SimpleSelect.Option id="bar" value="bar">
+    Bar
+  </SimpleSelect.Option>
+  <SimpleSelect.Option id="baz" value="baz">
+    Baz
+  </SimpleSelect.Option>
+</SimpleSelect>
+```
+
+### Controlled
+
+To use `SimpleSelect` controlled, simply provide the `value` prop the string that corresponds to the selected option's `value` prop. The `onChange` callback can be used to update the value stored in state.
+
+```js
+---
+type: example
+---
+const Example = ({ options }) => {
+  const [value, setValue] = useState('Alaska')
+
+  const handleSelect = (e, { id, value }) => {
+    setValue(value)
+  }
+
+  return (
+    <SimpleSelect
+      renderLabel="Controlled Select"
+      assistiveText="Use arrow keys to navigate options."
+      value={value}
+      onChange={handleSelect}
+    >
+      {options.map((opt, index) => (
+        <SimpleSelect.Option key={index} id={`opt-${index}`} value={opt}>
+          {opt}
+        </SimpleSelect.Option>
+      ))}
+    </SimpleSelect>
+  )
+}
+
+render(
+  <Example
+    options={[
+      'Alaska',
+      'American Samoa',
+      'Arizona',
+      'Arkansas',
+      'California',
+      'Colorado',
+      'Connecticut',
+      'Delaware',
+      'District Of Columbia',
+      'Federated States Of Micronesia',
+      'Florida',
+      'Georgia',
+      'Guam',
+      'Hawaii',
+      'Idaho',
+      'Illinois'
+    ]}
+  />
+)
+```
+
+### Groups
+
+Like a HTML `<select>` element, `SimpleSelect` supports option groups. `SimpleSelect.Group` only requires the `renderLabel` prop be provided.
+
+```javascript
+---
+type: example
+---
+<SimpleSelect renderLabel="Select with Groups">
+  <SimpleSelect.Group renderLabel="Group one" key="grp1">
+    <SimpleSelect.Option id="opt1" value="option-1">
+      Option one
+    </SimpleSelect.Option>
+  </SimpleSelect.Group>
+  <SimpleSelect.Group renderLabel="Group two" key="grp2">
+    <SimpleSelect.Option id="opt2" value="option-2">
+      Option two
+    </SimpleSelect.Option>
+    <SimpleSelect.Option id="opt3" value="option-3">
+      Option three
+    </SimpleSelect.Option>
+    <SimpleSelect.Option id="opt4" value="option-4">
+      Option four
+    </SimpleSelect.Option>
+  </SimpleSelect.Group>
+</SimpleSelect>
+```
+
+### Icons
+
+To display icons (or other elements) before or after an option, pass it via the `renderBeforeLabel` and `renderAfterLabel` prop to `SimpleSelect.Option`. You can pass a function as well, which will have a `props` parameter, so you can access the properties of that `SimpleSelect.Option` (e.g. if it is currently `isHighlighted`). The available props are: `[ id, isDisabled, isSelected, isHighlighted, children ]` (same as for `Select.Option`).
+
+```javascript
+---
+type: example
+---
+<SimpleSelect renderLabel="Option Icons">
+  <SimpleSelect.Option
+    id="text"
+    value="text"
+    renderBeforeLabel={'XY'}
+  >
+    Text
+  </SimpleSelect.Option>
+  <SimpleSelect.Option
+    id="icon"
+    value="icon"
+    renderBeforeLabel={<CheckInstUIIcon />}
+  >
+    Icon
+  </SimpleSelect.Option>
+  <SimpleSelect.Option
+    id="coloredIcon"
+    value="coloredIcon"
+    renderBeforeLabel={(props) => {
+      let color = 'infoColor'
+      if (props.isHighlighted) color = 'baseColor'
+      if (props.isSelected) color = 'inverseColor'
+      if (props.isDisabled) color = 'disabledBaseColor'
+      return <VerifiedInstUIIcon color={color} />
+    }}
+  >
+    Colored Icon
+  </SimpleSelect.Option>
+</SimpleSelect>
+```
+
+> Note: This component uses a native `input` field to render the selected value. When it's included in a native HTML `form`, the text value will be sent to the backend instead of anything specified in the `value` field of the `SimpleSelect.Option`-s. We do not recommend to use this component this way, rather write your own code that collects information and sends it to the backend.