lightning-base-components 1.13.10-alpha → 1.14.4-alpha

package/src/lightning/datatable/rowSelectionShared.js

@@ -0,0 +1,79 @@
+/**
+ * This file exists in order to get around circular dependencies.
+ * In this case, rowSelection.js has a dependency on rows.js;
+ * but rows.js also has a dependency on rowSelection.js for
+ * `isSelectedRow()` among others.
+ *
+ * We split out the functions that could cause circular dependencies with
+ * `rowSelection.js` into the `*Shared.js` files.
+ */
+
+/**
+ * Returns whether or not the row is selected using the state and the rowKeyValue
+ * The state maintains the list of selected rows from which
+ * this value can be retrieved.
+ *
+ * @param {Object} state - datatable state object
+ * @param {String} rowKeyValue
+ * @returns
+ */
+export function isSelectedRow(state, rowKeyValue) {
+    return !!state.selectedRowsKeys[rowKeyValue];
+}
+
+/**
+ * Returns whether the row (whose row key value is specified)
+ * should be disabled or not.
+ * Should not disable if the row is selected.
+ * If the particular row is not selected, the row should be disabled
+ * when max-row-selection > 1 and the selection limit is reached
+ *
+ * Note: Do not disable selection when max-row-selection = 1 and
+ * a row has been selected.
+ *
+ * @param {Object} state
+ * @param {String} rowKeyValue
+ * @returns {Boolean} whether the row should be disabled or not
+ */
+export function isDisabledRow(state, rowKeyValue) {
+    if (!isSelectedRow(state, rowKeyValue)) {
+        const maxRowSelection = getMaxRowSelection(state);
+
+        // when selection is 1, we should not disable selection
+        return (
+            maxRowSelection !== 1 &&
+            getCurrentSelectionLength(state) === maxRowSelection
+        );
+    }
+
+    return false;
+}
+
+/**
+ * Returns which input type to use for row selection.
+ * If max-row-selection = 1, use radio buttons,
+ * otherwise, use checkboxes.
+ *
+ * @param {Object} state - datatable's state object
+ * @returns
+ */
+export function getRowSelectionInputType(state) {
+    if (getMaxRowSelection(state) === 1) {
+        return 'radio';
+    }
+    return 'checkbox';
+}
+
+export function getMaxRowSelection(state) {
+    return state.maxRowSelection;
+}
+
+export function getCurrentSelectionLength(state) {
+    return getSelectedRowsKeys(state).length;
+}
+
+export function getSelectedRowsKeys(state) {
+    return Object.keys(state.selectedRowsKeys).filter(
+        (key) => state.selectedRowsKeys[key]
+    );
+}

package/src/lightning/datatable/rows.js

@@ -1,11 +1,11 @@
 import { assert } from 'lightning/utilsPrivate';
