From 914515f7dd77322a0e19abd753a1b5ecd9f7f9b9 Mon Sep 17 00:00:00 2001
From: Dobromir Hristov <dhristov@apple.com>
Date: Thu, 30 Mar 2023 21:44:15 +0300
Subject: [PATCH 1/2] feat: allow customizing Page color

---
 src/components/DocumentationTopic.vue         |  9 ++++++
 .../DocumentationTopic/DocumentationHero.vue  | 27 ++++++++++++++----
 src/components/TopicTypeIcon.vue              | 12 ++++----
 src/styles/core/colors/_light.scss            |  8 ++++++
 .../DocumentationHero.spec.js                 | 28 +++++++++++++++----
 tests/unit/components/TopicTypeIcon.spec.js   |  4 +--
 6 files changed, 70 insertions(+), 18 deletions(-)

diff --git a/src/components/DocumentationTopic.vue b/src/components/DocumentationTopic.vue
index fedf4ca9f..b90d53c8f 100644
--- a/src/components/DocumentationTopic.vue
+++ b/src/components/DocumentationTopic.vue
@@ -21,6 +21,7 @@
         :shortHero="shortHero"
         :shouldShowLanguageSwitcher="shouldShowLanguageSwitcher"
         :iconOverride="references[pageIcon]"
+        :standardColorIdentifier="standardColorIdentifier"
       >
         <template #above-content>
           <slot name="above-hero-content" />
@@ -354,6 +355,10 @@ export default {
       type: Boolean,
       default: false,
     },
+    standardColorIdentifier: {
+      type: String,
+      required: false,
+    },
   },
   provide() {
     // NOTE: this is not reactive: if this.references change, the provided value
@@ -543,6 +548,9 @@ export default {
           symbolKind = '',
           remoteSource,
           images: pageImages = [],
+          color: {
+            standardColorIdentifier,
+          } = {},
         } = {},
         primaryContentSections,
         relationshipsSections,
@@ -595,6 +603,7 @@ export default {
         pageImages,
         objcPath,
         swiftPath,
+        standardColorIdentifier,
       };
     },
   },
diff --git a/src/components/DocumentationTopic/DocumentationHero.vue b/src/components/DocumentationTopic/DocumentationHero.vue
index 3c422eb0e..ad3f0de9b 100644
--- a/src/components/DocumentationTopic/DocumentationHero.vue
+++ b/src/components/DocumentationTopic/DocumentationHero.vue
@@ -72,13 +72,20 @@ export default {
       type: Object,
       required: false,
     },
