@instructure/quiz-core 22.16.1 → 22.18.0

package/src/reporting/components/charts/Distribution/presenter.js

@@ -0,0 +1,378 @@
+/** @jsx jsx */
+import {Component} from 'react'
+import {PropTypes} from 'prop-types'
+import {max, range, sum} from 'd3-array'
+import {axisBottom} from 'd3-axis'
+import {scaleBand, scaleLinear} from 'd3-scale'
+import {select} from 'd3-selection'
+import {jsx, css} from '@instructure/emotion'
+
+import t from '@instructure/quiz-i18n/format-message'
+
+import generateStyle from './styles'
+import generateComponentTheme from './theme'
+import {ScreenReaderContent, PresentationContent} from '@instructure/ui-a11y-content'
+
+import {transition} from 'd3-transition'
+import flow from 'lodash/flow'
+import {withStyleOverrides} from '@instructure/quiz-common/util/withStyleOverrides'
+
+// Star path copied from instructure-icons/svg/Solid/star.svg
+export const starPathData =
+  'M1915.918 737.475c-10.955-33.543-42.014-56.131-77.364-56.131h-612.029l-189.063-582.1v-.112C1026.394 65.588 995.335 43 959.984 43c-35.237 0-66.41 22.588-77.365 56.245L693.443 681.344H81.415c-35.35 0-66.41 22.588-77.365 56.131-10.955 33.544.79 70.137 29.478 91.03l495.247 359.831-189.177 582.212c-10.955 33.657 1.13 70.25 29.817 90.918 14.23 10.278 30.946 15.473 47.66 15.473 16.716 0 33.432-5.195 47.775-15.586l495.134-359.718 495.021 359.718c28.574 20.781 67.087 20.781 95.662.113 28.687-20.668 40.658-57.261 29.703-91.03l-189.176-582.1 495.36-359.83c28.574-20.894 40.433-57.487 29.364-91.03'
+
+const MARGIN_T = 0
+const MARGIN_B = 28
+
+@withStyleOverrides(generateStyle, generateComponentTheme)
+export class Distribution extends Component {
+  static displayName = 'Distribution'
+  static componentId = `Quizzes${this.displayName}`
+
+  static propTypes = {
+    animateDelay: PropTypes.number,
+    animateDuration: PropTypes.number,
+    // ESLint thinks these props aren't used but they are via a call chain in componentDidMount
+    barPaddingInner: PropTypes.number, // Spacing between bars, so each is visible, could be accomplished by borders
+    barPaddingOuter: PropTypes.number, // Spacing between bars, so each is visible, could be accomplished by borders
+    barPaddingTop: PropTypes.number,
+    chartHeight: PropTypes.number.isRequired, // Height in pixels
+    chartWidth: PropTypes.number,
+    /* *
+     * * a fallback minimal distribution for tab-able, keyboard navigable buckets
+     * * typically this will be ~ 10 buckets
+     * */
+    summaryDistribution: PropTypes.arrayOf(PropTypes.node),
+    /* *
+     * * A list of score values for each bucket.  Size of this array determines the number of buckets
+     * */
+    visualDistribution: PropTypes.arrayOf(PropTypes.node).isRequired,
+
+    calculateAxis: PropTypes.func,
+    createChart: PropTypes.func,
+    renderTable: PropTypes.func,
+    summarizeChart: PropTypes.func,
+    updateChart: PropTypes.func,
+    starIndex: PropTypes.number,
+    styles: PropTypes.object,
+  }
+
+  static defaultProps = {
+    animateDelay: 200,
+    animateDuration: 900,
+    barPaddingInner: 0.25, // Spacing between bars, so each is visible, could be accomplished by borders
+    barPaddingOuter: 0, // Spacing between bars, so each is visible, could be accomplished by borders
+    barPaddingTop: 0, // Spacing between highest bar and top of chart, pixels
+    chartHeight: 200, // Height in pixels
+    chartWidth: null,
+    summaryDistribution: void 0,
+    visualDistribution: [],
+    calculateAxis: Function.prototype,
+    createChart: Function.prototype,
+    renderTable: Function.prototype,
+    summarizeChart: textForScreenreaders => {
+      return textForScreenreaders
+    },
+    updateChart: Function.prototype,
+    starIndex: null,
+  }
+
+  static addTitle(svg, title) {
+    return svg.append('title').text(title)
+  }
+
+  componentDidMount() {
+    this.__svg = this.createChart(this.chart, this.props)
+    this.updateChart(this.__svg, this.props)
+  }
+
+  shouldComponentUpdate(nextProps) {
+    this.updateChart(this.__svg, nextProps)
+    return false
+  }
+
+  componentWillUnmount() {
+    this.removeChart()
+  }
+
+  isAnimated() {
+    return this.props.animateDelay || this.props.animateDuration
+  }
+
+  calculateAxis(props) {
+    // the x scale is static since it will always represent the BucketCount
+    // percentiles, so we can avoid recalculating it on every update:
+    this.x = scaleBand()
+      .rangeRound([0, this.width])
+      .paddingInner(props.barPaddingInner)
+      .paddingOuter(props.barPaddingOuter)
+      .domain(range(props.visualDistribution.length))
+
+    const highest = max(props.visualDistribution)
+    this.y = scaleLinear().rangeRound([this.height, props.barPaddingTop]).domain([0, highest])
+
+    this.xAxis = axisBottom(this.x).tickSize([0]).tickValues(range(props.visualDistribution.length))
+
+    this.props.calculateAxis(this.x, this.y, this.xAxis, this.height)
+  }
+
+  weightedAvg(data) {
+    const partitions = data.length - 1
+    const totalStudents = sum(data)
+    const avg =
+      data.reduce((total, count, index) => {
+        // Assumes even weight of scores across distribution
+        const score = index / partitions
+        return total + score * count
+      }, 0.0) / totalStudents
+
+    const avgPartition = Math.floor(avg * partitions)
+    return {
+      avg,
+      aboveAvg: sum(data.slice(avgPartition)),
+      belowAvg: sum(data.slice(0, avgPartition)),
+    }
+  }
+
+  summarizeChart() {
+    const data = this.props.summaryDistribution || this.props.visualDistribution
+    if (data.length <= 1) {
+      return ''
+    }
+    const avgInfo = this.weightedAvg(data)
+    if (avgInfo.belowAvg + avgInfo.aboveAvg < 1) {
+      return ''
+    }
+
+    let textForScreenreaders = t(
+      '{aboveAvg} students scored above or at the average, and {belowAvg} below. ',
+      {
+        aboveAvg: avgInfo.aboveAvg,
+        belowAvg: avgInfo.belowAvg,
+      },
+    )
+
+    data.forEach((datum, i) => {
+      if (datum > 0) {
+        textForScreenreaders += t(
+          `{
+            count, plural,
+            one {# student scored between {lower, number, percent} and {upper, number, percent}. }
+            other {# students scored between {lower, number, percent} and {upper, number, percent}. }
+          }`,
+          {
+            count: datum,
+            lower: i / data.length,
+            upper: (i + 1) / data.length,
+          },
+        )
+      }
+    })
+
+    return this.props.summarizeChart(textForScreenreaders)
+  }
+
+  createChart(node, props) {
+    // parentNode for IE11
+    const parentWidth = (node.parentElement || node.parentNode || {}).offsetWidth
+    this.width = props.chartWidth || parentWidth
+    this.height = props.chartHeight
+    this.viewportHeight = this.height + MARGIN_T + MARGIN_B
+
+    this.calculateAxis(props)
+
+    const svg = select(node)
+      .attr('role', 'document')
+      .attr('aria-role', 'document')
+      .attr('width', '100%')
+      .attr('height', '100%')
+      .attr('viewBox', `0 0 ${this.width} ${this.viewportHeight}`)
+      .attr('preserveAspectRatio', 'xMidYMax')
+      .append('g')
+
+    this.title = Distribution.addTitle(svg, t('Score percentiles chart'))
+
+    svg
+      .append('g')
+      .attr('class', 'xAxis')
+      .attr('style', css(this.props.styles.xAxis).styles)
+      .attr('data-role', 'xAxis')
+      .attr('aria-hidden', true)
+      .attr('transform', `translate(0,${this.height})`)
+      .call(this.xAxis)
+      .selectAll('text')
+      .attr('class', 'barLabel')
+      .attr('style', css(this.props.styles.barLabel).styles)
+      .attr('y', 9)
+
+    const clipKey = `clipPath${this.width}x${this.height}`
+    const clipPath = svg.append('clipPath').attr('id', clipKey)
+    clipPath
+      .append('rect')
+      .attr('x', 0)
+      .attr('y', 0)
+      .attr('width', this.width)
+      .attr('height', this.height)
+
+    this.barContainer = svg
+      .append('g')
+      .attr('class', 'barContainer')
+      .attr('clip-path', `url(#${clipKey})`)
+
+    this.props.createChart(svg, this.width)
+
+    return svg
+  }
+
+  updateChart(svg, props) {
+    this.renderBars(this.barContainer, props)
+    this._renderStar(this.barContainer)
+    this.props.updateChart(
+      svg,
+      this.x,
+      this.y,
+      this.applyTransition,
+      this.barContainer,
+      this.height,
+    )
+  }
+
+  removeChart() {
+    if (this.__svg) {
+      this.__svg.remove()
+      delete this.__svg
+    }
+  }
+
+  renderBars(node, props) {
+    this.chartData = props.visualDistribution
+    const height = this.height
+    const x = this.x
+    const y = this.y
+
+    const bars = node.selectAll('rect').data(this.chartData)
+    const rects = bars
+      .enter()
+      .append('rect')
+      .attr('style', (d, i) =>
+        this._isStarred(d, i)
+          ? css(this.props.styles.barStar).styles
+          : css(this.props.styles.bar).styles,
+      )
+      .attr('class', (d, i) => (this._isStarred(d, i) ? 'barStar' : 'bar'))
+      .attr('x', (d, i) => {
+        return x(i)
+      })
+      .attr('width', x.bandwidth())
+    this.applyTransition(
+      rects,
+      rects => {
+        return rects.attr('y', height).attr('height', 0)
+      },
+      rects => {
+        return rects.attr('y', y).attr('height', d => {
+          return height - y(d)
+        })
+      },
+    )
+
+    bars.exit().remove()
+  }
+
+  _isStarred = (d, i) => {
+    return typeof this.props.starIndex === 'number' && i === this.props.starIndex
+  }
+
+  _renderStar = svg => {
+    if (typeof this.props.starIndex !== 'number') return
+
+    const star = svg
+      .append('path')
+      .attr('d', starPathData)
+      .attr('style', css(this.props.styles.barStar).styles)
+
+    const starIndex = this.props.starIndex
+    const starX = this.x(starIndex) + this.x.bandwidth() / 2
+    const starY = this.y(this.props.visualDistribution[starIndex]) - 30
+    // scale the star down and position it on the x axis - y axis will be applied by animation
+    const xTransform = `translate(${starX} 0) scale(0.011) translate(-960 0)`
+    this.applyTransition(
+      star,
+      rects =>
+        rects.attr('opacity', 0).attr('transform', `translate(0 ${starY + 20}) ${xTransform}`),
+      rects => rects.attr('opacity', 1).attr('transform', `translate(0 ${starY}) ${xTransform}`),
+      transition => transition.delay(this.props.animateDuration).duration(600),
+    )
+  }
+
+  getTransition() {
+    this.transition =
+      this.transition ||
+      transition()
+        .delay(this.props.animateDelay || 0)
+        .duration(this.props.animateDuration || 0)
+    return this.transition
+  }
+
+  applyTransition = (selection, initialFunc, finalFunc, transitionFunc) => {
+    const identity = s => {
+      return s
+    }
+    const transition = s => s.transition(this.getTransition())
+
+    const applicators = []
+    if (this.isAnimated()) {
+      applicators.push(initialFunc || identity, transition, transitionFunc || identity)
+    }
+    applicators.push(finalFunc || identity)
+
+    return flow(applicators)(selection)
+  }
+
+  renderSummary() {
+    return <ScreenReaderContent>{this.summarizeChart()}</ScreenReaderContent>
+  }
+
+  setChartRef = ref => {
+    this.chart = ref
+  }
+
+  render() {
+    const {chartWidth, chartHeight} = this.props
+    const viewportHeight = chartHeight + MARGIN_T + MARGIN_B
+
+    // IE11 sizes svg elements incorrectly, so we render a canvas element to
+    // layout space for the chart, then position the svg absolute on top of it.
+    return (
+      <div>
+        <PresentationContent as="div">
+          <div style={{position: 'relative'}}>
+            <canvas
+              width={chartWidth}
+              height={viewportHeight}
+              style={{display: 'block', visibility: 'hidden'}}
+            />
+            <svg ref={this.setChartRef} style={{position: 'absolute', top: 0, left: 0}} />
+          </div>
+        </PresentationContent>
+        {this.renderSummary()}
+        {this.props.renderTable()}
+      </div>
+    )
+  }
+}
+/**
+ *   A component to render an a11y friendly distribution of scores across users.
+ *   Underneath the chart is two accessible features:
+ *     1. A keyboard friendly set of min(10, bucketCounts) buckets {0-10%, 10-20%, ..., 90-100%}
+ *     with the number of users in that slice
+ *     2. A screenreader-only block of content providing a table version of all the data
+ *
+ *     ```jsx_example
+ *      <Distribution
+ *        summaryDistribution={Array.from({length: 10}, () => Math.floor(Math.random() * 5))}
+ *        visualDistribution={Array.from({length: 101}, () => Math.floor(Math.random() * 5))}
+ *      />
+ *      ```
+ *  **/
+export default Distribution

