@brightspace-ui/labs 2.16.0 → 2.18.0

package/package.json

@@ -83,5 +83,5 @@
     "@lit/context": "^1.1.3",
     "lit": "^3"
   },
-  "version": "2.16.0"
+  "version": "2.18.0"
 }

package/src/components/grade-result/README.md

@@ -0,0 +1,85 @@
+# @d2l/labs-grade-result
+
+A web component used for rendering grades in Brightspace
+
+## Properties
+
+#### d2l-labs-d2l-grade-result
+
+| Property                          | Type      | Default     | Description                                                  |
+| ----------------------------------| --------- | -------     | ------------------------------------------------------------ |
+| `href`                            | `string`  | `''`        | The Hypermedia route to power the component. This component runs off of the /grade route or an activity. |
+| `token`                           | `string`  | `''`        | For authentication                                           |
+| `disableAutoSave`                 | `boolean` | `false`     | Prevent the component from automatically saving the grade to the API when the grade is changed. |
+| `_hideTitle`                      | `boolean` | `false`     | This property will hide the "Overall Grade" title above the component. |
+| `customManualOverrideText`        | `string`  | `undefined` | This properly will substitute the stock text on the "Manual Override" button. |
+| `customManualOverrideClearText`   | `string`  | `undefined` | This properly will substitute the stock text on the "Clear Manual Override" button. |
+
+##### Public Methods
+
+| Method                         | Description                                                  |
+| ------------------------------ | ------------------------------------------------------------ |
+| `saveGrade(): void`            | This is the method used to manually save the grade to the server when `disableAutoSave = true`. This method will emit `@d2l-grade-result-grade-saved-success` or `@d2l-grade-result-grade-saved-error`. |
+| `hasUnsavedChanges(): boolean` | Determines whether the grade has been changed by the user and has not been saved to the server yet. |
+
+If you are only interested in rendering the presentational layer of the component, you can simply use the `d2l-grade-result-presentational` component.
+
+#### d2l-labs-d2l-grade-result-presentational
+
+| Property                          | GradeType      | Type                        | Default     | Description                                                  |
+| ----------------------------------| -------------- | --------------------------- | ----------- | ------------------------------------------------------------ |
+| `gradeType`                       | All            | `string ('Numeric' or 'LetterGrade')` | `'Numeric'` | Specifies the type of grade that the component is meant to render. |
+| `labelText`                       | All            | `string`                    | `''`        | The text that appears above the component.                   |
+| `scoreNumerator`                  | Numeric        | `number`                    | `0`         | The numerator of the numeric score that is given.            |
+| `scoreDenominator`                | Numeric        | `number`                    | `0`         | The denominator of the numeric score that is given.          |
+| `selectedLetterGrade`             | LetterGrade    | `string`                    | `''`        | The current selected letter grade of the options given.      |
+| `letterGradeOptions`              | LetterGrade    | `Object`                    | `null`      | A dictionary where the key is a unique id and the value is an object containing the LetterGrade text and the PercentStart. |
+| `includeGradeButton`              | All            | `boolean`                   | `false`     | Determines whether the grades icon button is rendered.       |
+| `includeReportsButton`            | All            | `boolean`                   | `false`     | Determines whether the reports icon button is rendered.      |
+| `gradeButtonTooltip`              | All            | `string`                    | `''`        | The text that is inside of the tooltip when hovering over the grades button. |
+| `reportsButtonTooltip`            | All            | `string`                    | `''`        | The text that is inside of the tooltip when hovering over the reports button. |
+| `readOnly`                        | All            | `boolean`                   | `false`     | Set to `true` if the user does not have permissions to edit the grade. |
+| `isManualOverrideActive`          | All            | `boolean`                   | `false`     | Set to `true` if the user is currently manually overriding the grade. This will display the button to 'Clear Manual Override'. |
+| `hideTitle`                       | All            | `boolean`                   | `false`     | This property will hide the "Overall Grade" title above the component. |
+| `customManualOverrideClearText`   | All            | `string`                    | `undefined` | This property will substitute the stock text on the "Clear Manual Override" button. |
+| `subtitleText`                    | All            | `string`                    | `undefined` | This property will show the given text under the title. |
+| `required`                 | Numeric        | `Boolean`                    | `false` | Set to `true` if an undefined/blank grade is not considered valid |
+| `inputLabelText`                 | Numeric        | `string`                    | `''` |  This property sets the label that will be used inside the aria-label and validation error tool-tips |
+| `allowNegativeScore`             | Numeric        | `boolean`                    | `'false'`   | Set to `true` if negative scores can be entered                         |
+| `showFlooredScoreWarning`        | Numeric        | `boolean`                    | `'false'`   | Set to `true` if displaying a negative grade that has been floored at 0 |
+
+## Events
+
+#### d2l-labs-d2l-grade-result
+
+| Event                                           | Description                                                  |
+| ----------------------------------------------- | ------------------------------------------------------------ |
+| `@d2l-grade-result-initialized-success`         | This event is fired when the component is successfully initialized and a grade is loaded from the API. |
+| `@d2l-grade-result-initialized-error`           | This event is fired when there is an error initializing the component. This is usually caused by an invalid `href` or `token`. |
+| `@d2l-grade-result-grade-updated-success`       | This event is fired when the grade is successfully updated on the frontend. |
+| `@d2l-grade-result-grade-updated-error`         | This event is fired when there is an error updating the grade on the frontend. |
+| `@d2l-grade-result-grade-saved-success`         | This event is fired when the grade is successfully saved to the server. |
+| `@d2l-grade-result-grade-saved-error`           | This event is fired when there is an error while saving the grade to the server. |
+| `@d2l-grade-result-grade-button-click`          | This event is fired when the grades button is clicked.       |
+| `@d2l-grade-result-reports-button-click`        | This event is fired when the reports button is clicked.      |
+| `@d2l-grade-result-manual-override-clear-click` | This event is fired when the manual override clear is clicked. |
+
+#### d2l-labs-d2l-grade-result-presentational
+
+| Event                                           | Description                                                  |
+| ----------------------------------------------- | ------------------------------------------------------------ |
+| `@d2l-grade-result-grade-button-click`          | This event is fired when the grades button is clicked.       |
+| `@d2l-grade-result-reports-button-click`        | This event is fired when the reports button is clicked.      |
+| `@d2l-grade-result-grade-change`                | This event is fired on the change of the grade for a `gradeType="Numeric"` grade. |
+| `@d2l-grade-result-letter-score-selected`       | This event is fired on the change of the grade for a `gradeType="LetterGrade"` grade. |
+| `@d2l-grade-result-manual-override-clear-click` | This event is fired when the manual override clear is clicked. |
+
+
+## Usage
+
+```html
+<script type="module">
+    import '@d2l/labs-grade-result/d2l-grade-result.js';
+</script>
+<d2l-labs-d2l-grade-result href="href" token="token" disableAutoSave _hideTitle>My element</d2l-labs-d2l-grade-result>
+```

