@instructure/ui-text-area 11.6.0 → 11.6.1-snapshot-129

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-text-area",
-  "version": "11.6.0",
+  "version": "11.6.1-snapshot-129",
   "description": "A styled HTML text area component",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -15,25 +15,25 @@
   "license": "MIT",
   "dependencies": {
     "@babel/runtime": "^7.27.6",
-    "@instructure/emotion": "11.6.0",
-    "@instructure/debounce": "11.6.0",
-    "@instructure/shared-types": "11.6.0",
-    "@instructure/ui-a11y-utils": "11.6.0",
-    "@instructure/ui-dom-utils": "11.6.0",
-    "@instructure/ui-react-utils": "11.6.0",
-    "@instructure/ui-utils": "11.6.0",
-    "@instructure/uid": "11.6.0",
-    "@instructure/ui-form-field": "11.6.0"
+    "@instructure/debounce": "11.6.1-snapshot-129",
+    "@instructure/shared-types": "11.6.1-snapshot-129",
+    "@instructure/emotion": "11.6.1-snapshot-129",
+    "@instructure/ui-dom-utils": "11.6.1-snapshot-129",
+    "@instructure/ui-a11y-utils": "11.6.1-snapshot-129",
+    "@instructure/ui-form-field": "11.6.1-snapshot-129",
+    "@instructure/ui-react-utils": "11.6.1-snapshot-129",
+    "@instructure/uid": "11.6.1-snapshot-129",
+    "@instructure/ui-utils": "11.6.1-snapshot-129"
   },
   "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-babel-preset": "11.6.0",