package/src/reporting/components/charts/Distribution/styles.js

@@ -0,0 +1,26 @@
+const generateStyle = componentTheme => {
+  return {
+    bar: {
+      fill: componentTheme.barFillColor,
+    },
+
+    barStar: {
+      fill: componentTheme.barStarFillColor,
+    },
+
+    barContainer: {},
+
+    xAxis: {
+      color: componentTheme.xAxisColor,
+    },
+
+    barLabel: {
+      color: componentTheme.barLabelColor,
+      fontFamily: componentTheme.barLabelFontFamily,
+      fontSize: componentTheme.barLabelFontSize,
+      textAnchor: 'middle',
+    },
+  }
+}
+
+export default generateStyle

package/src/reporting/components/charts/Distribution/theme.js

@@ -0,0 +1,12 @@
+const generateComponentTheme = ({colors, typography}) => {
+  return {
+    barFillColor: colors.contrasts.blue4570,
+    barStarFillColor: colors.contrasts.orange4570,
+    barLabelColor: colors.contrasts.grey125125,
+    barLabelFontFamily: typography.fontFamily,
+    barLabelFontSize: typography.fontSizeSmall,
+    xAxisColor: colors.contrasts.grey125125,
+  }
+}
+
+export default generateComponentTheme

package/src/reporting/components/charts/Legend/README.md