+    standardColorIdentifier: {
+      type: String,
+      required: false,
+    },
   },
   computed: {
     // get the alias, if any, and fallback to the `teal` color
     color: ({ type }) => HeroColorsMap[TopicTypeAliases[type] || type] || HeroColors.teal,
-    styles: ({ color }) => ({
+    styles: ({ color, standardColorIdentifier }) => ({
       // use the color or fallback to the gray secondary, if not defined.
-      '--accent-color': `var(--color-documentation-intro-accent, var(--color-type-icon-${color}, var(--color-figure-gray-secondary)))`,
+      '--accent-color': `var(--color-documentation-intro-accent, var(--color-type-icon-${color}))`,
+      // if a `standardColor` is provided, first try the more specific variant,
+      // falling back to the generic color variant.
+      '--standard-accent-color': standardColorIdentifier && `var(--color-standard-${standardColorIdentifier}-documentation-intro-fill, var(--color-standard-${standardColorIdentifier}))`,
     }),
     // This mapping is necessary to help create a consistent mapping for the
     // following kinds of things, which are represented as different strings
@@ -103,10 +110,18 @@ export default {
 <style scoped lang='scss'>
 @import 'docc-render/styles/_core.scss';
 
-$doc-hero-gradient-background: dark-color(fill-tertiary) !default;
+// if the page has a `standard` color, it must be used
+$doc-hero-gradient-background: var(
+    --standard-accent-color,
+    // then fallback to a theme-settings color
+    var(--color-documentation-intro-fill, #{dark-color(fill-tertiary)})
+) !default;
 $doc-hero-overlay-background: transparent !default;
 $doc-hero-icon-opacity: 1 !default;
-$doc-hero-icon-color: dark-color(fill-secondary) !default;
+$doc-hero-icon-color: var(
+    --color-documentation-intro-accent,
+    #{dark-color(fill-secondary)}
+) !default;
 $doc-hero-icon-spacing: 25px;
 $doc-hero-icon-vertical-spacing: 10px;
 $doc-hero-icon-dimension: 250px;
@@ -123,7 +138,7 @@ $doc-hero-icon-dimension: 250px;
   // gradient
   &:before {
     content: '';
-    background: var(--color-documentation-intro-fill, $doc-hero-gradient-background);
+    background: $doc-hero-gradient-background;
     position: absolute;
     width: 100%;
     left: 0;
@@ -160,7 +175,7 @@ $doc-hero-icon-dimension: 250px;
   }
 
   .background-icon {
-    color: var(--color-documentation-intro-accent, $doc-hero-icon-color);
+    color: $doc-hero-icon-color;
     display: block;
     width: $doc-hero-icon-dimension;
     height: auto;
diff --git a/src/components/TopicTypeIcon.vue b/src/components/TopicTypeIcon.vue
index 5f43dc642..23d8aba40 100644
--- a/src/components/TopicTypeIcon.vue
+++ b/src/components/TopicTypeIcon.vue
@@ -9,11 +9,13 @@
 -->
 
 <template>
-  <div class="TopicTypeIcon">
+  <div
+    class="TopicTypeIcon"
+    :style="styles"
+  >
     <OverridableAsset
       v-if="imageOverride"
       :imageOverride="imageOverride"
-      :style="styles"
       :shouldCalculateOptimalWidth="shouldCalculateOptimalWidth"
       class="icon-inline"
     />
@@ -21,7 +23,6 @@
       v-else
       :is="icon"
       v-bind="iconProps"
-      :style="styles"
       class="icon-inline"
     />
   </div>
@@ -124,7 +125,7 @@ export default {
     styles: ({
       color,
       withColors,
-    }) => (withColors && color ? { color: `var(--color-type-icon-${color})` } : {}),
+    }) => (withColors && color ? { '--icon-color': `var(--color-type-icon-${color})` } : {}),
   },
 };
 </script>
@@ -136,7 +137,8 @@ export default {
   width: 1em;
   height: 1em;
   flex: 0 0 auto;
-  color: var(--color-figure-gray-secondary);
+  // use the `--icon-color` if `withColors` is true, otherwise just use gray.
+  color: var(--icon-color, var(--color-figure-gray-secondary));
 
   /deep/ picture {
     flex: 1;
diff --git a/src/styles/core/colors/_light.scss b/src/styles/core/colors/_light.scss
index f36303068..0295210d1 100644
--- a/src/styles/core/colors/_light.scss
+++ b/src/styles/core/colors/_light.scss
@@ -196,4 +196,12 @@
   --color-card-eyebrow: var(--color-figure-gray-secondary-alt);
   --color-card-shadow: #{change-color(dark-color(fill), $alpha: 0.04)};
   --color-link-block-card-border: #{change-color(dark-color(fill), $alpha: 0.04)};
+
+  --color-standard-red: #8B0000;
+  --color-standard-orange: #8B4000;
+  --color-standard-yellow: #8F7200;
+  --color-standard-blue: #002D75;
+  --color-standard-green: #023B2D;
+  --color-standard-purple: #512B55;
+  --color-standard-gray: #{dark-color(fill-tertiary)};
 }
diff --git a/tests/unit/components/DocumentationTopic/DocumentationHero.spec.js b/tests/unit/components/DocumentationTopic/DocumentationHero.spec.js
index fa3f77bf3..1be0287a2 100644
--- a/tests/unit/components/DocumentationTopic/DocumentationHero.spec.js
+++ b/tests/unit/components/DocumentationTopic/DocumentationHero.spec.js
@@ -68,7 +68,8 @@ describe('DocumentationHero', () => {
     expect(wrapper.find('.default-slot').text()).toBe('Default Slot');
     expect(wrapper.find('.above-content-slot').text()).toBe('Above Content Slot');
     expect(wrapper.vm.styles).toEqual({
-      '--accent-color': `var(--color-documentation-intro-accent, var(--color-type-icon-${HeroColorsMap[defaultProps.role]}, var(--color-figure-gray-secondary)))`,
+      '--accent-color': `var(--color-documentation-intro-accent, var(--color-type-icon-${HeroColorsMap[defaultProps.role]}))`,
+      '--standard-accent-color': undefined,
     });
   });
 
@@ -114,7 +115,8 @@ describe('DocumentationHero', () => {
     });
     const color = HeroColorsMap[TopicTypeAliases[TopicTypes.init]];
     expect(wrapper.vm.styles).toEqual({
-      '--accent-color': `var(--color-documentation-intro-accent, var(--color-type-icon-${color}, var(--color-figure-gray-secondary)))`,
+      '--accent-color': `var(--color-documentation-intro-accent, var(--color-type-icon-${color}))`,
+      '--standard-accent-color': undefined,
     });
   });
 
@@ -125,7 +127,8 @@ describe('DocumentationHero', () => {
       },
     });
     expect(wrapper.vm.styles).toEqual({
-      '--accent-color': `var(--color-documentation-intro-accent, var(--color-type-icon-${HeroColors.teal}, var(--color-figure-gray-secondary)))`,
+      '--accent-color': `var(--color-documentation-intro-accent, var(--color-type-icon-${HeroColors.teal}))`,
+      '--standard-accent-color': undefined,
     });
   });
 
