@instructure/ui-source-code-editor 8.25.1-snapshot-19

package/src/SourceCodeEditor/props.ts

@@ -0,0 +1,291 @@
+/*
+ * 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 PropTypes from 'prop-types'
+
+import type { TagStyle } from '@codemirror/language'
+
+import { controllable } from '@instructure/ui-prop-types'
+
+import type {
+  PropValidators,
+  CodeEditorTheme,
+  OtherHTMLAttributes
+} from '@instructure/shared-types'
+import type {
+  WithStyleProps,
+  StyleObject,
+  ComponentStyle
+} from '@instructure/emotion'
+import type { WithDeterministicIdProps } from '@instructure/ui-react-utils'
+import type { BidirectionalProps } from '@instructure/ui-i18n'
+
+type SourceCodeEditorOwnProps = {
+  /**
+   * The label text that screen readers will read when this component gets
+   * focus.
+   */
+  label: string
+
+  /**
+   * The language to use (adds autocomplete and syntax highlighting).
+   */
+  language?:
+    | 'sh'
+    | 'js'
+    | 'json'
+    | 'javascript'
+    | 'jsx'
+    | 'shell'
+    | 'css'
+    | 'html'
+    | 'markdown'
+    | 'yaml'
+    | 'yml'
+    | 'bash'
+
+  /**
+   * This disables editing of the editor content by the user and API calls.
+   *
+   * __Note:__ The editor is still focusable in readOnly mode. Read more at the [codemirror documentation](https://codemirror.net/6/docs/ref/#state.EditorState%5EreadOnly).
+   */
+  readOnly?: boolean
+
+  /**
+   * Controls whether the editor content DOM is editable.
+   *
+   * __Note:__ When set to false, the editor is not focusable.
+   * (This doesn't affect API calls that change the editor content, e.g.: copy-paste,
+   * even when those are bound to keys or buttons.) Read more at the [codemirror documentation](https://codemirror.net/6/docs/ref/#view.EditorView%5Eeditable).
+   */
+  editable?: boolean
+
+  /**
+   * Whether to display the line numbers in the gutter
+   */
+  lineNumbers?: boolean
+
+  /**
+   * Whether to show a fold status indicator before foldable lines (which can be clicked to fold or unfold the line)
+   */
+  foldGutter?: boolean
+
+  /**
+   * Whether to highlight gutter elements on the active line (visible only when a gutter is visible)
+   */
+  highlightActiveLineGutter?: boolean
+
+  /**
+   * Highlights the lines that have a cursor on them
+   */
+  highlightActiveLine?: boolean
+
+  /**
+   * Whether it should scroll or wrap for long lines. Defaults to false (scroll)
+   */
+  lineWrapping?: boolean
+
+  /**
+   * Whether the editor should focus itself on initialization
+   */
+  autofocus?: boolean
+
+  /**
+   * Whether spellcheck will be enabled on the input
+   */
+  spellcheck?: boolean
+
+  /**
+   * Whether the editor should auto-indent the code on this initial load
+   * and when the `value` is changed
+   */
+  indentOnLoad?: boolean
+
+  /**
+   * When this feature is on, Tab and Shift-Tab will indent the code. By default, it is turned off, and tabbing will focus the next element in the tab order.
+   *
+   * __Note__: Even if this feature is on, pressing Escape before tabbing will not handle indentation and will handle focus instead.
+   */
+  indentWithTab?: boolean
+
+  /**
+   * Overrides the unit by which indentation happens (defaults to 2 spaces).
+   * Should be a string consisting either entirely of spaces or entirely of tabs.
+   */
+  indentUnit?: string
+
+  /**
+   * Flips overall layout and selects base paragraph direction to be "LTR" or "RTL".
+   */
+  direction?: 'ltr' | 'rtl'
+
+  /**
+   * Whether horizontal cursor movement through "RTL" text is visual
+   * (pressing the left arrow moves the cursor left) or logical
+   * (pressing the left arrow moves to the next lower index in the string,
+   * which is visually right in "RTL" text)
+   */
+  rtlMoveVisually?: boolean
+
+  /**
+   * The default value of the editor (in uncontrolled mode)
+   */
+  defaultValue?: string
+
+  /**
+   * The selected value for the controlled version
+   * (needs an onChange handler to work)
+   */
+  value?: string
+
+  /**
+   * Called when the value of the component changes.
+   */
+  onChange?: (value: string) => void
+
+  /**
+   * Called when the editor receives focus
+   */
+  onFocus?: () => void
+
+  /**
+   * Called when the editor loses focus
+   */
+  onBlur?: () => void
+
+  /**
+   * Sets minor visual styles (border radius & top/bottom margin)
+   */
+  attachment?: 'bottom' | 'top'
+
+  // TODO: discuss the future of the dark theme with the Design theme
+  // We decided not to use the dark theme yet, the colors need to be configured
+  // (e.g. color contrast)
+  // Also, probably a `theme` oneOf prop would be better with more options
+  // darkTheme?: boolean
+
+  /**
+   * provides a reference to the underlying html root element
+   */
+  elementRef?: (element: HTMLDivElement | null) => void
+
+  /**
+   * provides a reference to the html element of the editor's container
+   */
+  containerRef?: (element: HTMLDivElement | null) => void
+}
+
+type PropKeys = keyof SourceCodeEditorOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type SourceCodeEditorProps = SourceCodeEditorOwnProps &
+  WithStyleProps<
+    CodeEditorTheme,
+    // The highlightStyle is a unique one, not compatible with our style syntax,
+    // but isn't used for the css prop anyway
+    Record<keyof SourceCodeEditorStyle, any>
+  > &
+  BidirectionalProps &
+  OtherHTMLAttributes<SourceCodeEditorOwnProps> &
+  WithDeterministicIdProps
+
+type SourceCodeEditorStyle = ComponentStyle<
+  'codeEditor' | 'codeEditorContainer'
+> & {
+  theme: StyleObject
+  highlightStyle: TagStyle[]
+}
+
+const propTypes: PropValidators<PropKeys> = {
+  label: PropTypes.string.isRequired,
+  language: PropTypes.oneOf([
+    'sh',
+    'js',
+    'json',
+    'javascript',
+    'jsx',
+    'shell',
+    'css',
+    'html',
+    'markdown',
+    'yaml',
+    'yml',
+    'bash'
+  ]),
+  readOnly: PropTypes.bool,
+  editable: PropTypes.bool,
+  lineNumbers: PropTypes.bool,
+  foldGutter: PropTypes.bool,
+  highlightActiveLineGutter: PropTypes.bool,
+  highlightActiveLine: PropTypes.bool,
+  lineWrapping: PropTypes.bool,
+  autofocus: PropTypes.bool,
+  spellcheck: PropTypes.bool,
+  direction: PropTypes.oneOf(['ltr', 'rtl']),
+  rtlMoveVisually: PropTypes.bool,
+  indentOnLoad: PropTypes.bool,
+  indentWithTab: PropTypes.bool,
+  indentUnit: PropTypes.string,
+  defaultValue: PropTypes.string,
+  value: controllable(PropTypes.string, 'onChange', 'defaultValue'),
+  onChange: PropTypes.func,
+  onFocus: PropTypes.func,
+  onBlur: PropTypes.func,
+  attachment: PropTypes.oneOf(['bottom', 'top']),
+  // darkTheme: PropTypes.bool,
+  elementRef: PropTypes.func,
+  containerRef: PropTypes.func
+}
+
+const allowedProps: AllowedPropKeys = [
+  'label',
+  'language',
+  'readOnly',
+  'editable',
+  'lineNumbers',
+  'foldGutter',
+  'highlightActiveLineGutter',
+  'highlightActiveLine',
+  'lineWrapping',
+  'autofocus',
+  'spellcheck',
+  'direction',
+  'rtlMoveVisually',
+  'indentOnLoad',
+  'indentWithTab',
+  'indentUnit',
+  'defaultValue',
+  'value',
+  'onChange',
+  'onFocus',
+  'onBlur',
+  'attachment',
+  // 'darkTheme',
+  'elementRef',
+  'containerRef'
+]
+
+export type { SourceCodeEditorProps, SourceCodeEditorStyle }
+export { propTypes, allowedProps }