package/src/components/grade-result/grade-result-icon-button.js

@@ -0,0 +1,38 @@
+import '@brightspace-ui/core/components/button/button-icon.js';
+import { html, LitElement } from 'lit';
+import { getUniqueId } from '@brightspace-ui/core/helpers/uniqueId.js';
+
+export class D2LGradeResultIconButton extends LitElement {
+	static get properties() {
+		return {
+			text: { type: String },
+			icon: { type: String },
+			_id: { type: String },
+		};
+	}
+
+	constructor() {
+		super();
+		this._id = getUniqueId();
+	}
+
+	render() {
+		return html`
+			<d2l-button-icon
+				id="d2l-grade-result-icon-button-${this._id}"
+				icon="${this.icon}"
+				@click="${this._onClick}"
+				text="${this.text}"
+			></d2l-button-icon>
+		`;
+	}
+
+	_onClick() {
+		this.dispatchEvent(new CustomEvent('d2l-grade-result-icon-button-click', {
+			bubbles: true,
+			composed: true,
+		}));
+	}
+
+}
+customElements.define('d2l-grade-result-icon-button', D2LGradeResultIconButton);

package/src/components/grade-result/grade-result-letter-score.js

@@ -0,0 +1,91 @@
+import { css, html, LitElement } from 'lit';
+import { bodyStandardStyles } from '@brightspace-ui/core/components/typography/styles.js';
+import { LocalizeLabsElement } from '../localize-labs-element.js';
+import { selectStyles } from '@brightspace-ui/core/components/inputs/input-select-styles.js';
+
+export class D2LGradeResultLetterScore extends LocalizeLabsElement(LitElement) {
+
+	static get properties() {
+		return {
+			availableOptions: { type: Object },
+			label: { type: String },
+			selectedOption: { type: String },
+			readOnly: { type: Boolean }
+		};
+	}
+
+	static get styles() {
+		return [selectStyles, bodyStandardStyles, css`
+			.d2l-grade-result-letter-score-container {
+				width: 8rem;
+			}
+			.d2l-grade-result-letter-score-select {
+				width: 100%;
+			}
+			.d2l-grade-result-letter-score-score-read-only {
+				height: calc(2rem + 2px);
+				line-height: calc(2rem + 2px);
+			}
+		`];
+	}
+
+	constructor() {
+		super();
+		this.availableOptions = null;
+		this.selectedOption = '';
+	}
+
+	render() {
+		if (!this.readOnly) {
+			return html`
+				<div class="d2l-grade-result-letter-score-container">
+					<select
+						id="d2l-grade"
+						aria-label=${this.label ? this.label : this.localize('components:gradeResult:gradeScoreLabel')}
+						class="d2l-input-select d2l-grade-result-letter-score-select"
+						@change=${this._onOptionSelected}
+						.value=${this.selectedOption}>
+						${this._renderOptions()}
+					</select>
+				</div>
+			`;
+		} else {
+			return html`
+				<div class="d2l-grade-result-letter-score-score-read-only">
+					<span id="d2l-grade" class="d2l-body-standard">${this._selectedOptionText()}</span>
+				</div>
+			`;
+		}
+	}
+
+	_onOptionSelected(e) {
+		this.dispatchEvent(new CustomEvent('d2l-grade-result-letter-score-selected', {
+			composed: true,
+			bubbles: true,
+			detail: {
+				value: e.target.value
+			}
+		}));
+	}
+
+	_renderOptions() {
+		const itemTemplate = [];
+		for (const [id, option] of Object.entries(this.availableOptions)) {
+			if (this.selectedOption === id) {
+				itemTemplate.push(html`<option selected value=${id}>${option.LetterGrade}</option>`);
+			} else {
+				itemTemplate.push(html`<option value=${id}>${option.LetterGrade}</option>`);
+			}
+		}
+		return itemTemplate;
+	}
+
+	_selectedOptionText() {
+		if (this.availableOptions[this.selectedOption]) {
+			return this.availableOptions[this.selectedOption].LetterGrade;
+		}
+	}
+
+}
+
+customElements.define('d2l-grade-result-letter-score', D2LGradeResultLetterScore);