@@ -134,7 +137,7 @@ describe('DocumentationHero', () => {
       propsData: { role: TopicTypes.collection },
     });
     expect(wrapper.vm.styles['--accent-color'])
-      .toBe('var(--color-documentation-intro-accent, var(--color-type-icon-sky, var(--color-figure-gray-secondary)))');
+      .toBe('var(--color-documentation-intro-accent, var(--color-type-icon-sky))');
   });
 
   it('renders the DocumentationHero, disabled', () => {
@@ -148,7 +151,8 @@ describe('DocumentationHero', () => {
     // assert slot
     expect(wrapper.find('.default-slot').text()).toBe('Default Slot');
     expect(wrapper.vm.styles).toEqual({
-      '--accent-color': `var(--color-documentation-intro-accent, var(--color-type-icon-${HeroColorsMap[defaultProps.role]}, var(--color-figure-gray-secondary)))`,
+      '--accent-color': `var(--color-documentation-intro-accent, var(--color-type-icon-${HeroColorsMap[defaultProps.role]}))`,
+      '--standard-accent-color': undefined,
     });
   });
 
@@ -171,4 +175,18 @@ describe('DocumentationHero', () => {
     });
     expect(wrapper.find(TopicTypeIcon).props('type')).toBe(TopicTypes.collection);
   });
+
+  it('adds a standard-accent-color, if provided', () => {
+    const wrapper = createWrapper({
+      propsData: {
+        enhanceBackground: true,
+        role: TopicTypes.section,
+        standardColorIdentifier: 'blue',
+      },
+    });
+    expect(wrapper.vm.styles).toEqual({
+      '--accent-color': `var(--color-documentation-intro-accent, var(--color-type-icon-${HeroColors.teal}))`,
+      '--standard-accent-color': 'var(--color-standard-blue-documentation-intro-fill, var(--color-standard-blue))',
+    });
+  });
 });
diff --git a/tests/unit/components/TopicTypeIcon.spec.js b/tests/unit/components/TopicTypeIcon.spec.js
index 4e6ecfea4..ed88e9e1f 100644
--- a/tests/unit/components/TopicTypeIcon.spec.js
+++ b/tests/unit/components/TopicTypeIcon.spec.js
@@ -41,7 +41,7 @@ describe('TopicTypeIcon', () => {
     expect(iconComponent.props()).toMatchObject(bindings);
     if (color) {
       // we cannot assert on component, because JSDOM does not work with custom CSS vars
-      expect(wrapper.vm.styles).toHaveProperty('color', `var(--color-type-icon-${color})`);
+      expect(wrapper.vm.styles).toHaveProperty('--icon-color', `var(--color-type-icon-${color})`);
     }
   });
 