package/src/SourceCodeEditor/styles.ts

@@ -0,0 +1,200 @@
+/*
+ * 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 { tags } from '@lezer/highlight'
+
+import type { SourceCodeEditorTheme } from '@instructure/shared-types'
+import type { SourceCodeEditorProps, SourceCodeEditorStyle } from './props'
+
+/**
+ * ---
+ * private: true
+ * ---
+ * Generates the style object from the theme and provided additional information
+ * @param  {Object} componentTheme The theme variable object.
+ * @param  {Object} props the props of the component, the style is applied to
+ * @return {Object} The final style object, which will be used in the component
+ */
+const generateStyle = (
+  componentTheme: SourceCodeEditorTheme,
+  props: SourceCodeEditorProps
+): SourceCodeEditorStyle => {
+  const { attachment } = props
+
+  const attachmentBorderRadius = {
+    top: {
+      borderBottomLeftRadius: 0,
+      borderBottomRightRadius: 0
+    },
+    bottom: {
+      borderTopLeftRadius: 0,
+      borderTopRightRadius: 0
+    }
+  }
+
+  const attachmentVariants = {
+    top: {
+      marginBottom: 0,
+      marginTop: '0.25rem'
+    },
+    bottom: {
+      borderTopLeftRadius: 0,
+      borderTopRightRadius: 0,
+      marginBottom: '0.25rem'
+    }
+  }
+
+  return {
+    codeEditor: {
+      label: 'codeEditor',
+      position: 'relative'
+    },
+    codeEditorContainer: {
+      label: 'codeEditorContainer',
+      borderColor: componentTheme?.borderColor,
+      borderStyle: 'solid',
+      borderWidth: componentTheme?.borderWidth,
+      borderRadius: componentTheme.borderRadius,
+      marginBottom: '1rem',
+      ...(attachment && {
+        ...attachmentVariants[attachment],
+        ...attachmentBorderRadius[attachment]
+      })
+    },
+    theme: {
+      '&': {
+        overflow: 'hidden',
+        background: componentTheme.background,
+        height: 'auto',
+        fontFamily: componentTheme.fontFamily,
+        fontSize: componentTheme.fontSize,
+        color: componentTheme.color,
+        border: 0,
+        lineHeight: 1.4375,
+        minHeight: '1.4375rem',
+        borderRadius: componentTheme.borderRadius,
+        ...(attachment && {
+          ...attachmentBorderRadius[attachment]
+        })
+      },
+
+      '&.cm-editor.cm-focused': {
+        // Provide a simple default outline to make sure a focused
+        // editor is visually distinct. Can't leave the default behavior
+        // because that will apply to the content element, which is
+        // inside the scrollable container and doesn't include the
+        // gutters. We also can't use an 'auto' outline, since those
+        // are, for some reason, drawn behind the element content, which
+        // will cause things like the active line background to cover
+        // the outline (#297).
+        outline: `${componentTheme?.borderWidth} solid ${componentTheme?.focusBorderColor}`
+      },
+
+      '.cm-content': {
+        padding: `${componentTheme.verticalPadding} 0`
+      },
+
+      '.cm-scroller': {
+        fontFamily: componentTheme.fontFamily,
+        lineHeight: 1.4375
+      },
+
+      '.cm-gutters': {
+        background: componentTheme.gutterBackground,
+        borderColor: componentTheme.borderColor
+      },
+
+      '.cm-line': {
+        padding: `0 ${componentTheme.horizontalPadding}`
+      },
+
+      '.cm-selectionBackground': {
+        background: 'transparent'
+      },
+      '.cm-focused .cm-selectionBackground': {
+        background: '#d7d4f0'
+      },
+
+      '.cm-placeholder': {
+        // for better contrast
+        color: '#707070'
+      }
+    },
+
+    highlightStyle: [
+      /**
+       * Copy of `defaultHighlightStyle` from '@codemirror/language'
+       */
+      // { tag: tags.meta, color: '#7a757a' },
+      { tag: tags.link, textDecoration: 'underline' },
+      { tag: tags.heading, textDecoration: 'underline', fontWeight: 'bold' },
+      { tag: tags.emphasis, fontStyle: 'italic' },
+      { tag: tags.strong, fontWeight: 'bold' },
+      { tag: tags.strikethrough, textDecoration: 'line-through' },
+      { tag: tags.keyword, color: '#708' },
+      {
+        tag: [
+          tags.atom,
+          tags.bool,
+          tags.url,
+          tags.contentSeparator,
+          tags.labelName
+        ],
+        color: '#219'
+      },
+      { tag: [tags.literal, tags.inserted], color: '#164' },
+      { tag: [tags.string, tags.deleted], color: '#a11' },
+      // {
+      //   tag: [tags.regexp, tags.escape, tags.special(tags.string)],
+      //   color: '#e40'
+      // },
+      { tag: tags.definition(tags.variableName), color: '#00f' },
+      { tag: tags.local(tags.variableName), color: '#30a' },
+      // { tag: [tags.typeName, tags.namespace], color: '#085' },
+      { tag: tags.className, color: '#167' },
+      {
+        tag: [tags.special(tags.variableName), tags.macroName],
+        color: '#256'
+      },
+      { tag: tags.definition(tags.propertyName), color: '#00c' },
+      { tag: tags.comment, color: '#940' },
+      // { tag: tags.invalid, color: '#f00' },
+
+      /**
+       * Custom highlighting overrides
+       * (where original colors don't have enough contrast against #fff
+       * or active highlight background)
+       */
+      { tag: tags.meta, color: '#757075' },
+      {
+        tag: [tags.regexp, tags.escape, tags.special(tags.string)],
+        color: '#d13b00'
+      },
+      { tag: [tags.typeName, tags.namespace], color: '#008051' },
+      { tag: tags.invalid, color: '#e60000' }
+    ]
+  }
+}
+
+export default generateStyle