package/src/components/grade-result/grade-result-numeric-score.js

@@ -0,0 +1,108 @@
+import '@brightspace-ui/core/components/inputs/input-number.js';
+import '@brightspace-ui/core/components/offscreen/offscreen.js';
+import { bodyCompactStyles, bodyStandardStyles } from '@brightspace-ui/core/components/typography/styles.js';
+import { css, html, LitElement, nothing } from 'lit';
+import { LocalizeLabsElement } from '../localize-labs-element.js';
+
+const numberConverter = {
+	fromAttribute: (attr) => { return !attr ? undefined : Number(attr); },
+	toAttribute:  (prop) => { return String(prop); }
+};
+
+const EXTRA_SPACE = 2.5;
+const MIN_WIDTH = 5.5;
+const MIN_NEGATIVE_GRADE = -9999999999;
+const MIN_POSITIVE_GRADE = 0;
+
+export class D2LGradeResultNumericScore extends LocalizeLabsElement(LitElement) {
+	static get properties() {
+		return {
+			label: { type: String },
+			scoreNumerator: { type: Number, converter: numberConverter },
+			scoreDenominator: { type: Number },
+			readOnly: { type: Boolean },
+			required: { type: Boolean },
+			allowNegativeScore: { type: Boolean },
+			showFlooredScoreWarning: { type: Boolean },
+		};
+	}
+
+	static get styles() {
+		return [bodyCompactStyles, bodyStandardStyles, css`
+			.d2l-grade-result-numeric-score-container {
+				align-items: center;
+				display: flex;
+				flex-direction: row;
+			}
+			.d2l-grade-result-numeric-score-score-read-only {
+				height: calc(2rem + 2px);
+				line-height: calc(2rem + 2px);
+				max-width: 5.25rem;
+			}
+			.d2l-grade-result-numeric-score-hint {
+				margin: 0 0.3rem;
+			}
+		`];
+	}
+
+	render() {
+		const roundedNumerator = isNaN(this.scoreNumerator) ? '' : Math.round((this.scoreNumerator + Number.EPSILON) * 100) / 100;
+
+		const denominatorLength = isNaN(this.scoreDenominator) ? 0 : this.scoreDenominator.toString().length;
+		const numeratorLength = roundedNumerator.toString().length;
+		const dynamicWidth = numeratorLength <= denominatorLength ? denominatorLength + EXTRA_SPACE : (numeratorLength * 0.5) + (denominatorLength * 0.5) + EXTRA_SPACE;
+
+		return html`
+			<div class="d2l-grade-result-numeric-score-container">
+				${!this.readOnly ? html`
+					<div class="d2l-grade-result-numeric-score-score">
+						<d2l-form>
+							<d2l-input-number
+								?required=${this.required}
+								id="d2l-grade"
+								label=${this.label ? this.label : this.localize('components:gradeResult:gradeScoreLabel')}
+								label-hidden
+								value="${this.scoreNumerator}"
+								input-width="${dynamicWidth > MIN_WIDTH ? dynamicWidth : MIN_WIDTH}rem"
+								min="${this.allowNegativeScore ? MIN_NEGATIVE_GRADE : MIN_POSITIVE_GRADE}"
+								max="9999999999"
+								max-fraction-digits="2"
+								unit="/ ${this.scoreDenominator}"
+								unit-label=${this.localize('components:gradeResult:outOfDenominator', { denominator: this.scoreDenominator })}
+								value-align="end"
+								@change=${this._onGradeChange}
+							></d2l-input-number>
+						</d2l-form>
+					</div>
+				` : html`
+					<div
+						aria-hidden="true"
+						class="d2l-body-standard d2l-grade-result-numeric-score-score-read-only"
+						id="d2l-grade">
+						${roundedNumerator} / ${this.scoreDenominator}
+					</div>
+					<d2l-offscreen>${this.localize('components:gradeResult:numeratorOutOfDenominator', { numerator: roundedNumerator, denominator: this.scoreDenominator })}</d2l-offscreen>
+				`}
+				${this.showFlooredScoreWarning ? html`
+					<div class="d2l-grade-result-numeric-score-hint d2l-body-compact">
+						${this.localize('components:gradeResult:cannotBeNegative')}
+					</div>
+				` : nothing}
+			</div>
+		`;
+	}
+
+	_onGradeChange(e) {
+		const newScore = e.target.value;
+		this.dispatchEvent(new CustomEvent('d2l-grade-result-grade-change', {
+			bubbles: true,
+			composed: true,
+			detail: {
+				value: newScore
+			}
+		}));
+	}
+
+}
+
+customElements.define('d2l-grade-result-numeric-score', D2LGradeResultNumericScore);