-import { classSet, isObjectLike } from './utils';
+import { classSet, isObjectLike, styleToString } from './utils';
 import { isTreeType, getAttributesNames } from './types';
 import {
     isSelectedRow,
     isDisabledRow,
     getRowSelectionInputType,
-} from './selector-shared';
+} from './rowSelectionShared';
 import { getTreeStateIndicatorFieldNames, getStateTreeColumn } from './tree';
 import {
     getColumns,
@@ -17,7 +17,8 @@ import {
 } from './columns';
 import { isRowNumberColumn, getRowNumberErrorColumnDef } from './rowNumber';
 import { getRowError } from './errors';
-import { getDirtyValue } from './inlineEdit-shared';
+import { getDirtyValueFromCell } from './inlineEditShared';
+import { DEFAULT_ROW_HEIGHT } from './renderManager';
 
 export function getData(state) {
     return state.data;
@@ -115,7 +116,7 @@ export function uniqueRowKeyGenerator(keyField) {
  */
 export function updateRowsAndCellIndexes() {
     const { state, privateTypes: types } = this;
-    const { keyField, renderModeRoleBased } = state;
+    const { keyField, renderModeRoleBased, virtualize } = state;
     const data = getData(state);
     const columns = getColumns(state);
     const computeUniqueRowKey = uniqueRowKeyGenerator(keyField);
@@ -141,11 +142,21 @@ export function updateRowsAndCellIndexes() {
         row.classnames = resolveRowClassNames(row);
         Object.assign(row, getRowStateForTree(rowData, state));
         row.tabIndex = -1;
+        if (virtualize) {
+            row.style = styleToString({
+                position: 'absolute',
+                top: `${rowIndex * DEFAULT_ROW_HEIGHT}px`,
+            });
+        }
 
         columns.reduce((currentRow, colData, colIndex) => {
             const { fieldName } = colData;
             const colKeyValue = generateColKeyValue(colData, colIndex);
-            const dirtyValue = getDirtyValue(state, row.key, colKeyValue);
+            const dirtyValue = getDirtyValueFromCell(
+                state,
+                row.key,
+                colKeyValue
+            );
             const cellHasErrors = hasCellErrors(
                 rowErrors,
                 colData.fieldName,
@@ -391,7 +402,7 @@ function computeCellEditable(row, column) {
  * @param {object} row - a row data object stored in datatable state. Must be truthy.
  * @param {object} column - a column data object stored in datatable state. Must be truthy.
  */
-function isCellEditable(row, column) {
+export function isCellEditable(row, column) {
     return !!resolveAttributeValue(column.editable, row);
 }
 

package/src/lightning/datatable/state.js

@@ -17,8 +17,9 @@ export const getDefaultState = function () {
         rows: [],
         indexes: {},
 
-        // selector
+        // row selection
         selectedRowsKeys: {},
+        lastSelectedRowKey: undefined,
         maxRowSelection: undefined,
 
         headerIndexes: {},
@@ -54,12 +55,25 @@ export const getDefaultState = function () {
         // table render mode
         renderModeRoleBased: false,
 
-        // viewport rendering
+        // viewport rendering and virtualization
         enableViewportRendering: undefined,
+        virtualize: '',
+        bufferSize: 5, // number of extra rows rendered on each side outside of viewport
+        rowHeight: 30.5,
+        renderedRowCount: 0,
+        firstVisibleIndex: 0, // first row that should be visible in viewport
 
         // inline edit
         inlineEdit: {
+            rowKeyValue: undefined,
+            colKeyValue: undefined,
+            columnDef: {},
             dirtyValues: {},
+            editedValue: undefined,
+            isPanelVisible: false,
+            massEditEnabled: false,
+            massEditSelectedRows: undefined,
+            resolvedAttributeTypes: {},
         },
 
         // errors

package/src/lightning/datatable/templates/div/div.css

@@ -22,6 +22,10 @@
     border-top: 1px solid #dddbda;
 }
 
+.slds-table_header-fixed [data-row-key-value]:first-child {
+    border-top: 0;
+}
+
 /* Required for row numbers */
 [role="row"] {
     counter-increment: row-number;

package/src/lightning/datatable/templates/div/div.html

@@ -48,6 +48,7 @@
                             <div class="slds-line-height_reset table-header"
                                 role="row"
                                 aria-rowindex="1"
+                                data-row-key-value="HEADER"
                                 onprivateresizestart={handleResizeStart}
                                 onprivateresizeend={handleResizeEnd}>
                                 <template for:each={state.columns} for:item="def" for:index="colIndex">
@@ -58,6 +59,7 @@
                                         tabindex={def.tabIndex}
                                         aria-label={def.ariaLabel}
                                         aria-sort={def.sortAriaLabel}
+                                        data-col-key-value={def.colKeyValue}
                                         key={def.colKeyValue}>
 
                                         <template if:true={def.fixedWidth}>
@@ -120,6 +122,7 @@
                                     aria-setsize={row.setSize}
                                     aria-posinset={row.posInSet}
                                     aria-rowindex={row.ariaRowIndex}
+                                    style={row.style}
                                     tabindex={row.tabIndex}>
                                     <template for:each={row.cells} for:item="cell">
                                         <template if:true={cell.isCheckbox}>
@@ -129,6 +132,7 @@
                                                 role="gridcell"
                                                 tabindex={cell.tabIndex}
                                                 data-label={cell.dataLabel}
+                                                data-col-key-value={cell.colKeyValue}
                                                 key={cell.colKeyValue}>
                                                 <lightning-primitive-cell-checkbox
                                                     dt-context-id={_datatableId}
@@ -154,6 +158,7 @@
                                                 aria-readonly={cell.ariaReadOnly}
                                                 tabindex={cell.tabIndex}
                                                 data-label={cell.dataLabel}
+                                                data-col-key-value={cell.colKeyValue}
                                                 key={cell.colKeyValue}>
                                                 <lightning-primitive-cell-factory
                                                     types={privateTypes}
@@ -202,6 +207,7 @@
                                                 aria-readonly={cell.ariaReadOnly}
                                                 tabindex={cell.tabIndex}
                                                 data-label={cell.dataLabel}
+                                                data-col-key-value={cell.colKeyValue}
                                                 key={cell.colKeyValue}>
                                                 <lightning-primitive-cell-factory
                                                     types={privateTypes}

package/src/lightning/datatable/templates/table/table.html

@@ -41,6 +41,7 @@
                         <thead>
                             <!-- Column Header Row -->
                             <tr class="slds-line-height_reset"
+                                data-row-key-value="HEADER"
                                 onprivateresizestart={handleResizeStart}
                                 onprivateresizeend={handleResizeEnd}>
                                 <template for:each={state.columns} for:item="def" for:index="colIndex">
@@ -50,6 +51,7 @@
                                         tabindex={def.tabIndex}
                                         aria-label={def.ariaLabel}
                                         aria-sort={def.sortAriaLabel}
+                                        data-col-key-value={def.colKeyValue}
                                         key={def.colKeyValue}>
 
                                         <template if:true={def.fixedWidth}>
@@ -117,6 +119,7 @@
                                                 role="gridcell"
                                                 tabindex={cell.tabIndex}
                                                 data-label={cell.dataLabel}
+                                                data-col-key-value={cell.colKeyValue}
                                                 key={cell.colKeyValue}>
                                                 <lightning-primitive-cell-checkbox
                                                     dt-context-id={_datatableId}
@@ -142,6 +145,7 @@
                                                 scope="row"
                                                 tabindex={cell.tabIndex}
                                                 data-label={cell.dataLabel}
+                                                data-col-key-value={cell.colKeyValue}
                                                 key={cell.colKeyValue}>
                                                 <lightning-primitive-cell-factory
                                                     types={privateTypes}
@@ -190,6 +194,7 @@
                                                 aria-readonly={cell.ariaReadOnly}
                                                 tabindex={cell.tabIndex}
                                                 data-label={cell.dataLabel}
+                                                data-col-key-value={cell.colKeyValue}
                                                 key={cell.colKeyValue}>
                                                 <lightning-primitive-cell-factory
                                                     types={privateTypes}

package/src/lightning/datatable/utils.js

@@ -109,3 +109,17 @@ export function getScrollOffsetFromTableEnd(el) {
         el.scrollHeight - el.parentNode.scrollTop - el.parentNode.clientHeight
     );
 }
+
+/**
+ * Utility for converting arrays and plain objects to style strings
+ * @param {Array|Object} style
+ * @returns {string} representing array/object as a string
+ */
+export function styleToString(style) {
+    if (!Array.isArray(style)) {
+        return Object.entries(style)
+            .map(([key, value]) => `${key}:${value}`)
+            .join(';');
+    }
+    return style.join(';');
+}

package/src/lightning/datatable/wrapText.js

@@ -3,8 +3,10 @@ import labelWrapText from '@salesforce/label/LightningDatatable.wrapText';
 import { getStateColumnIndex, getColumns } from './columns';
 import { normalizeBoolean } from 'lightning/utilsPrivate';
 import { normalizeNumberAttribute } from './utils';
+import { getDefaultState } from './state';
 
-const nonWrapableTypes = [
+const WRAP_TEXT_DEFAULT = false;
+const NON_WRAPPABLE_TYPES = [
     'action',
     'boolean',
     'button',
@@ -13,17 +15,33 @@ const nonWrapableTypes = [
     'rowNumber',
 ];
 
-const WRAP_TEXT_DEFAULT = false;
-
 const i18n = {
     clipText: labelClipText,
     wrapText: labelWrapText,
 };
 
-function isWrapableType(type) {
-    return nonWrapableTypes.indexOf(type) < 0;
+/************************** WRAP TEXT STATE **************************/
+
+// Returns a boolean representing whether or not the column should be text wrapped
+export function getWrapTextState(state = getDefaultState(), colKeyValue) {
+    return state.wrapText[colKeyValue] || WRAP_TEXT_DEFAULT;
 }
 
+// Sets a boolean value in state's wrapText object against the column key value
+// representing whether or not the column is text wrapped
+export function setWrapTextState(state = getDefaultState(), columnDefinition) {
+    const { colKeyValue, type, wrapText } = columnDefinition;
+
+    if (isWrappableType(type)) {
+        state.wrapText[colKeyValue] =
+            normalizeBoolean(wrapText) || WRAP_TEXT_DEFAULT;
+    }
+}
+
+/************************** WRAP TEXT MAX LINES **************************/
+
+// Normalizes and sets wrapTextMaxLines in datatable's state object
+// The normalized value should be a positive integer or it'll fall back to undefined
 export function setWrapTextMaxLines(state, value) {
     state.wrapTextMaxLines = normalizeNumberAttribute(
         'wrapTextMaxLines',
@@ -33,6 +51,8 @@ export function setWrapTextMaxLines(state, value) {
     );
 }
 
+// Sets the `wrapText` and `wrapTextMaxLines` values in the cell object for all cells in a column
+// These values are used by primitiveCellFactory to set the required classes on the cell for wrapping
 function updateWrapTextAndMaxLinesValuesInCells(state, colIndex, colKeyValue) {
     state.rows.forEach((row) => {
         const cell = row.cells[colIndex];
@@ -43,39 +63,17 @@ function updateWrapTextAndMaxLinesValuesInCells(state, colIndex, colKeyValue) {
     });
 }
 
-function updateSelectedOptionInHeaderActions(state, colKeyValue) {
-    const columns = getColumns(state);
-    const colIndex = getStateColumnIndex(state, colKeyValue);
-    const colData = columns[colIndex];
-
-    colData.actions.internalActions.forEach((action) => {
-        if (action.name === 'wrapText') {
-            action.checked = state.wrapText[colKeyValue];
-        }
-        if (action.name === 'clipText') {
-            action.checked = !state.wrapText[colKeyValue];
-        }
-    });
-
-    updateWrapTextAndMaxLinesValuesInCells(state, colIndex, colKeyValue);
-
-    // lets force a refresh on this column, because the wrapText checked value changed.
-    colData.actions = Object.assign({}, colData.actions);
-}
-
-export function getWrapTextState(state = getDefaultState(), colKeyValue) {
-    return state.wrapText[colKeyValue] || WRAP_TEXT_DEFAULT;
-}
-
-export function setWrapTextState(state = getDefaultState(), columnDefinition) {
-    const { colKeyValue, type, wrapText } = columnDefinition;
-
-    if (isWrapableType(type)) {
-        state.wrapText[colKeyValue] =
-            normalizeBoolean(wrapText) || WRAP_TEXT_DEFAULT;
-    }
-}
-
+/************************** HEADER ACTIONS **************************/
+
+/**
+ * Returns an object representing the two internal header actions that datatable
+ * provides - Wrap Text and Clip Text.
+ * Each header action contains a label, title, action name and its selected value (checked)
+ *
+ * @param {Object} state - datatable's state object
+ * @param {Object} columnDefinition - datatable's column definitions
+ * @returns
+ */
 export function getActions(state, columnDefinition) {
     const wrapTextActions = [];
     const { hideDefaultActions, type, colKeyValue } = columnDefinition;
@@ -84,7 +82,7 @@ export function getActions(state, columnDefinition) {
     setWrapTextState(state, columnDefinition);
 
     // if not hidden and isWrapable, sets the internal actions
-    if (isWrapableType(type) && !hideDefaultActions) {
+    if (isWrappableType(type) && !hideDefaultActions) {
         const isTextWrapped = getWrapTextState(state, colKeyValue);
 
         wrapTextActions.push({
@@ -105,19 +103,51 @@ export function getActions(state, columnDefinition) {
     return wrapTextActions;
 }
 
+/**
+ * If the action is an internal action and if the wrapText value for a column
+ * needs to be changed in the state, change it to the new value and update
+ * the check mark to represent the currently selected action
+ *
+ * @param {Object} state - datatable's state object
+ * @param {String} action - action that was selected/triggered
+ * @param {String} colKeyValue - column key value
+ */
 export function handleTriggeredAction(state, action, colKeyValue) {
-    if (action.name === 'wrapText' || action.name === 'clipText') {
-        // If will change state
-        if (state.wrapText[colKeyValue] !== (action.name === 'wrapText')) {
-            state.wrapText[colKeyValue] = action.name === 'wrapText';
+    const actionName = action.name;
+    if (actionName === 'wrapText' || actionName === 'clipText') {
+        // If state should be changed
+        if (state.wrapText[colKeyValue] !== (actionName === 'wrapText')) {
+            state.wrapText[colKeyValue] = actionName === 'wrapText';
 
             updateSelectedOptionInHeaderActions(state, colKeyValue);
         }
     }
 }
 
-export function getDefaultState() {
-    return {
-        wrapText: {},
-    };
+// Update the 'checked' value of the each action to show which action is selected
+// and which action is not selected
+function updateSelectedOptionInHeaderActions(state, colKeyValue) {
+    const columns = getColumns(state);
+    const colIndex = getStateColumnIndex(state, colKeyValue);
+    const colData = columns[colIndex];
+
+    colData.actions.internalActions.forEach((action) => {
+        if (action.name === 'wrapText') {
+            action.checked = state.wrapText[colKeyValue];
+        }
+        if (action.name === 'clipText') {
+            action.checked = !state.wrapText[colKeyValue];
+        }
+    });
+
+    updateWrapTextAndMaxLinesValuesInCells(state, colIndex, colKeyValue);
+
+    // Force a refresh on this column, because the wrapText checked value changed.
+    colData.actions = Object.assign({}, colData.actions);
+}
+
+/************************** HELPER FUNCTIONS **************************/
+
+function isWrappableType(type) {
+    return NON_WRAPPABLE_TYPES.indexOf(type) < 0;
 }

package/src/lightning/dualListbox/dualListbox.html

@@ -9,7 +9,7 @@
         <lightning-helptext if:true={fieldLevelHelp} content={fieldLevelHelp}></lightning-helptext>
         <div class="slds-form-element__control">
             <div class="slds-dueling-list" onfocusin={handleFocus} onfocusout={handleBlur}>
-                <div class="slds-assistive-text" id="assertive-thing" aria-live="assertive"></div>
+                <div class="slds-assistive-text" id="assertive-thing" aria-live="assertive">{_messageToDisplay}</div>
                 <div class="slds-assistive-text" id="keyboard-interacton">{i18n.componentAssistiveText}</div>
                 <div class={computedLeftColumnClass}>
                     <span class="slds-form-element__label" id="source-list-label">{sourceLabel}</span>

package/src/lightning/dualListbox/dualListbox.js

@@ -14,6 +14,8 @@ import labelRequiredOptionError from '@salesforce/label/LightningDualListbox.req
 import labelUpButtonAssistiveText from '@salesforce/label/LightningDualListbox.upButtonAssistiveText';
 import labelMoveSelectionToAssistiveText from '@salesforce/label/LightningDualListbox.moveSelectionToAssistiveText';
 import labelLoadingText from '@salesforce/label/LightningCombobox.loadingText';
+import labelMovedOptionsSingular from '@salesforce/label/LightningDualListbox.movedOptionsSingular';
+import labelMovedOptionsPlural from '@salesforce/label/LightningDualListbox.movedOptionsPlural';
 import { LightningElement, api, track } from 'lwc';
 import { handleKeyDownOnOption } from './keyboard';
 import { classSet, formatLabel } from 'lightning/utils';
@@ -47,6 +49,8 @@ const i18n = {
     upButtonAssistiveText: labelUpButtonAssistiveText,
     moveSelectionToAssistiveText: labelMoveSelectionToAssistiveText,
     loadingText: labelLoadingText,
+    movedOptionsSingular: labelMovedOptionsSingular,
+    movedOptionsPlural: labelMovedOptionsPlural,
 };
 
 /**
@@ -117,6 +121,9 @@ export default class LightningDualListbox extends LightningElement {
     @track highlightedOptions = [];
     @track focusableInSource;
     @track focusableInSelected;
+    @track highlightedOptionsLabel = [];
+
+    _messageToDisplay = '';
 
     isFocusOnList = false;
 
@@ -705,6 +712,8 @@ export default class LightningDualListbox extends LightningElement {
             );
         }
 
+        this.movedOptions(addToSelect);
+
         const oldSelectedValues = this._selectedValues;
         this._selectedValues = newValues;
         const invalidMove =
@@ -730,6 +739,7 @@ export default class LightningDualListbox extends LightningElement {
             this.interactingState.leave();
             this.isFocusOnList = false;
             this.highlightedOptions = [];
+            this.highlightedOptionsLabel = [];
             this.optionToFocus = null;
         }
 
@@ -785,6 +795,7 @@ export default class LightningDualListbox extends LightningElement {
         const start = all ? options.length : this.lastSelected;
         let val, select;
         this.highlightedOptions = [];
+        this.highlightedOptionsLabel = [];
         for (let i = 0; i < options.length; i++) {
             select = (i - start) * (i - end) <= 0;
             if (select) {
@@ -889,6 +900,7 @@ export default class LightningDualListbox extends LightningElement {
         if (this.selectedList !== currentList || !isMultiple) {
             if (this.selectedList) {
                 this.highlightedOptions = [];
+                this.highlightedOptionsLabel = [];
                 this.lastSelected = -1;
             }
             this.selectedList = currentList;
@@ -1013,6 +1025,36 @@ export default class LightningDualListbox extends LightningElement {
         }
         if (!isSame) {
             this.highlightedOptions = [];
+            this.highlightedOptionsLabel = [];
+        }
+    }
+
+    movedOptions(addToSelect) {
+        const listName = addToSelect ? this.selectedLabel : this.sourceLabel;
+
+        for (let i = 0; i < this.highlightedOptions.length; i++) {
+            let selectedOption = addToSelect
+                ? this.computedSourceList.filter(
+                      (item) => item.value === this.highlightedOptions[i]
+                  )
+                : this.computedSelectedList.filter(
+                      (item) => item.value === this.highlightedOptions[i]
+                  );
+            this.highlightedOptionsLabel.push(selectedOption[0].label);
+        }
+
+        if (this.highlightedOptions.length) {
+            const strToFormat =
+                this.highlightedOptions.length > 1
+                    ? i18n.movedOptionsPlural
+                    : i18n.movedOptionsSingular;
+            this._messageToDisplay = formatLabel(
+                strToFormat,
+                this.highlightedOptionsLabel.join(', '),
+                listName
+            );
+        } else {
+            this._messageToDisplay = '';
         }
     }
 }

package/src/lightning/formattedDateTime/__docs__/formattedDateTime.md

@@ -45,11 +45,11 @@ are specified, the component uses the default date format based on the user's lo
 
 The locale determines the order and format of the month, day, and year. For example, the English (United States) locale's date format is Oct 14, 2020 and the French (France) locale's date format is 14 Oct 2020. The locale doesn't determine the time zone. Time zone is a separate setting.
 
-The locale also determines whether to display time as 24-hour time or 12-hour time with AM and PM.
+The locale also determines whether to display time as 24-hour time or 12-hour time with AM and PM. You can override the locale default with the `hour12` attribute. See _Date and Time Display Examples_ for more information.
 
-Specify optional attributes to modify the date and time display, overriding the locale's default formatting.
+Specify optional attributes listed in the Specification tab to modify the date and time display, overriding the locale's default formatting.
 
-In the Component Library's Playground and the Mini-Playground in the Examples tab, the component is limited to the en-US locale.
+In the Mini-Playground in the Examples tab, the component is limited to the en-US locale.
 
 #### Time Zone Considerations
 
@@ -132,6 +132,35 @@ Displays: 1/11/2019, 6:53 PM EST
 </template>
 ```
 
+Displays: 1/11/2019, 18:53 EST
+
+```html
+<template>
+    <lightning-formatted-date-time
+        value="1547250828000"
+        year="numeric"
+        month="numeric"
+        day="numeric"
+        hour="2-digit"
+        hour12={ampm}
+        minute="2-digit"
+        time-zone-name="short"
+        time-zone="America/New_York"
+    >
+    </lightning-formatted-date-time>
+</template>
+```
+
+Set the `hour12` attribute using a variable. If set to `false` or any other string directly, the component interprets its value as true.
+
+```js
+import { LightningElement } from 'lwc';
+
+export default class FormattedDateTimeHour12 extends LightningElement {
+    ampm = false;
+}
+```
+
 #### Date and Time Stored in Salesforce
 
 Salesforce uses the ISO8601 format `YYYY-MM-DD` to store date fields, which store a date without time, and includes no time zone information.
@@ -186,6 +215,10 @@ Displays: December 03, 2017, 12:00 PM
 </template>
 ```
 
+#### Usage Considerations
+
+This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](docs/component-library/documentation/lwc/lwc.migrate_map_aura_lwc_components) in the Lightning Web Components Developer Guide.
+
 #### Source Code
 
 `lightning-formatted-date-time` is available in the [Base Components Recipes GitHub repository](https://github.com/salesforce/base-components-recipes#documentation). It's transpiled into the `c` namespace so that you can use it in your own projects.

package/src/lightning/formattedDateTime/__examples__/datetime/datetime.html

@@ -4,8 +4,8 @@
         <p><lightning-formatted-date-time value="1547250828000" year="2-digit" month="short" day="2-digit" hour="numeric"
                                        weekday="long" era="short"></lightning-formatted-date-time></p>
         <p><lightning-formatted-date-time value="1547250828000" year="numeric" month="numeric" day="numeric" hour="2-digit"
-                                        minute="2-digit" time-zone-name="short" hour12="true"></lightning-formatted-date-time></p>
+                                        minute="2-digit" time-zone-name="short"></lightning-formatted-date-time></p>
         <p><lightning-formatted-date-time value="1547250828000" year="numeric" month="numeric" day="numeric" hour="2-digit"
-                                        minute="2-digit" time-zone="UTC" time-zone-name="short" hour12="false"></lightning-formatted-date-time></p>
+                                        minute="2-digit" time-zone="UTC" time-zone-name="short" hour12={ampm}></lightning-formatted-date-time></p>
     </div>
 </template>

package/src/lightning/formattedDateTime/__examples__/datetime/datetime.js

@@ -1,3 +1,5 @@
 import { LightningElement } from 'lwc';
 
-export default class FormattedDateTimeDateTime extends LightningElement {}
+export default class FormattedDateTimeDateTime extends LightningElement {
+    ampm = false;
+}