@@ -52,7 +52,7 @@ describe('TopicTypeIcon', () => {
         withColors: false,
       },
     });
-    expect(wrapper.vm.styles).not.toHaveProperty('color');
+    expect(wrapper.vm.styles).not.toHaveProperty('--icon-color');
   });
 
   it('renders an icon override', () => {

From 58544bd67f6ed8d1889c45036ad8c9cd98e4f911 Mon Sep 17 00:00:00 2001
From: Dobromir Hristov <dhristov@apple.com>
Date: Mon, 10 Apr 2023 10:27:25 +0300
Subject: [PATCH 2/2] refactor: add the standard colors to a constant and prop
 validators

---
 src/components/DocumentationTopic.vue         |  2 ++
 .../DocumentationTopic/DocumentationHero.vue  |  2 ++
 src/constants/StandardColors.js               | 20 +++++++++++++++++++
 3 files changed, 24 insertions(+)
 create mode 100644 src/constants/StandardColors.js

diff --git a/src/components/DocumentationTopic.vue b/src/components/DocumentationTopic.vue
index b90d53c8f..daf6409ce 100644
--- a/src/components/DocumentationTopic.vue
+++ b/src/components/DocumentationTopic.vue
@@ -157,6 +157,7 @@ import { TopicSectionsStyle } from 'docc-render/constants/TopicSectionsStyle';
 import OnThisPageNav from 'theme/components/OnThisPageNav.vue';
 import { SectionKind } from 'docc-render/constants/PrimaryContentSection';
 import Declaration from 'docc-render/components/DocumentationTopic/PrimaryContent/Declaration.vue';
+import { StandardColors } from 'docc-render/constants/StandardColors';
 import Abstract from './DocumentationTopic/Description/Abstract.vue';
 import ContentNode from './DocumentationTopic/ContentNode.vue';
 import CallToActionButton from './CallToActionButton.vue';
@@ -358,6 +359,7 @@ export default {
     standardColorIdentifier: {
       type: String,
       required: false,
+      validator: v => Object.prototype.hasOwnProperty.call(StandardColors, v),
     },
   },
   provide() {
diff --git a/src/components/DocumentationTopic/DocumentationHero.vue b/src/components/DocumentationTopic/DocumentationHero.vue
index ad3f0de9b..3a8da5877 100644
--- a/src/components/DocumentationTopic/DocumentationHero.vue
+++ b/src/components/DocumentationTopic/DocumentationHero.vue
@@ -43,6 +43,7 @@ import TopicTypeIcon from 'docc-render/components/TopicTypeIcon.vue';
 import { TopicTypes, TopicTypeAliases } from 'docc-render/constants/TopicTypes';
 import { HeroColorsMap, HeroColors } from 'docc-render/constants/HeroColors';
 import { TopicRole } from 'docc-render/constants/roles';
+import { StandardColors } from 'docc-render/constants/StandardColors';
 
 export default {
   name: 'DocumentationHero',
@@ -75,6 +76,7 @@ export default {
     standardColorIdentifier: {
       type: String,
       required: false,
+      validator: v => Object.prototype.hasOwnProperty.call(StandardColors, v),
     },
   },
   computed: {
diff --git a/src/constants/StandardColors.js b/src/constants/StandardColors.js
new file mode 100644
index 000000000..b69115281
--- /dev/null
+++ b/src/constants/StandardColors.js
@@ -0,0 +1,20 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2022 Apple Inc. and the Swift project authors
+ * Licensed under Apache License v2.0 with Runtime Library Exception
+ *
+ * See https://swift.org/LICENSE.txt for license information
+ * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+// eslint-disable-next-line import/prefer-default-export
+export const StandardColors = {
+  red: 'red',
+  orange: 'orange',
+  yellow: 'yellow',
+  blue: 'blue',
+  green: 'green',
+  purple: 'purple',
+  gray: 'gray',
+};