@@ -0,0 +1,62 @@
+---
+category: components
+name: Legend
+---
+
+Legend renders a collection of labels and color swatches to accompany a chart.
+The `series` prop expects an array of objects with `label` and `className`
+keys. `className` will be applied to the swatch div element to style it.
+
+```jsx_example
+function Example () {
+  return (
+    <div>
+      <style dangerouslySetInnerHTML={{__html: `
+        .oneClass { background: repeating-linear-gradient(
+          90deg,
+          transparent, transparent 37%, grey 37%, grey 63%
+        ); }
+        .twoClass { background: repeating-linear-gradient(
+          90deg,
+          transparent -12%, transparent 12%, grey 12%, grey 37%
+        ); }
+      `}} />
+      <Legend series={[
+        { className: 'oneClass', label: 'One Fish' },
+        { className: 'twoClass', label: 'Two Fish' }
+      ]} />
+    </div>
+  )
+}
+
+<LocaleSwitcher locales={LOCALES}>
+  <Example />
+</LocaleSwitcher>
+```
+
+Set `variant="row"` to arrange the series in a row instead of column. The row
+variant has no border style.
+
+```jsx_example
+function Example () {
+  return (
+    <div>
+      <style dangerouslySetInnerHTML={{__html: `
+        .redClass { background-color: red; }
+        .blueClass { background-color: blue; }
+      `}} />
+      <Legend
+        series={[
+          { className: 'redClass', label: 'Red Fish' },
+          { className: 'blueClass', label: 'Blue Fish' }
+        ]}
+        variant="row"
+      />
+    </div>
+  )
+}
+
+<LocaleSwitcher locales={LOCALES}>
+  <Example />
+</LocaleSwitcher>
+```

