/*

* Copyright 2020 Google LLC

*

* Licensed under the Apache License, Version 2.0 (the "License");

* you may not use this file except in compliance with the License.

* You may obtain a copy of the License at

*

* https://www.apache.org/licenses/LICENSE-2.0

*

* Unless required by applicable law or agreed to in writing, software

* distributed under the License is distributed on an "AS IS" BASIS,

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

* See the License for the specific language governing permissions and

* limitations under the License.

*/

import {getBFCacheRestoreTime, onBFCacheRestore} from './lib/bfcache.js';

import {bindReporter} from './lib/bindReporter.js';

import {doubleRAF} from './lib/doubleRAF.js';

import {getVisibilityWatcher} from './lib/getVisibilityWatcher.js';

import {initMetric} from './lib/initMetric.js';

import {initUnique} from './lib/initUnique.js';

import {LayoutShiftManager} from './lib/LayoutShiftManager.js';

import {observe} from './lib/observe.js';

import {checkSoftNavsEnabled} from './lib/softNavs.js';

import {runOnce} from './lib/runOnce.js';

import {onFCP} from './onFCP.js';

import type {

CLSMetric,

Metric,

MetricRatingThresholds,

ReportOpts,

} from './types.js';

/** Thresholds for CLS. See https://web.dev/articles/cls#what_is_a_good_cls_score */

export const CLSThresholds: MetricRatingThresholds = [0.1, 0.25];

/**

* Calculates the [CLS](https://web.dev/articles/cls) value for the current page and

* calls the `callback` function once the value is ready to be reported, along

* with all `layout-shift` performance entries that were used in the metric

* value calculation. The reported value is a `double` (corresponding to a

* [layout shift score](https://web.dev/articles/cls#layout_shift_score)).

*

* If the `reportAllChanges` configuration option is set to `true`, the

* `callback` function will be called as soon as the value is initially

* determined as well as any time the value changes throughout the page

* lifespan.

*

* _**Important:** CLS should be continually monitored for changes throughout

* the entire lifespan of a page—including if the user returns to the page after

* it's been hidden/backgrounded. However, since browsers often [will not fire

* additional callbacks once the user has backgrounded a

* page](https://developer.chrome.com/blog/page-lifecycle-api/#advice-hidden),

* `callback` is always called when the page's visibility state changes to

* hidden. As a result, the `callback` function might be called multiple times

* during the same page load._

*/

export const onCLS = (

onReport: (metric: CLSMetric) => void,

opts: ReportOpts = {},

) => {

const visibilityWatcher = getVisibilityWatcher();

// Start monitoring FCP so we can only report CLS if FCP is also reported.

// Note: this is done to match the current behavior of CrUX.

onFCP(

runOnce(() => {

let metric = initMetric('CLS', 0);

let report: ReturnType<typeof bindReporter>;

const layoutShiftManager = initUnique(opts, LayoutShiftManager);

const initNewCLSMetric = (

navigationType?: Metric['navigationType'],

navigationId?: number,

navigationInteractionId?: number,

navigationURL?: string,

navigationStartTime?: number,

) => {

metric = initMetric(

'CLS',

0,

navigationType,

navigationId,

navigationInteractionId,

navigationURL,

navigationStartTime,

);

layoutShiftManager._sessionValue = 0;

report = bindReporter(

onReport,

metric,

CLSThresholds,

opts.reportAllChanges,

);

};

const updateAndReportMetric = (forceReport: boolean = false) => {

// If the current session value is larger than the current CLS value,

// update CLS and the entries contributing to it.

if (layoutShiftManager._sessionValue > metric.value) {

metric.value = layoutShiftManager._sessionValue;

metric.entries = layoutShiftManager._sessionEntries;

}

report(forceReport);

};

const handleSoftNavEntry = (entry: PerformanceSoftNavigation) => {

updateAndReportMetric(true);

initNewCLSMetric(

'soft-navigation',

entry.navigationId,

entry.interactionId,

entry.name,

entry.startTime,

);

};

const handleEntries = (

entries: (LayoutShift | PerformanceSoftNavigation)[],

) => {

for (const entry of entries) {

if (entry.entryType === 'soft-navigation') {

handleSoftNavEntry(entry as PerformanceSoftNavigation);

continue;

}

layoutShiftManager._processEntry(entry as LayoutShift);

}

updateAndReportMetric();

};

const types = ['layout-shift'] as ('layout-shift' | 'soft-navigation')[];

if (checkSoftNavsEnabled(opts)) {

types.push('soft-navigation');

}

const po = observe(types, handleEntries);

if (po) {

report = bindReporter(

onReport,

metric,

CLSThresholds,

opts.reportAllChanges,

);

visibilityWatcher.onHidden(() => {

handleEntries(

po.takeRecords() as [LayoutShift | PerformanceSoftNavigation],

);

report(true);

});

// Only report after a bfcache restore if the `PerformanceObserver`

// successfully registered.

onBFCacheRestore(() => {

initNewCLSMetric(

'back-forward-cache',

metric.navigationId,

metric.navigationInteractionId,

metric.navigationURL,

getBFCacheRestoreTime(),

);

doubleRAF(report);

});

// Queue a task to report (if nothing else triggers a report first).

// This allows CLS to be reported as soon as FCP fires when

// `reportAllChanges` is true.

setTimeout(report);

}

}),

);

};