package/src/components/grade-result/grade-result-presentational.js

@@ -0,0 +1,253 @@
+import './grade-result-icon-button.js';
+import './grade-result-numeric-score.js';
+import './grade-result-letter-score.js';
+import './grade-result-student-grade-preview.js';
+import '@brightspace-ui/core/components/button/button-subtle.js';
+import { bodySmallStyles, labelStyles } from '@brightspace-ui/core/components/typography/styles.js';
+import { css, html, LitElement, nothing } from 'lit';
+import { GradeType } from '../../controllers/grade-result/Grade.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
+import { LocalizeLabsElement } from '../localize-labs-element.js';
+
+const numberConverter = {
+	fromAttribute: (attr) => { return !attr ? undefined : Number(attr); },
+	toAttribute:  (prop) => { return String(prop); }
+};
+
+export class D2LGradeResultPresentational extends LocalizeLabsElement(LitElement) {
+	static get properties() {
+		return {
+			allowNegativeScore: { type: Boolean },
+			customManualOverrideClearText: { type: String },
+			displayStudentGradePreview: { type: Boolean, attribute: 'display-student-grade-preview' },
+			gradeButtonTooltip: { type: String },
+			gradeType: { type: String },
+			hideTitle: { type: Boolean },
+			includeGradeButton: { type: Boolean },
+			includeReportsButton: { type: Boolean },
+			inputLabelText: { type: String },
+			isManualOverrideActive: { type: Boolean },
+			labelHeadingLevel: { type: Number },
+			labelText: { type: String },
+			letterGradeOptions: { type: Object },
+			readOnly: { type: Boolean },
+			reportsButtonTooltip: { type: String },
+			required: { type: Boolean },
+			scoreDenominator: { type: Number },
+			scoreNumerator: { type: Number, converter: numberConverter },
+			selectedLetterGrade: { type: String },
+			showFlooredScoreWarning: { type: Boolean },
+			subtitleText: { type: String },
+			studentGradePreview: { type: Object, attribute: 'student-grade-preview' },
+		};
+	}
+
+	static get styles() {
+		return [ bodySmallStyles, labelStyles, css`
+			.d2l-grade-result-presentational-container {
+				display: flex;
+				flex-wrap: wrap;
+				gap: 0 0.9rem;
+			}
+			.d2l-grade-result-presentational-score-container {
+				display: flex;
+				flex-wrap: wrap;
+				gap: 0.3rem;
+			}
+			.d2l-grade-result-manual-override-clear {
+				margin-top: 0.3rem;
+			}
+			.d2l-label-text {
+				line-height: 1.6rem;
+				margin-bottom: 0.4rem;
+			}
+			.d2l-grade-result-presentational-subtitle {
+				font-weight: bold;
+				margin-top: -4px;
+			}
+		`];
+	}
+
+	constructor() {
+		super();
+		this.allowNegativeScore = false;
+		this.customManualOverrideClearText = undefined;
+		this.hideTitle = false;
+		this.includeGradeButton = false;
+		this.includeReportsButton = false;
+		this.isManualOverrideActive = false;
+		this.labelHeadingLevel = undefined;
+		this.readOnly = false;
+		this.selectedLetterGrade = '';
+		this.showFlooredScoreWarning = false;
+		this.subtitleText = undefined;
+	}
+
+	render() {
+		return html`
+			<div class="d2l-grade-result-presentational-container">
+				<div>
+					${this._renderScoreLabel()}
+					${this._renderScoreSubtitle()}
+					<div class="d2l-grade-result-presentational-score-container">
+						${this._renderScoreComponent()}
+						${this._renderGradeIconButton()}
+						${this._renderGradeReportIconButton()}
+					</div>
+				</div>
+				${this._renderStudentGradePreview()}
+			</div>
+			${this._renderManualOverrideButtonComponent()}
+		`;
+	}
+
+	_isReadOnly() {
+		return Boolean(this.readOnly);
+	}
+
+	_onGradeButtonClick() {
+		this.dispatchEvent(new CustomEvent('d2l-grade-result-grade-button-click', {
+			bubbles: true,
+			composed: true,
+		}));
+	}
+
+	_onManualOverrideClearClick() {
+		this.dispatchEvent(new CustomEvent('d2l-grade-result-manual-override-clear-click', {
+			bubbles: true,
+			composed: true
+		}));
+	}
+
+	_onReportsButtonClick() {
+		this.dispatchEvent(new CustomEvent('d2l-grade-result-reports-button-click', {
+			bubbles: true,
+			composed: true,
+		}));
+	}
+
+	_renderGradeIconButton() {
+		if (!this.includeGradeButton) {
+			return nothing;
+		}
+
+		return html`
+			<d2l-grade-result-icon-button
+				icon="tier1:grade"
+				text=${this.gradeButtonTooltip}
+				@d2l-grade-result-icon-button-click=${this._onGradeButtonClick}
+			></d2l-grade-result-icon-button>
+		`;
+	}
+
+	_renderGradeReportIconButton() {
+		if (!this.includeReportsButton) {
+			return nothing;
+		}
+
+		return html`
+			<d2l-grade-result-icon-button
+				icon="tier1:reports"
+				text=${this.reportsButtonTooltip}
+				@d2l-grade-result-icon-button-click=${this._onReportsButtonClick}
+			></d2l-grade-result-icon-button>
+		`;
+	}
+
+	_renderLetterScoreComponent() {
+		return html`
+			<d2l-grade-result-letter-score
+				.availableOptions=${this.letterGradeOptions}
+				.label=${this.inputLabelText}
+				.readOnly=${this._isReadOnly()}
+				.selectedOption=${this.selectedLetterGrade}
+			></d2l-grade-result-letter-score>
+		`;
+	}
+
+	_renderManualOverrideButtonComponent() {
+		if (!this.isManualOverrideActive) {
+			return nothing;
+		}
+
+		const text = this.customManualOverrideClearText ? this.customManualOverrideClearText : this.localize('components:gradeResult:clearManualOverride');
+
+		return html`
+			<d2l-button-subtle
+				class="d2l-grade-result-manual-override-clear"
+				icon="tier1:close-default"
+				text=${text}
+				@click=${this._onManualOverrideClearClick}
+			></d2l-button-subtle>
+		`;
+	}
+
+	_renderNumericScoreComponent() {
+		return html`
+			<d2l-grade-result-numeric-score
+				?allowNegativeScore=${this.allowNegativeScore}
+				.label=${this.inputLabelText}
+				.readOnly=${this._isReadOnly()}
+				?required=${this.required}
+				.scoreDenominator=${this.scoreDenominator}
+				.scoreNumerator=${this.scoreNumerator}
+				?showFlooredScoreWarning=${this.showFlooredScoreWarning}
+			></d2l-grade-result-numeric-score>
+		`;
+	}
+
+	_renderScoreComponent() {
+		if (this.gradeType === GradeType.Number) {
+			return this._renderNumericScoreComponent();
+		} else if (this.gradeType === GradeType.Letter) {
+			return this._renderLetterScoreComponent();
+		} else {
+			throw new Error('INVALID GRADE TYPE PROVIDED');
+		}
+	}
+
+	_renderScoreLabel() {
+		if (this.hideTitle || !this.labelText) {
+			return nothing;
+		}
+
+		return html`
+			<label
+				aria-level=${ifDefined(this.labelHeadingLevel)}
+				class="d2l-label-text"
+				for="d2l-grade"
+				role=${this.labelHeadingLevel ? 'heading' : ''}>
+				${this.labelText}
+			</label>
+		`;
+	}
+
+	_renderScoreSubtitle() {
+		if (!this.subtitleText) {
+			return nothing;
+		}
+
+		return html`
+			<div class="d2l-grade-result-presentational-subtitle d2l-body-small">
+				${this.subtitleText}
+			</div>
+		`;
+	}
+
+	_renderStudentGradePreview() {
+		if (!this.studentGradePreview) {
+			return nothing;
+		}
+
+		return html`
+			<d2l-grade-result-student-grade-preview
+				?hidden=${!this.displayStudentGradePreview}
+				out-of=${this.scoreDenominator}
+				.studentGradePreview=${this.studentGradePreview}
+			></d2l-grade-result-student-grade-preview>
+		`;
+	}
+
+}
+
+customElements.define('d2l-labs-d2l-grade-result-presentational', D2LGradeResultPresentational);