package/src/reporting/components/charts/Legend/__tests__/index.test.js

@@ -0,0 +1,39 @@
+import React from 'react'
+import {render, screen} from '../../../../../../tests/util/rtlRenderOverride'
+
+import Legend from '../index'
+import {expect} from 'vitest'
+
+describe('Legend', () => {
+  const testStyleObjectRed = {
+    div: {
+      color: 'red',
+    },
+  }
+  const testStyleObjectBlue = {
+    div: {
+      color: 'blue',
+    },
+  }
+
+  const defaultProps = {
+    series: [
+      {customStyles: testStyleObjectRed, label: 'Red'},
+      {customStyles: testStyleObjectBlue, label: 'Blue'},
+    ],
+  }
+
+  it('renders each series', () => {
+    const {container} = render(<Legend {...defaultProps} />)
+    const series = container.querySelectorAll('.seriesContainer')
+    expect(series).toHaveLength(2)
+    expect(screen.getByText('Red')).toBeDefined()
+    expect(screen.getByText('Blue')).toBeDefined()
+  })
+
+  it('applies containerRow class to row variant', () => {
+    const {container} = render(<Legend {...defaultProps} variant="row" />)
+    const series = container.querySelectorAll('.containerRow .seriesContainer')
+    expect(series).toHaveLength(2)
+  })
+})

package/src/reporting/components/charts/Legend/index.js