package/src/SourceCodeEditor/theme.ts

@@ -0,0 +1,55 @@
+/*
+ * 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 { Theme } from '@instructure/ui-themes'
+import type { SourceCodeEditorTheme } from '@instructure/shared-types'
+
+/**
+ * Generates the theme object for the component from the theme and provided additional information
+ * @param  {Object} theme The actual theme object.
+ * @return {Object} The final theme object with the overrides and component variables
+ */
+const generateComponentTheme = (theme: Theme): SourceCodeEditorTheme => {
+  const { colors, borders, typography, spacing } = theme
+
+  const componentVariables: SourceCodeEditorTheme = {
+    fontFamily: typography?.fontFamilyMonospace,
+    fontSize: typography?.fontSizeSmall,
+    background: colors?.backgroundLightest,
+    color: colors?.textDarkest,
+    gutterBackground: colors?.backgroundLight,
+    borderWidth: borders?.widthSmall,
+    borderColor: colors?.borderMedium,
+    borderRadius: borders?.radiusMedium,
+    focusBorderColor: colors?.borderBrand,
+    horizontalPadding: spacing?.xSmall,
+    verticalPadding: spacing?.xxSmall
+  }
+
+  return {
+    ...componentVariables
+  }
+}
+
+export default generateComponentTheme