-    "@instructure/ui-axe-check": "11.6.0",
-    "@instructure/ui-color-utils": "11.6.0",
-    "@instructure/ui-themes": "11.6.0"
+    "@instructure/ui-axe-check": "11.6.1-snapshot-129",
+    "@instructure/ui-color-utils": "11.6.1-snapshot-129",
+    "@instructure/ui-themes": "11.6.1-snapshot-129",
+    "@instructure/ui-babel-preset": "11.6.1-snapshot-129"
   },
   "peerDependencies": {
     "react": ">=18 <=19"
@@ -43,17 +43,39 @@
   },
   "sideEffects": false,
   "exports": {
-    ".": {
-      "types": "./types/index.d.ts",
-      "import": "./es/index.js",
-      "require": "./lib/index.js",
-      "default": "./es/index.js"
-    },
     "./lib/*": "./lib/*",
     "./es/*": "./es/*",
     "./types/*": "./types/*",
     "./package.json": "./package.json",
-    "./src/*": "./src/*"
+    "./src/*": "./src/*",
+    ".": {
+      "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"
+    },
+    "./v11_6": {
+      "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"
+    },
+    "./v11_7": {
+      "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/b.ts",
+      "types": "./types/exports/b.d.ts",
+      "import": "./es/exports/b.js",
+      "require": "./lib/exports/b.js",
+      "default": "./es/exports/b.js"
+    }
   },
   "scripts": {
     "lint": "ui-scripts lint",

package/src/TextArea/{index.tsx → v1/index.tsx}

@@ -23,7 +23,7 @@
  */
 
 import { Fragment, Component } from 'react'
-import { FormField } from '@instructure/ui-form-field'
+import { FormField } from '@instructure/ui-form-field/v11_6'
 import {
   addEventListener,
   isActiveElement,
@@ -33,7 +33,7 @@ import {
 import type { RequestAnimationFrameType } from '@instructure/ui-dom-utils'
 import { debounce } from '@instructure/debounce'
 import type { Debounced } from '@instructure/debounce'
-import { withStyle } from '@instructure/emotion'
+import { withStyleLegacy as withStyle } from '@instructure/emotion'
 import { px } from '@instructure/ui-utils'
 import {
   omitProps,

package/src/TextArea/{props.ts → v1/props.ts}

@@ -29,7 +29,7 @@ import type {
   TextAreaTheme,
   PickPropsWithExceptions
 } from '@instructure/shared-types'
-import type { FormMessage, FormFieldOwnProps } from '@instructure/ui-form-field'
+import type { FormMessage, FormFieldOwnProps } from '@instructure/ui-form-field/v11_6'
 import type {
   WithStyleProps,
   ComponentStyle,

package/src/TextArea/{styles.ts → v1/styles.ts}

@@ -88,9 +88,10 @@ const generateStyle = (
         transform: 'scale(1)',
         opacity: 1
       },
-      '&[aria-invalid], &[aria-invalid]:focus, &[aria-invalid]:focus + [class$=-textArea__outline]': {
-        borderColor: componentTheme.errorBorderColor
-      },
+      '&[aria-invalid], &[aria-invalid]:focus, &[aria-invalid]:focus + [class$=-textArea__outline]':
+        {
+          borderColor: componentTheme.errorBorderColor
+        },
       '&::placeholder': {
         color: componentTheme.placeholderColor
       },

package/src/TextArea/v2/README.md

@@ -0,0 +1,136 @@
+---
+describes: TextArea
+---
+
+TextArea renders a standard HTML `textarea` element. By default, TextArea will
+resize to fit its content. Use the `maxHeight` property to set a limit on the
+component's height.
+
+```js
+---
+type: example
+---
+<div>
+  <TextArea
+    label="Enter/delete text to see TextArea resize"
+  />
+  <br />
+  <TextArea
+    label="I can't go any higher than 10rem (160px)"
+    maxHeight="10rem"
+  />
+</div>
+```
+
+To allow the user to manually resize TextArea (in supported browsers), use the
+`resize` property.
+
+```js
+---
+type: example
+---
+<TextArea label="Description" resize="vertical" />
+```
+
+A `TextArea` with errors:
+
+```js
+---
+type: example
+---
+<TextArea messages={[{ text: 'Invalid description', type: 'error' }]} label="Description" />
+```
+
+A disabled `TextArea`:
+
+```js
+---
+type: example
+---
+<TextArea label="Description" disabled />
+```
+
+A `TextArea` with a screenreader only label:
+
+```js
+---
+type: example
+---
+<TextArea
+  label={<ScreenReaderContent>Description</ScreenReaderContent>}
+  placeholder="describe something"
+/>
+```
+
+An inline `TextArea` with a fixed width, initial height and maxHeight.
+
+```js
+---
+type: example
+---
+<div style={{ display: 'flex', alignItems: 'center' }}>
+  <TextArea
+    label={<ScreenReaderContent>Label</ScreenReaderContent>}
+    inline
+    width="10em"
+    height="10em"
+    maxHeight="250px"
+  />
+</div>
+```
+
+A 'controlled' TextArea:
+
+```js
+---
+type: example
+---
+  const Example = () => {
+    const [description, setDescription] = useState('Hello World')
+
+    const handleChange = (e) => setDescription(e.target.value)
+
+    return (
+      <TextArea
+        label="Description"
+        value={description}
+        onChange={handleChange}
+      />
+    )
+  }
+
+  render(<Example />)
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="yes" title="Do">
+    <Figure.Item>Align text to the left</Figure.Item>
+  </Figure>
+  <Figure recommendation="no" title="Don't">
+    <Figure.Item>Repeat label text if using placeholder text</Figure.Item>
+    <Figure.Item>Use for rich text editing</Figure.Item>
+    <Figure.Item>Allow resizing of the TextArea to break the layout of a page</Figure.Item>
+    <Figure.Item>Place labels to the right of the TextArea</Figure.Item>
+  </Figure>
+</Guidelines>
+```
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Alert
+    variant="info"
+    margin="small"
+  >
+    Every non-listed prop will be passed down to the underlying 'textarea' element, such as 'onBlur' and any other prop
+  </Alert>
+</Guidelines>
+```

package/src/TextArea/v2/index.tsx

@@ -0,0 +1,434 @@
+/*
+ * 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 {
+  forwardRef,
+  useRef,
+  useEffect,
+  useContext,
+  useImperativeHandle,
+  useCallback,
+  useMemo
+} from 'react'
+import { FormField } from '@instructure/ui-form-field/latest'
+import {
+  addEventListener,
+  isActiveElement,
+  requestAnimationFrame,
+  getBoundingClientRect
+} from '@instructure/ui-dom-utils'
+import type { RequestAnimationFrameType } from '@instructure/ui-dom-utils'
+import { debounce } from '@instructure/debounce'
+import type { Debounced } from '@instructure/debounce'
+
+import { useStyle } from '@instructure/emotion'
+import { generateId, px } from '@instructure/ui-utils'
+
+import {
+  passthroughProps,
+  pickProps,
+  DeterministicIdContext
+} from '@instructure/ui-react-utils'
+
+import generateStyle from './styles'
+import type { TextAreaProps } from './props'
+
+export type TextAreaElement = {
+  focus: () => void
+  readonly value: string
+  readonly minHeight: string
+  readonly focused: boolean
+  readonly invalid: boolean
+  readonly id: string
+}
+
+/**
+---
+category: components
+---
+**/
+const TextArea = forwardRef<TextAreaElement, TextAreaProps>((props, ref) => {
+  const {
+    size = 'medium',
+    autoGrow = true,
+    resize = 'none',
+    inline = false,
+    messages = [],
+    disabled = false,
+    readOnly = false,
+    layout = 'stacked',
+    required = false,
+    placeholder,
+    value,
+    defaultValue,
+    width,
+    height,
+    maxHeight,
+    textareaRef,
+    margin,
+    label,
+    onChange,
+    id: propId,
+    themeOverride,
+    ...rest
+  } = props
+
+  // Use deterministic ID
+  const instanceCounterMap = useContext(DeterministicIdContext)
+  const defaultId = useMemo(
+    () => generateId('TextArea', instanceCounterMap),
+    [instanceCounterMap]
+  )
+  const id = propId || defaultId
+
+  // Use refs for mutable values
+  const _listener = useRef<{ remove(): void } | undefined>()
+  const _request = useRef<RequestAnimationFrameType | undefined>()
+  const _textareaResizeListener = useRef<ResizeObserver | undefined>()
+  const _debounced = useRef<Debounced<() => void> | undefined>()
+  const _textarea = useRef<HTMLTextAreaElement | null>(null)
+  const _container = useRef<HTMLDivElement | null>(null)
+  const _height = useRef<string | undefined>()
+  const _manuallyResized = useRef(false)
+  const formFieldRef = useRef<Element | null>(null)
+
+  // Compute invalid state
+  const { isInvalid, isSuccess } = useMemo(() => {
+    const isInvalid =
+      messages &&
+      messages.findIndex(
+        (message) => message.type === 'error' || message.type === 'newError'
+      ) >= 0
+    const isSuccess =
+      messages &&
+      messages.findIndex((message) => message.type === 'success') >= 0
+    return { isInvalid, isSuccess }
+  }, [messages])
+
+  // Use styles
+  const styles = useStyle({
+    generateStyle,
+    themeOverride,
+    params: {
+      size,
+      disabled,
+      readOnly,
+      success: isSuccess,
+      invalid: isInvalid
+    },
+    componentId: 'TextArea',
+    displayName: 'TextArea'
+  })
+
+  // Mock ResizeObserver for SSR
+  useEffect(() => {
+    if (typeof window === 'undefined') {
+      global.ResizeObserver = class ResizeObserver {
+        observe() {
+          // do nothing
+        }
+        unobserve() {
+          // do nothing
+        }
+        disconnect() {
+          // do nothing
+        }
+      }
+    }
+  }, [])
+
+  // Grow function
+  const grow = useCallback(() => {
+    if (!_textarea.current || _manuallyResized.current) {
+      return
+    }
+    const offset =
+      _textarea.current.offsetHeight - _textarea.current.clientHeight
+    let heightValue = ''
+
+    // Notes:
+    // 1. height has to be reset to `auto` every time this method runs, or scrollHeight will not reset
+    // 2. `_textarea.current.scrollHeight` will not reset if assigned to a variable; it needs to be written out each time
+    _textarea.current.style.height = 'auto'
+    _textarea.current.style.overflowY = 'hidden' // hide scrollbars for autoGrow textareas
+    heightValue = _textarea.current.scrollHeight + offset + 'px'
+
+    const maxHeightPx = maxHeight
+      ? px(maxHeight, _container.current)
+      : undefined
+
+    if (
+      maxHeight &&
+      maxHeightPx !== undefined &&
+      _textarea.current.scrollHeight > maxHeightPx
+    ) {
+      _textarea.current.style.overflowY = 'auto' // add scroll if scrollHeight exceeds maxHeight in pixels
+    } else if (height) {
+      if (_textarea.current.value === '') {
+        heightValue = height
+      } else if (
+        px(height, _container.current) > _textarea.current.scrollHeight
+      ) {
+        _textarea.current.style.overflowY = 'auto' // add scroll if scrollHeight exceeds height in pixels
+        heightValue = height
+      }
+    }
+
+    // preserve container height to prevent scroll jumping on long textareas,
+    // but make sure container doesn't exceed maxHeight prop
+    const heightExceedsMax =
+      maxHeightPx !== undefined && px(heightValue) > maxHeightPx
+    if (!heightExceedsMax && _container.current) {
+      _container.current.style.minHeight = heightValue
+    }
+
+    _height.current = heightValue
+    _textarea.current.style.height = heightValue
+  }, [height, maxHeight])
+
+  // Textarea resize handler
+  const _textareaResize = useCallback(() => {
+    if (!_textarea.current) return
+
+    const textareaHeight = _textarea.current.style.height
+    if (textareaHeight !== '' && textareaHeight !== _height.current) {
+      _manuallyResized.current = true
+      _textarea.current.style.overflowY = 'auto'
+
+      // update container minHeight to ensure focus ring always wraps input
+      if (_container.current) {
+        _container.current.style.minHeight = textareaHeight
+      }
+    }
+  }, [])
+
+  // AutoGrow effect
+  useEffect(() => {
+    if (autoGrow) {
+      if (!_debounced.current) {
+        _debounced.current = debounce(grow, 200, {
+          leading: false,
+          trailing: true
+        })
+      }
+
+      if (!_listener.current) {
+        _listener.current = addEventListener(
+          window,
+          'resize',
+          _debounced.current
+        )
+      }
+
+      if (_textarea.current && !_textareaResizeListener.current) {
+        const { height: origHeight } = getBoundingClientRect(_textarea.current)
+        _textareaResizeListener.current = new ResizeObserver((entries) => {
+          for (const entry of entries) {
+            const { height: entryHeight } = entry.contentRect
+
+            if (origHeight !== entryHeight) {
+              _textareaResize()
+            }
+          }
+        })
+
+        _textareaResizeListener.current.observe(_textarea.current)
+      }
+
+      _request.current = requestAnimationFrame(grow)
+    }
+  }, [autoGrow, grow, _textareaResize])
+
+  // Cleanup effect
+  useEffect(() => {
+    return () => {
+      if (_listener.current) {
+        _listener.current.remove()
+      }
+
+      if (_textareaResizeListener.current) {
+        _textareaResizeListener.current.disconnect()
+      }
+
+      if (_request.current) {
+        _request.current.cancel()
+      }
+
+      if (_debounced.current) {
+        _debounced.current.cancel()
+      }
+    }
+  }, [])
+
+  // Handle change
+  const handleChange = useCallback(
+    (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+      if (disabled || readOnly) {
+        event.preventDefault()
+        return
+      }
+
+      if (typeof value === 'undefined') {
+        // if uncontrolled
+        if (autoGrow) {
+          if (!_debounced.current) {
+            _debounced.current = debounce(grow, 200, {
+              leading: false,
+              trailing: true
+            })
+          }
+
+          if (!_listener.current) {
+            _listener.current = addEventListener(
+              window,
+              'resize',
+              _debounced.current
+            )
+          }
+
+          if (_textarea.current && !_textareaResizeListener.current) {
+            const { height: origHeight } = getBoundingClientRect(
+              _textarea.current
+            )
+            _textareaResizeListener.current = new ResizeObserver((entries) => {
+              for (const entry of entries) {
+                const { height: entryHeight } = entry.contentRect
+
+                if (origHeight !== entryHeight) {
+                  _textareaResize()
+                }
+              }
+            })
+
+            _textareaResizeListener.current.observe(_textarea.current)
+          }
+
+          _request.current = requestAnimationFrame(grow)
+        }
+      }
+
+      if (typeof onChange === 'function') {
+        onChange(event)
+      }
+    },
+    [disabled, readOnly, value, onChange, autoGrow, grow, _textareaResize]
+  )
+
+  // Expose API through ref using useImperativeHandle
+  useImperativeHandle(
+    ref,
+    () => ({
+      focus: () => {
+        _textarea.current?.focus()
+      },
+      get value() {
+        return _textarea.current?.value || ''
+      },
+      get minHeight() {
+        return _textarea.current?.style.minHeight || ''
+      },
+      get focused() {
+        return isActiveElement(_textarea.current)
+      },
+      get invalid() {
+        return (
+          messages &&
+          messages.findIndex(
+            (message) => message.type === 'error' || message.type === 'newError'
+          ) >= 0
+        )
+      },
+      get id() {
+        return id
+      }
+    }),
+    [id, messages]
+  )
+
+  const style = {
+    width,
+    resize,
+    height: !autoGrow ? height : undefined,
+    maxHeight
+  }
+
+  const textarea = (
+    <textarea
+      {...passthroughProps(rest)}
+      value={value}
+      defaultValue={defaultValue}
+      placeholder={placeholder}
+      ref={(textarea) => {
+        _textarea.current = textarea
+        if (typeof textareaRef === 'function') {
+          textareaRef(textarea)
+        }
+      }}
+      style={style}
+      id={id}
+      required={required}
+      aria-required={required}
+      aria-invalid={isInvalid ? 'true' : undefined}
+      disabled={disabled}
+      readOnly={readOnly}
+      css={styles?.textArea}
+      onChange={handleChange}
+    />
+  )
+
+  return (
+    <FormField
+      {...pickProps(props, FormField.allowedProps)}
+      label={label}
+      vAlign="top"
+      id={id}
+      elementRef={(el) => {
+        formFieldRef.current = el
+      }}
+      margin={margin}
+      isRequired={required}
+      disabled={disabled}
+      readOnly={readOnly}
+      data-cid="TextArea"
+    >
+      <div
+        css={styles?.textAreaLayout}
+        style={{
+          width,
+          maxHeight
+        }}
+        ref={(node) => {
+          _container.current = node
+        }}
+      >
+        {textarea}
+      </div>
+    </FormField>
+  )
+})
+
+TextArea.displayName = 'TextArea'
+
+export default TextArea
+export { TextArea }