package/src/components/grade-result/grade-result-student-grade-preview.js

@@ -0,0 +1,139 @@
+import '@brightspace-ui/core/components/offscreen/offscreen.js';
+import { bodyCompactStyles, bodySmallStyles, labelStyles } from '@brightspace-ui/core/components/typography/styles.js';
+import { css, html, LitElement, nothing } from 'lit';
+import { formatNumber } from '@brightspace-ui/intl/lib/number.js';
+import { LocalizeLabsElement } from '../localize-labs-element.js';
+
+const previewOptions = {
+	colour: 'colour',
+	score: 'score',
+	symbol: 'symbol'
+};
+
+export class D2LGradeResultStudentGradePreview extends LocalizeLabsElement(LitElement) {
+
+	static get properties() {
+		return {
+			hideLabel: {
+				type: Boolean,
+				attribute: 'hide-label'
+			},
+			outOf: {
+				type: Number,
+				attribute: 'out-of'
+			},
+			studentGradePreview: {
+				type: Object,
+				attribute: 'student-grade-preview'
+			}
+		};
+	}
+
+	static get styles() {
+		return [bodySmallStyles, bodyCompactStyles, labelStyles, css`
+			:host {
+				display: inline-block;
+			}
+			:host([hidden]) {
+				display: none;
+			}
+			.d2l-grade-result-student-grade-preview-container {
+				align-items: center;
+				display: flex;
+				flex-direction: row;
+				gap: 0.5rem;
+				min-height: calc(2rem + 2px);
+			}
+			.d2l-grade-result-student-grade-preview-colour {
+				border-radius: 6px;
+				height: 0.9rem;
+				width: 0.9rem;
+			}
+			.d2l-label-text {
+				line-height: 1.6rem;
+				margin-bottom: 0.4rem;
+			}
+		`];
+	}
+
+	constructor() {
+		super();
+		this.hideLabel = false;
+	}
+
+	render() {
+		if (!this.studentGradePreview) {
+			return nothing;
+		}
+
+		let label = nothing;
+		if (!this.hideLabel) {
+			label = html`
+				<label class="d2l-label-text d2l-skeletize" for="d2l-grade-result-student-grade-preview">
+					${this.localize('components:gradeResult:studentGradePreviewLabel')}
+				</label>
+			`;
+		}
+
+		const shouldDisplayAny = Object.values(previewOptions).some(option => this._shouldDisplay(option));
+		if (!shouldDisplayAny) {
+			return html`
+				${label}
+				<div class="d2l-body-small d2l-grade-result-student-grade-preview-container" id="d2l-grade-result-student-grade-preview">
+					${this.localize('components:gradeResult:studentGradePreviewNotShown')}
+				</div>
+			`;
+		}
+
+		return html`
+			${label}
+			<div id="d2l-grade-result-student-grade-preview" class="d2l-grade-result-student-grade-preview-container">
+				${this._renderColour()}
+				${this._renderScoreAndSymbol()}
+			</div>
+		`;
+	}
+
+	_renderColour()	{
+		if (!this._shouldDisplay(previewOptions.colour) || !this.studentGradePreview.colour) {
+			return nothing;
+		}
+
+		return html`
+			<div class="d2l-grade-result-student-grade-preview-colour"
+				style="background-color: ${this.studentGradePreview.colour};">
+			</div>
+		`;
+	}
+
+	_renderScoreAndSymbol() {
+		if (!this._shouldDisplay(previewOptions.score) && !this._shouldDisplay(previewOptions.symbol)) {
+			return nothing;
+		}
+
+		const score = this._shouldDisplay(previewOptions.score)
+			? `${this.studentGradePreview?.score && typeof this.studentGradePreview?.score === 'number' ? formatNumber(this.studentGradePreview?.score) : ''} / ${this.outOf && typeof this.outOf === 'number' ? formatNumber(this.outOf) : 0}`
+			: '';
+		const accessibleScore = this._shouldDisplay(previewOptions.score) ? this.localize('components:gradeResult:numeratorOutOfDenominator', { numerator: this.studentGradePreview?.score, denominator: this.outOf }) : '';
+
+		const symbol = this._shouldDisplay(previewOptions.symbol) ? this.studentGradePreview?.symbol : '';
+
+		const separator = score && symbol ? ' - ' : '';
+
+		return html`
+			<div aria-hidden="true" class="d2l-body-compact">
+				${`${score}${separator}${symbol}`}
+			</div>
+			<d2l-offscreen>
+				${`${accessibleScore}${separator}${symbol}`}
+			</d2l-offscreen>
+		`;
+	}
+
+	_shouldDisplay(property) {
+		return Object.prototype.hasOwnProperty.call(this.studentGradePreview, property);
+	}
+
+}
+
+customElements.define('d2l-grade-result-student-grade-preview', D2LGradeResultStudentGradePreview);

