@instructure/ui-editable 11.7.2-snapshot-23 → 11.7.2-snapshot-25

package/src/Editable/v1/README.md

@@ -56,7 +56,7 @@ const Example = (props) => {
   }
 
   const renderViewer = () => {
-    return <span>{value}</span>
+    return <Text>{value}</Text>
   }
 
   const handleValueChange = (event) => {
@@ -69,8 +69,10 @@ const Example = (props) => {
 
   const renderEditor = ({ onBlur, editorRef }) => {
     return (
-      <input
-        ref={editorRef}
+      <TextInput
+        renderLabel=""
+        width="10rem"
+        inputRef={editorRef}
         onBlur={onBlur}
         value={value}
         onChange={handleValueChange}

package/src/InPlaceEdit/v2/README.md

@@ -0,0 +1,338 @@
+---
+describes: InPlaceEdit
+---
+
+`InPlaceEdit` provides the DOM structure to organize the components that participate
+in in-place editing by calling the `renderViewer` and `renderEditor` _render props_
+in the context of the containing DOM sub-tree. It also takes care of wiring up the
+event handlers required by [`Editable`](Editable) to make the user interactions work.
+
+As a controlled component, it is the responsibility of the consumer to maintain some data to make this work.
+Each time `InPlaceEdit` is rendered, you must provide as props:
+
+- the current `mode` prop, which defaults to `'view'`. The app will be notified of
+  changes in mode via the `onChangeMode` function property.
+- the current `value` prop, which primarily serves to trigger a re-render when the value changes
+
+The view component, as returned by the `renderViewer` property can be anything you wish, but
+will typically render some formatted text. It is up to the consumer to provide this component with
+the current value.
+
+The edit component, as returned by the `renderEditor` property is used to collect the user's
+input. It is up to the consumer to provide the necessary properties to get the user provided value
+(typically `onChange`), and to provide the current value.
+
+Some components, like [Heading](Heading) and [Text](Text) can be made editable by setting their `as` property
+to `input` (and optionally the `type` property). The value of this approach is that the editable version
+will render in the same style as the view, making for a nice user experience. Other transitions,
+`Text` to `Select` or `DateTimeInput` for example, result in a wholesale change in the component's UI, and will alter
+the space it consumes in the app.
+
+Use `InPlaceEdit` to edit `Text` using `Text as="input"`. Also demonstrates how you might wish to handle
+the case when the text is empty. Use the checkbox to switch between inline and block layout.
+
+```js
+---
+type: example
+---
+  const Example = (props) => {
+    const [mode, setMode] = useState(props.mode || 'view')
+    const [value, setValue] = useState('This is some text')
+    const [inline, setInline] = useState(true)
+
+    // You must provide this to Editable to be
+    // notified of mode changes
+    const handleChangeMode = (mode) => {
+      setMode(mode)
+    }
+
+    // You attach an event handler to your edit component
+    // to be notified of value changes from user interactions
+    const handleChange = (event) => {
+      setValue(event.target.value)
+    }
+
+    // Renders the view component
+    // Be sure to give it the current value
+    const renderView = () => (
+      <Text
+        color={value ? 'primary' : 'secondary'}
+        weight={value ? 'normal' : 'light'}
+        size="large"
+      >
+        {value || 'Enter some text'}
+      </Text>
+    )
+
+    // Renders the edit component.
+    // You have to forward the props on, which
+    // includes an onBlur property to help manage
+    // the mode changes.
+    // Be sure to give it the current value
+    const renderEdit = ({ onBlur, editorRef }) => (
+      <Text
+        color="primary"
+        size="large"
+        as="input"
+        type="text"
+        value={value}
+        onChange={handleChange}
+        aria-label="The title"
+        onBlur={onBlur}
+        elementRef={editorRef}
+      />
+    )
+
+    // Renders the edit button.
+    // Leverage the default implementation provided by InPlaceEdit
+    const renderEditButton = (props) => {
+      props.label = `Edit title "${value}"`
+      return InPlaceEdit.renderDefaultEditButton(props)
+    }
+
+    const onChangeLayout = (event) => {
+      setInline(event.target.checked)
+    }
+
+    return (
+      <View as="div">
+        <InPlaceEdit
+          renderViewer={renderView}
+          renderEditor={renderEdit}
+          renderEditButton={renderEditButton}
+          onChangeMode={handleChangeMode}
+          mode={mode}
+          value={value}
+          inline={inline}
+        />
+        <View as="div" margin="small 0">
+          <Checkbox label="inline" checked={inline} onChange={onChangeLayout} />
+        </View>
+      </View>
+    )
+  }
+
+  render(<Example />)
+```
+
+A readOnly `InPlaceEdit`
+
+```js
+---
+type: example
+---
+  const Example = (props) => {
+    const [mode, setMode] = useState(props.mode || 'view')
+    const [value, setValue] = useState('This is some text')
+
+    // You must provide this to Editable to be
+    // notified of mode changes
+    const handleChangeMode = (mode) => {
+      setMode(mode)
+    }
+
+    // You attach an event handler to your edit component
+    // to be notified of value changes from user interactions
+    const handleChange = (event) => {
+      setValue(event.target.value)
+    }
+
+    // Renders the view component
+    // Be sure to give it the current value
+    const renderView = () => <Text size="large">{value}</Text>
+
+    // Renders the edit component.
+    // You have to forward the props on, which
+    // includes an onBlur property to help manage
+    // the mode changes.
+    // Be sure to give it the current value
+    const renderEdit = ({ onBlur, editorRef }) => (
+      <Text
+        size="large"
+        as="input"
+        type="text"
+        value={value}
+        onChange={handleChange}
+        aria-label="The title"
+        onBlur={onBlur}
+        elementRef={editorRef}
+      />
+    )
+
+    // Renders the edit button.
+    // Leverage the default implementation provided by InPlaceEdit
+    const renderEditButton = (props) => {
+      props.label = `Edit title "${value}"`
+      return InPlaceEdit.renderDefaultEditButton(props)
+    }
+
+    return (
+      <InPlaceEdit
+        readOnly
+        renderViewer={renderView}
+        renderEditor={renderEdit}
+        renderEditButton={renderEditButton}
+        onChangeMode={handleChangeMode}
+        mode={mode}
+        value={value}
+      />
+    )
+  }
+
+  render(<Example />)
+```
+
+To edit end-justified text, wrap `<InPlaceEdit />` in a
+`<View>` component, as follows:
+
+```js
+---
+type: example
+---
+  const Example = (props) => {
+    const [mode, setMode] = useState(props.mode || 'view')
+    const [value, setValue] = useState('This is some text')
+
+    // You must provide this to Editable to be
+    // notified of mode changes
+    const handleChangeMode = (mode) => {
+      setMode(mode)
+    }
+
+    // You attach an event handler to your edit component
+    // to be notified of value changes from user interactions
+    const handleChange = (event) => {
+      setValue(event.target.value)
+    }
+
+    // Renders the view component
+    // Be sure to give it the current value
+    const renderView = () => <Text size="large">{value}</Text>
+
+    // Renders the edit component.
+    // You have to forward the props on, which
+    // includes an onBlur property to help manage
+    // the mode changes.
+    // Be sure to give it the current value
+    const renderEdit = ({ onBlur, editorRef }) => (
+      <Text
+        size="large"
+        as="input"
+        type="text"
+        value={value}
+        onChange={handleChange}
+        aria-label="The title"
+        onBlur={onBlur}
+        elementRef={editorRef}
+      />
+    )
+
+    // Renders the edit button.
+    // Leverage the default implementation provided by InPlaceEdit
+    const renderEditButton = (props) => {
+      props.label = `Edit title "${value}"`
+      return InPlaceEdit.renderDefaultEditButton(props)
+    }
+
+    return (
+      <View as="div" textAlign="end">
+        <InPlaceEdit
+          renderViewer={renderView}
+          renderEditor={renderEdit}
+          renderEditButton={renderEditButton}
+          onChangeMode={handleChangeMode}
+          mode={mode}
+          value={value}
+          editButtonPlacement="start"
+        />
+      </View>
+    )
+  }
+
+  render(<Example />)
+```
+
+Same as the first example, but notifies `Editable`'s `onChange`
+when the user has finished editing and the value has changed.
+
+```js
+---
+type: example
+---
+  const Example = (props) => {
+    const [mode, setMode] = useState(props.mode || 'view')
+    const [value, setValue] = useState('Edit me')
+    const [onChangeValue, setOnChangeValue] = useState(undefined)
+
+    // typically provided by the application so it can
+    // be notified of value changes when the user is
+    // finished editing
+    const onChange = (newValue) => {
+      setOnChangeValue(newValue)
+    }
+
+    // You must provide this to Editable to be
+    // notified of mode changes
+    const handleChangeMode = (mode) => {
+      setMode(mode)
+    }
+
+    // You attach an event handler to your edit component
+    // to be notified of value changes from user interactions
+    const handleChange = (event) => {
+      setValue(event.target.value)
+    }
+
+    // Renders the view component
+    // Be sure to give it the current value
+    const renderView = () => <Text size="large">{value}</Text>
+
+    // Renders the edit component.
+    // You have to forward the props on, which
+    // includes an onBlur property to help manage
+    // the mode changes.
+    // Be sure to give it the current value
+    const renderEdit = ({ onBlur, editorRef }) => (
+      <Text
+        size="large"
+        as="input"
+        type="text"
+        value={value}
+        onChange={handleChange}
+        aria-label="The title"
+        onBlur={onBlur}
+        elementRef={editorRef}
+      />
+    )
+
+    // Renders the edit button.
+    // Leverage the default implementation provided by InPlaceEdit
+    const renderEditButton = (props) => {
+      props.label = `Edit title "${value}"`
+      return InPlaceEdit.renderDefaultEditButton(props)
+    }
+
+    return (
+      <View as="div" background="primary">
+        <InPlaceEdit
+          renderViewer={renderView}
+          renderEditor={renderEdit}
+          renderEditButton={renderEditButton}
+          onChangeMode={handleChangeMode}
+          mode={mode}
+          value={value}
+          onChange={onChange}
+        />
+        <div>
+          <Text fontStyle="italic">
+            {onChangeValue !== undefined
+              ? `onChange said: ${onChangeValue}`
+              : `You haven't edited me yet!`}
+          </Text>
+        </div>
+      </View>
+    )
+  }
+
+  render(<Example />)
+```

package/src/InPlaceEdit/v2/index.tsx

@@ -0,0 +1,205 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2018 - 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 { Flex } from '@instructure/ui-flex/latest'
+import { IconButton } from '@instructure/ui-buttons/latest'
+import type { IconButtonProps } from '@instructure/ui-buttons/latest'
+import { PencilInstUIIcon } from '@instructure/ui-icons'
+import { logWarn as warn } from '@instructure/console'
+import { createChainedFunction } from '@instructure/ui-utils'
+import { withStyle } from '@instructure/emotion'
+import { View } from '@instructure/ui-view/latest'
+
+import { Editable } from '../../Editable/v1'
+import generateStyle from './styles'
+
+import { allowedProps } from './props'
+import type { InPlaceEditProps } from './props'
+import type { EditableRenderProps } from '../../Editable/v1/props'
+
+/**
+---
+category: components
+---
+**/
+@withStyle(generateStyle)
+class InPlaceEdit extends Component<InPlaceEditProps> {
+  static readonly componentId = 'InPlaceEdit'
+  static allowedProps = allowedProps
+  static defaultProps = {
+    readOnly: false,
+    showFocusRing: true,
+    inline: true,
+    editButtonPlacement: 'end'
+  }
+
+  ref: Element | null = null
+  _editButtonRef: HTMLButtonElement | null = null
+
+  handleRef = (el: Element | null) => {
+    this.ref = el
+  }
+
+  constructor(props: InPlaceEditProps) {
+    super(props)
+
+    warn(
+      props.readOnly ? props.mode === 'view' : true,
+      '[InPlaceEdit] When readOnly is true, mode is forced to "view"'
+    )
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+  }
+
+  handleEditButtonRef = (el: HTMLButtonElement) => {
+    this._editButtonRef = el
+  }
+
+  renderEditor({
+    mode,
+    onBlur,
+    editorRef,
+    readOnly
+  }: ReturnType<EditableRenderProps['getEditorProps']>) {
+    const { showFocusRing, renderEditor } = this.props
+    const isEditMode = !readOnly && mode === 'edit'
+
+    return isEditMode ? (
+      <View
+        as="span"
+        display="block"
+        withFocusOutline={showFocusRing}
+        position="relative"
+        css={this.props.styles?.inPlaceEdit}
+        borderRadius="medium"
+        margin="auto"
+      >
+        {renderEditor({ onBlur, editorRef })}
+      </View>
+    ) : null
+  }
+
+  renderViewer({
+    readOnly,
+    mode
+  }: ReturnType<EditableRenderProps['getViewerProps']>) {
+    return readOnly || mode === 'view' ? this.props.renderViewer() : null
+  }
+
+  renderEditButton({
+    buttonRef,
+    ...rest
+  }: ReturnType<EditableRenderProps['getEditButtonProps']>) {
+    return this.props.renderEditButton({
+      elementRef: createChainedFunction(this.handleEditButtonRef, buttonRef),
+      ...rest
+    })
+  }
+
+  // Render a default edit button, an icon button with the edit icon
+  // the margin makes room for the focus ring
+  static renderDefaultEditButton = ({
+    isVisible,
+    readOnly,
+    label,
+    ...buttonProps
+  }: {
+    isVisible: boolean
+    readOnly?: boolean
+    label: string
+  } & Partial<IconButtonProps>) => {
+    if (readOnly) {
+      return null
+    }
+    return (
+      <IconButton
+        size="small"
+        screenReaderLabel={label}
+        withBackground={false}
+        withBorder={false}
+        {...buttonProps}
+      >
+        {isVisible ? PencilInstUIIcon : null}
+      </IconButton>
+    )
+  }
+
+  renderAll = ({
+    getContainerProps,
+    getViewerProps,
+    getEditorProps,
+    getEditButtonProps
+  }: EditableRenderProps) => {
+    const flexDir =
+      this.props.editButtonPlacement === 'start' ? 'row-reverse' : 'row'
+    const justifyItems = flexDir === 'row-reverse' ? 'end' : 'start'
+    const buttonMargin =
+      this.props.editButtonPlacement === 'start'
+        ? '0 xx-small 0 0'
+        : '0 0 0 xx-small'
+    return (
+      <Flex
+        display={this.props.inline ? 'inline-flex' : 'flex'}
+        direction={flexDir}
+        justifyItems={justifyItems}
+        {...getContainerProps()}
+      >
+        <Flex.Item shouldGrow shouldShrink>
+          {this.renderEditor(getEditorProps())}
+          {this.renderViewer(getViewerProps())}
+        </Flex.Item>
+        <Flex.Item margin={buttonMargin}>
+          {this.renderEditButton(getEditButtonProps())}
+        </Flex.Item>
+      </Flex>
+    )
+  }
+
+  render() {
+    const { mode, value, onChange, onChangeMode, readOnly } = this.props
+
+    return (
+      <Editable
+        mode={mode}
+        onChangeMode={onChangeMode}
+        render={this.renderAll}
+        value={value}
+        onChange={onChange}
+        readOnly={readOnly}
+        elementRef={this.handleRef}
+      />
+    )
+  }
+}
+
+export default InPlaceEdit
+export { InPlaceEdit }

package/src/InPlaceEdit/v2/props.ts

@@ -0,0 +1,146 @@
+/*
+ * 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 type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import type { EditableProps } from '../../Editable/v1/props'
+import React from 'react'
+
+type ExtendedRenderEditButton = {
+  elementRef?: (el: HTMLButtonElement) => void
+  onClick: () => void
+  onFocus: () => void
+  onBlur: () => void
+  isVisible: boolean
+  readOnly?: boolean
+}
+
+type InPlaceEditOwnProps = {
+  /**
+   * Function to render the view mode component.
+   * It is the consumer's responsibility to provide the
+   * current value or children.
+   *
+   * Return value:
+   * - element: the viewer DOM sub-tree.
+   */
+  renderViewer: () => React.ReactNode
+  /**
+   * Function to render the edit mode component
+   * It is the consumer's responsibility to provide the
+   * current value, and to attach the appropriate onChange
+   * event handler needed to capture the updated value. This
+   * new value must then be forwarded to the view mode component.
+   *
+   * Return value:
+   * - element: the editor DOM sub-tree.
+   */
+  renderEditor: (data: {
+    onBlur: () => void
+    editorRef: (el: HTMLElement | null) => void
+  }) => React.ReactNode
+  /**
+   * Function to render the edit button.
+   *
+   * Parameters:
+   * - object: { isVisible, onClick, onFocus, onBlur, buttonRef }
+   *
+   * Return value:
+   *
+   * - element:  the edit button DOM sub-tree
+   *
+   * If you choose to use the default edit button, add `label` to the
+   * incoming `props` parameter and call `InPlaceEdit.renderDefaultEditButton(props)`
+   *
+   * If you choose to render a custom button, attach the on* event handlers
+   * and set `buttonRef` as a `ref` type property on the `button` element.
+   *
+   * `isVisible` is a hint as to whether the button is _typically_ shown,
+   * but you're free to ignore it for your use-case.
+   */
+  renderEditButton: (props: ExtendedRenderEditButton) => React.ReactNode | null
+  /**
+   * If `'view'`: the view component is rendered,
+   * if `'edit'`: the edit component is rendered
+   */
+  mode: 'view' | 'edit'
+  /**
+   * Called when the component's mode changes
+   * Parameter:
+   * - newMode: string
+   */
+  onChangeMode: EditableProps['onChangeMode']
+  /**
+   * The current value.
+   * The value is managed by the consuming app, but we need to tell InPlaceEdit
+   * it's changed or it won't re-render
+   */
+  value?: any
+  /**
+   * Called when Editable switches from edit to view mode and the value has changed.
+   * Parameter:
+   * - value: any
+   */
+  onChange?: EditableProps['onChange']
+  /**
+   * The mode is fixed as 'view'
+   */
+  readOnly?: boolean
+  /**
+   * Show a focus outline when the input is focused
+   */
+  showFocusRing?: boolean
+  /**
+   * Put the edit button before or after the view
+   */
+  editButtonPlacement?: 'start' | 'end'
+  /**
+   * Render outermost element inline v. block
+   */
+  inline?: boolean
+}
+
+type PropKeys = keyof InPlaceEditOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type InPlaceEditProps = InPlaceEditOwnProps &
+  WithStyleProps<null, InPlaceEditStyle>
+
+type InPlaceEditStyle = ComponentStyle<'inPlaceEdit'>
+const allowedProps: AllowedPropKeys = [
+  'renderViewer',
+  'renderEditor',
+  'renderEditButton',
+  'mode',
+  'onChangeMode',
+  'value',
+  'onChange',
+  'readOnly',
+  'showFocusRing',
+  'editButtonPlacement',
+  'inline'
+]
+
+export type { InPlaceEditProps, InPlaceEditStyle }
+export { allowedProps }