@@ -0,0 +1,66 @@
+/** @jsx jsx */
+import {Component} from 'react'
+import PropTypes from 'prop-types'
+import {PresentationContent} from '@instructure/ui-a11y-content'
+
+import {jsx} from '@instructure/emotion'
+import generateStyle from './styles'
+import generateComponentTheme from './theme'
+import {withStyleOverrides} from '@instructure/quiz-common/util/withStyleOverrides'
+
+@withStyleOverrides(generateStyle, generateComponentTheme)
+export class Legend extends Component {
+  static displayName = 'Legend'
+  static componentId = `Quizzes${this.displayName}`
+
+  static propTypes = {
+    series: PropTypes.arrayOf(
+      PropTypes.shape({
+        label: PropTypes.string.isRequired,
+        customStyles: PropTypes.object.isRequired,
+      }),
+    ),
+    variant: PropTypes.oneOf(['column', 'row']),
+    makeStyles: PropTypes.func,
+    styles: PropTypes.object,
+  }
+
+  static defaultProps = {
+    series: [],
+    variant: 'column',
+  }
+
+  componentDidMount() {
+    this.props.makeStyles()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles()
+  }
+
+  renderSeries(series, index, styles) {
+    const customStyles = series.customStyles ? series.customStyles : {}
+    return (
+      <div key={index} className="seriesContainer" css={styles.seriesContainer}>
+        <div css={styles.seriesSwatchContainer}>
+          <div css={{...styles.seriesSwatch, ...customStyles}} />
+        </div>
+        <div css={styles.seriesLabel}>{series.label}</div>
+      </div>
+    )
+  }
+
+  render() {
+    const {variant, series, styles} = this.props
+    const containerClass = variant === 'row' ? 'containerRow' : 'containerColumn'
+    return (
+      <PresentationContent>
+        <div className={containerClass} css={styles.containerStyle}>
+          {series.map((s, i) => this.renderSeries(s, i, styles))}
+        </div>
+      </PresentationContent>
+    )
+  }
+}
+
+export default Legend

package/src/reporting/components/charts/Legend/styles.js

@@ -0,0 +1,44 @@
+const generateStyle = (componentTheme, props) => {
+  const containerVariant = {
+    row: {
+      margin: `0 calc(-1 * ${componentTheme.seriesContainerRowMargin})`,
+      '.seriesContainer': {
+        display: 'inline-flex',
+        padding: `0 ${componentTheme.seriesContainerRowMargin}`,
+      },
+    },
+    column: {
+      border: `${componentTheme.containerBorderWidth} solid ${componentTheme.containerBorderColor}`,
+      '.seriesContainer': {
+        display: 'flex',
+      },
+    },
+  }
+  return {
+    seriesContainer: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      margin: componentTheme.seriesContainerMargin,
+    },
+    containerStyle: {
+      ...containerVariant[props.variant],
+    },
+    seriesSwatchContainer: {
+      width: '1.2rem',
+      height: '1.2rem',
+      marginRight: componentTheme.seriesSwatchMargin,
+      display: 'flex',
+    },
+    seriesSwatch: {
+      flex: 1,
+    },
+    seriesLabel: {
+      fontFamily: componentTheme.seriesLabelFontFamily,
+      fontSize: componentTheme.seriesLabelFontSize,
+      whiteSpace: 'nowrap',
+      color: componentTheme.seriesLabelColor,
+    },
+  }
+}
+
+export default generateStyle

package/src/reporting/components/charts/Legend/theme.js

@@ -0,0 +1,15 @@
+const generateComponentTheme = ({borders, spacing, colors, typography}) => {
+  return {
+    containerBorderWidth: borders.widthSmall,
+    containerBorderColor: colors.contrasts.grey1214,
+    seriesContainerMargin: spacing.small,
+    seriesContainerRowMargin: spacing.medium,
+    seriesSwatchMargin: spacing.small,
+    seriesSwatchBackgroundColor: colors.contrasts.blue4570,
+    seriesLabelFontFamily: typography.fontFamily,
+    seriesLabelFontSize: typography.fontSizeXSmall,
+    seriesLabelColor: colors.contrasts.grey125125,
+  }
+}
+
+export default generateComponentTheme

package/src/reporting/components/charts/QuintileDistribution/__tests__/index.test.js

@@ -0,0 +1,9 @@
+import QuintileDistribution from '../index'
+import QuintileDistributionPresenter from '../presenter'
+import {expect} from 'vitest'
+
+describe('QuintileDistribution', () => {
+  it('exports QuintileDistributionPresenter', () => {
+    expect(QuintileDistribution).toBe(QuintileDistributionPresenter)
+  })
+})