package/src/controllers/grade-result/Grade.js

@@ -0,0 +1,175 @@
+
+export const GradeType = {
+	Letter: 'LetterGrade',
+	Number: 'Numeric'
+};
+
+export const GradeErrors = {
+	GET_LETTER_GRADE_FROM_NUMERIC_SCORE: 'Grade must be of type LetterGrade to get the letter grade',
+	GET_ASSIGNED_VALUE_FROM_NUMERIC_SCORE: 'Grade must be of type LetterGrade to get the assigned value',
+	INVALID_SCORE_TYPE: 'Invalid scoreType provided',
+	INVALID_SCORE: 'Invalid score provided',
+	INVALID_OUT_OF: 'Invalid outOf provided',
+	INVALID_LETTER_GRADE: 'Invalid letterGrade provided',
+	INVALID_LETTER_GRADE_ID: 'Invalid letterGradeId provided',
+	INVALID_LETTER_GRADE_OPTIONS: 'Invalid letterGradeOptions provided',
+	LETTER_GRADE_NOT_IN_OPTIONS: 'letterGrade must be one of the letterGradeOptions provided',
+	LETTER_GRADE_ID_NO_ASSIGNED_VALUE: 'LetterGradeId does not have a corresponding AssignedValue',
+};
+
+export class Grade {
+
+	constructor(scoreType, score, outOf, letterGrade, letterGradeOptions, entity, calculatedScore = null, aggregatedScore = null, display = null) {
+		this.entity = entity;
+		this.isManuallyOverridden = false;
+		this.calculatedScore = calculatedScore;
+		this.aggregatedScore = aggregatedScore;
+		this.display = display;
+		this.outOf = outOf;
+		this.scoreType = this._parseScoreType(scoreType);
+		if (this.isNumberGrade()) {
+			this._parseNumberGrade(score);
+		} else {
+			const letterGradeId = this._getLetterGradeIdFromLetterGrade(letterGrade, letterGradeOptions);
+			this._parseLetterGrade(letterGradeId, letterGradeOptions);
+		}
+	}
+
+	getDisplay() {
+		return this.display;
+	}
+
+	getEntity() {
+		return this.entity;
+	}
+
+	getLetterGrade() {
+		if (this.isNumberGrade()) {
+			throw new Error(GradeErrors.GET_LETTER_GRADE_FROM_NUMERIC_SCORE);
+		}
+		return this.letterGrade;
+	}
+
+	getLetterGradeAssignedValue() {
+		if (this.isNumberGrade()) {
+			throw new Error(GradeErrors.GET_LETTER_GRADE_FROM_NUMERIC_SCORE);
+		}
+
+		const letterGradeOption = this.letterGradeOptions[this.letterGradeId];
+
+		if (!letterGradeOption || (typeof letterGradeOption.AssignedValue !== 'number' && letterGradeOption.AssignedValue !== null)) {
+			throw new Error(GradeErrors.LETTER_GRADE_ID_NO_ASSIGNED_VALUE);
+		}
+
+		return letterGradeOption.AssignedValue;
+	}
+
+	getLetterGradeOptions() {
+		return this.letterGradeOptions;
+	}
+
+	getOutOf() {
+		return this.outOf;
+	}
+
+	getScore() {
+		return this.isNumberGrade() ? this.score : this.letterGradeId;
+	}
+
+	getScoreType() {
+		return this.scoreType;
+	}
+
+	isLetterGrade() {
+		return this.scoreType === GradeType.Letter;
+	}
+
+	isNumberGrade() {
+		return this.scoreType === GradeType.Number;
+	}
+
+	setScore(score) {
+		if (this.isNumberGrade()) {
+			this._parseNumberGrade(score, this.outOf);
+		} else {
+			this._parseLetterGrade(score, this.letterGradeOptions);
+		}
+	}
+
+	_getLetterGradeIdFromLetterGrade(letterGrade, letterGradeOptions) {
+		if ((!letterGrade || typeof letterGrade !== 'string') && letterGrade !== null && letterGrade !== '') {
+			throw new Error(GradeErrors.INVALID_LETTER_GRADE);
+		}
+		if (!letterGradeOptions || typeof letterGradeOptions !== 'object' || Object.keys(letterGradeOptions).length === 0) {
+			throw new Error(GradeErrors.INVALID_LETTER_GRADE_OPTIONS);
+		}
+
+		let letterGradeId;
+
+		// this is the "None" case which has the id 0
+		if (letterGrade === '' || letterGrade === null) {
+			letterGradeId = '0';
+		} else {
+			letterGradeId = Object.keys(letterGradeOptions).find(key =>
+				letterGradeOptions[key].LetterGrade === letterGrade
+			);
+		}
+
+		if (letterGradeId === undefined) {
+			throw new Error(GradeErrors.LETTER_GRADE_NOT_IN_OPTIONS);
+		}
+
+		return letterGradeId;
+	}
+
+	_parseLetterGrade(letterGradeId, letterGradeOptions) {
+		if (!letterGradeId && letterGradeId !== 0) {
+			throw new Error(GradeErrors.INVALID_LETTER_GRADE_ID);
+		}
+
+		if (!letterGradeOptions || Object.keys(letterGradeOptions).length === 0) {
+			throw new Error(GradeErrors.INVALID_LETTER_GRADE_OPTIONS);
+		}
+
+		this.score = null;
+		this.letterGradeId = letterGradeId;
+		this.letterGrade = letterGradeOptions[letterGradeId].LetterGrade;
+		this.letterGradeOptions = letterGradeOptions;
+	}
+
+	_parseNumberGrade(score) {
+		if (score === undefined) {
+			score = '';
+		} else if (isNaN(score)) {
+			throw new Error(GradeErrors.INVALID_SCORE);
+		} else if (typeof score === 'string') {
+			score = Number(score);
+		}
+
+		if (this.calculatedScore !== null) {
+			this.isManuallyOverridden = score !== this.calculatedScore;
+		}
+
+		this.score = score;
+		this.letterGradeId = null;
+		this.letterGrade = null;
+		this.letterGradeOptions = null;
+	}
+
+	_parseScoreType(scoreType) {
+		const invalidScoreError = new Error(GradeErrors.INVALID_SCORE_TYPE);
+
+		if (!scoreType || typeof scoreType !== 'string') {
+			throw invalidScoreError;
+		}
+
+		if (scoreType.toLowerCase() === GradeType.Number.toLowerCase()) {
+			return GradeType.Number;
+		} else if (scoreType.toLowerCase() === GradeType.Letter.toLowerCase()) {
+			return GradeType.Letter;
+		} else {
+			throw invalidScoreError;
+		}
+	}
+
+}