package/src/index.ts

@@ -0,0 +1,25 @@
+/*
+ * 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.
+ */
+export { SourceCodeEditor } from './SourceCodeEditor'
+export type { SourceCodeEditorProps } from './SourceCodeEditor/props'

package/tsconfig.build.json

@@ -0,0 +1,25 @@
+{
+  "extends": "../../tsconfig.build.json",
+  "compilerOptions": {
+    "outDir": "./types",
+    "composite": true,
+    "rootDir": "./src"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../ui-babel-preset/tsconfig.build.json" },
+    { "path": "../ui-test-utils/tsconfig.build.json" },
+    { "path": "../ui-themes/tsconfig.build.json" },
+    { "path": "../emotion/tsconfig.build.json" },
+    { "path": "../shared-types/tsconfig.build.json" },
+    { "path": "../ui-a11y-content/tsconfig.build.json" },
+    { "path": "../ui-dom-utils/tsconfig.build.json" },
+    { "path": "../ui-i18n/tsconfig.build.json" },
+    { "path": "../ui-prop-types/tsconfig.build.json" },
+    { "path": "../ui-react-utils/tsconfig.build.json" },
+    { "path": "../ui-test-locator/tsconfig.build.json" },
+    { "path": "../ui-test-queries/tsconfig.build.json" },
+    { "path": "../ui-testable/tsconfig.build.json" },
+    { "path": "../ui-utils/tsconfig.build.json" }
+  ]
+}