chore: Detect and report missing css styles

Author: just-boris

.gitignore

@@ -9,9 +9,9 @@ src/index.ts
 src/test-utils/dom/index.ts
 src/test-utils/selectors
 src/icon/generated
-src/internal/generated/custom-css-properties/index.*
+src/internal/generated/custom-css-properties
 vendor/generated-*.txt
 # IDEs
 .vscode
 # System
-.DS_Store
+.DS_Store

build-tools/tasks/clean.js

@@ -14,6 +14,7 @@ module.exports = task('clean', () => {
       `${workspace.targetPath}/**`,
       `${workspace.staticSitePath}/**`,
       `${workspace.generatedTestUtils}/**`,
+      `${workspace.generatedPath}/custom-css-properties/**`,
       `node_modules/.cache`,
     ],
     { glob: true }

build-tools/tasks/generate-custom-css-properties.js

@@ -1,11 +1,12 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-const customCssPropertiesList = require('../../src/internal/generated/custom-css-properties/list');
 const path = require('path');
-const { writeFile } = require('../utils/files');
 const { getHashDigest } = require('loader-utils');
+const customCssPropertiesList = require('../utils/custom-css-properties');
+const { writeFile } = require('../utils/files');
+const workspace = require('../utils/workspace');
 
-const outputBasePath = path.join(__dirname, '../../src/internal/generated/custom-css-properties');
+const outputBasePath = path.join(workspace.generatedPath, 'custom-css-properties');
 const hash = getHashDigest(Buffer.from(JSON.stringify(customCssPropertiesList)), 'md5', 'base36', 6);
 
 const getHashedProperty = property => {
@@ -32,6 +33,9 @@ function writeSassFile() {
   writeFile(
     filepath,
     `
+    // Build environment
+    $awsui-commit-hash: ${workspace.gitCommitVersion};
+    // Manually managed CSS-variables
     ${customCssPropertiesList.map(property => `$${property}: ${getHashedProperty(property)};`).join('\n')}
     `
   );

build-tools/tasks/generate-environment.js

@@ -10,6 +10,7 @@ function writeEnvironmentFile(theme) {
   const values = {
     PACKAGE_SOURCE: workspace.packageSource,
     PACKAGE_VERSION: workspace.packageVersion,
+    GIT_SHA: workspace.gitCommitVersion,
     THEME: theme.name,
     ALWAYS_VISUAL_REFRESH: !!theme.alwaysVisualRefresh,
   };

…/generated/custom-css-properties/list.js …ild-tools/utils/custom-css-properties.jssrc/internal/generated/custom-css-properties/list.js renamed to build-tools/utils/custom-css-properties.js src/internal/generated/custom-css-properties/list.js renamed to build-tools/utils/custom-css-properties.js

@@ -11,6 +11,7 @@ module.exports = {
   isProd: process.env.NODE_ENV === 'production',
   packageSource,
   packageVersion,
+  gitCommitVersion,
   sourcePath: 'src',
   generatedPath: 'src/internal/generated',
   generatedTestUtils: 'src/test-utils/selectors',

build-tools/utils/workspace.js

@@ -9,3 +9,8 @@
 */
 @use 'awsui:globals';
 @use '../styles/global.scss';
+@use '../generated/custom-css-properties' as custom-styles;
+
+:root {
+  --awsui-version-info-#{custom-styles.$awsui-commit-hash}: true;
+}

src/internal/base-component/styles.scss

@@ -5,5 +5,6 @@
 export const THEME: string;
 export const PACKAGE_SOURCE: string;
 export const PACKAGE_VERSION: string;
+export const GIT_SHA: string;
 /** Indicates that the current theme is always in visual refresh mode. */
 export const ALWAYS_VISUAL_REFRESH: boolean;

src/internal/environment.d.ts

@@ -0,0 +1,98 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { GIT_SHA } from '../../../../../lib/components/internal/environment';
+import { checkMissingStyles } from '../../../../../lib/components/internal/hooks/use-base-component/styles-check';
+import { metrics } from '../../../../../lib/components/internal/metrics';
+import { idleWithDelay } from '../styles-check';
+
+jest.mock('../../../../../lib/components/internal/environment', () => ({
+  ...jest.requireActual('../../../../../lib/components/internal/environment'),
+  PACKAGE_VERSION: '3.0.0 (abc)',
+  GIT_SHA: 'abc',
+}));
+
+afterEach(() => {
+  jest.resetAllMocks();
+});
+
+describe('checkMissingStyles', () => {
+  let consoleWarnSpy: jest.SpyInstance;
+  let sendPanoramaMetricSpy: jest.SpyInstance;
+  const style = document.createElement('style');
+  document.body.append(style);
+
+  beforeEach(() => {
+    style.textContent = ``;
+    consoleWarnSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    sendPanoramaMetricSpy = jest.spyOn(metrics, 'sendOpsMetricObject').mockImplementation(() => {});
+  });
+
+  test('should pass the check if styles found', () => {
+    // using :root does not work in JSDOM: https://github.com/jsdom/jsdom/issues/3563
+    style.textContent = `
+      body {
+        --awsui-version-info-${GIT_SHA}: true;
+      }
+  `;
+    checkMissingStyles();
+    expect(consoleWarnSpy).not.toHaveBeenCalled();
+    expect(sendPanoramaMetricSpy).not.toHaveBeenCalled();
+  });
+
+  test('should detect missing styles', () => {
+    checkMissingStyles();
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      'Missing Cloudscape CSS for theme "default", version "3.0.0 (abc)", and git sha "abc".'
+    );
+    expect(sendPanoramaMetricSpy).toHaveBeenCalledWith('awsui-missing-css-asset', {});
+  });
+
+  test('should report missing styles if a different version found', () => {
+    style.textContent = `
+      body {
+        --awsui-version-info-c4d5e6: true;
+      }
+  `;
+    checkMissingStyles();
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      'Missing Cloudscape CSS for theme "default", version "3.0.0 (abc)", and git sha "abc".'
+    );
+    expect(sendPanoramaMetricSpy).toHaveBeenCalledWith('awsui-missing-css-asset', {});
+  });
+});
+
+describe('idleWithDelay', () => {
+  const delay = (time: number) => new Promise(resolve => setTimeout(resolve, time));
+
+  beforeEach(() => {
+    // simulate requestIdleCallback for JSDOM
+    globalThis.requestIdleCallback = cb => setTimeout(cb, 0);
+  });
+
+  test('does nothing if requestIdleCallback not supported', async () => {
+    // @ts-expect-error simulate missing API
+    globalThis.requestIdleCallback = undefined;
+    const cb = jest.fn();
+    expect(requestIdleCallback).toBe(undefined);
+    idleWithDelay(cb);
+    await delay(1100);
+    expect(cb).not.toHaveBeenCalled();
+  });
+
+  test('runs callback after a delay', async () => {
+    const cb = jest.fn();
+    idleWithDelay(cb);
+    await delay(1100);
+    expect(cb).toHaveBeenCalled();
+  });
+
+  test('delay can be aborted', async () => {
+    const cb = jest.fn();
+    const abort = idleWithDelay(cb);
+    await delay(500);
+    abort!();
+    await delay(600);
+    expect(cb).not.toHaveBeenCalled();
+  });
+});

src/internal/hooks/use-base-component/__tests__/styles-check.test.ts

@@ -13,6 +13,7 @@ import { AnalyticsMetadata } from '../../analytics/interfaces';
 import { PACKAGE_SOURCE, PACKAGE_VERSION, THEME } from '../../environment';
 import { getVisualTheme } from '../../utils/get-visual-theme';
 import { useVisualRefresh } from '../use-visual-mode';
+import { useMissingStylesCheck } from './styles-check';
 
 export interface InternalBaseComponentProps<T = any> {
   __internalRootRef?: MutableRefObject<T | null> | null;
@@ -32,6 +33,7 @@ export default function useBaseComponent<T = any>(
   const theme = getVisualTheme(THEME, isVisualRefresh);
   useComponentMetrics(componentName, { packageSource: PACKAGE_SOURCE, packageVersion: PACKAGE_VERSION, theme }, config);
   useFocusVisible();
+  useMissingStylesCheck();
   const elementRef = useComponentMetadata<T>(
     componentName,
     { packageName: PACKAGE_SOURCE, version: PACKAGE_VERSION, theme },