From ca6bd9ed31b167ab26b537498e985b700e5413f7 Mon Sep 17 00:00:00 2001 From: Cory Dransfeldt Date: Fri, 6 Jun 2025 16:05:03 -0700 Subject: [PATCH 01/10] feat(contextual-help): S2 migration --- .changeset/legal-lands-warn.md | 43 +++++++++++++++++ components/contextualhelp/dist/metadata.json | 32 +++++++++++-- components/contextualhelp/index.css | 40 +++++++++++++--- .../stories/contextualhelp.stories.js | 46 +++++++++++++++---- .../stories/contextualhelp.test.js | 9 ++-- components/contextualhelp/stories/template.js | 6 ++- 6 files changed, 152 insertions(+), 24 deletions(-) create mode 100644 .changeset/legal-lands-warn.md diff --git a/.changeset/legal-lands-warn.md b/.changeset/legal-lands-warn.md new file mode 100644 index 00000000000..454a5aeb28f --- /dev/null +++ b/.changeset/legal-lands-warn.md @@ -0,0 +1,43 @@ +--- +"@spectrum-css/contextualhelp": major +--- + +#### S2 migration for contextual help + +This migrates the `contextual help` component to the latest Spectrum 2 designs. Custom properties have been remapped and added per the design specification. + +Typographic and color tokens have been updated per design specifications. + +All existing popover positioning varations are supported. + +##### New custom properties + +`--spectrum-contextual-help-body-color` +`--spectrum-contextual-help-body-line-height` +`--spectrum-contextual-help-body-sans-serif-font-family` +`--spectrum-contextual-help-body-sans-serif-font-style` +`--spectrum-contextual-help-body-sans-serif-font-weight` +`--spectrum-contextual-help-title-color` +`--spectrum-contextual-help-title-font-style` +`--spectrum-contextual-help-title-font-weight` +`--spectrum-contextual-help-title-line-height` +`--spectrum-contextual-help-title-sans-serif-font-family` + +##### New mods + +`--mod-contextual-help-body-line-height` +`--mod-contextual-help-body-sans-serif-font-family` +`--mod-contextual-help-body-sans-serif-font-style` +`--mod-contextual-help-body-sans-serif-font-weight` +`--mod-contextual-help-body-size` +`--mod-contextual-help-title-color` +`--mod-contextual-help-title-font-style` +`--mod-contextual-help-title-font-weight` +`--mod-contextual-help-title-line-height` +`--mod-contextual-help-title-sans-serif-font-family` +`--highcontrast-contextual-help-heading-color` +`--highcontrast-contextual-help-title-color` + +##### Removed mods + +`--highcontrast-contextual-help-heading-color` diff --git a/components/contextualhelp/dist/metadata.json b/components/contextualhelp/dist/metadata.json index 8711f77b47f..1262b444e95 100644 --- a/components/contextualhelp/dist/metadata.json +++ b/components/contextualhelp/dist/metadata.json @@ -10,7 +10,16 @@ ], "modifiers": [ "--mod-contextual-help-body-color", - "--mod-contextual-help-heading-color", + "--mod-contextual-help-body-line-height", + "--mod-contextual-help-body-sans-serif-font-family", + "--mod-contextual-help-body-sans-serif-font-style", + "--mod-contextual-help-body-sans-serif-font-weight", + "--mod-contextual-help-body-size", + "--mod-contextual-help-title-color", + "--mod-contextual-help-title-font-style", + "--mod-contextual-help-title-font-weight", + "--mod-contextual-help-title-line-height", + "--mod-contextual-help-title-sans-serif-font-family", "--mod-spectrum-contextual-help-body-size", "--mod-spectrum-contextual-help-content-spacing", "--mod-spectrum-contextual-help-heading-size", @@ -20,20 +29,37 @@ "--mod-spectrum-contextual-help-popover-maximum-width" ], "component": [ + "--spectrum-contextual-help-body-color", + "--spectrum-contextual-help-body-line-height", + "--spectrum-contextual-help-body-sans-serif-font-family", + "--spectrum-contextual-help-body-sans-serif-font-style", + "--spectrum-contextual-help-body-sans-serif-font-weight", "--spectrum-contextual-help-body-size", "--spectrum-contextual-help-content-spacing", "--spectrum-contextual-help-minimum-width", + "--spectrum-contextual-help-title-color", + "--spectrum-contextual-help-title-font-style", + "--spectrum-contextual-help-title-font-weight", + "--spectrum-contextual-help-title-line-height", + "--spectrum-contextual-help-title-sans-serif-font-family", "--spectrum-contextual-help-title-size" ], "global": [ "--spectrum-body-color", + "--spectrum-body-sans-serif-font-style", + "--spectrum-body-sans-serif-font-weight", "--spectrum-heading-color", + "--spectrum-line-height-200", + "--spectrum-sans-font-family-stack", "--spectrum-spacing-300", - "--spectrum-spacing-400" + "--spectrum-spacing-400", + "--spectrum-title-line-height", + "--spectrum-title-sans-serif-font-style", + "--spectrum-title-sans-serif-font-weight" ], "passthroughs": [], "high-contrast": [ "--highcontrast-contextual-help-body-color", - "--highcontrast-contextual-help-heading-color" + "--highcontrast-contextual-help-title-color" ] } diff --git a/components/contextualhelp/index.css b/components/contextualhelp/index.css index 68152fd353b..b94e8d9ed3a 100644 --- a/components/contextualhelp/index.css +++ b/components/contextualhelp/index.css @@ -1,5 +1,5 @@ /*! - * Copyright 2024 Adobe. All rights reserved. + * Copyright 2025 Adobe. All rights reserved. * * This file is licensed to you 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 @@ -11,6 +11,22 @@ * governing permissions and limitations under the License. */ +.spectrum-ContextualHelp { + --spectrum-contextual-help-title-sans-serif-font-family: var(--spectrum-sans-font-family-stack); + --spectrum-contextual-help-title-font-weight: var(--spectrum-title-sans-serif-font-weight); + --spectrum-contextual-help-title-font-style: var(--spectrum-title-sans-serif-font-style); + --spectrum-contextual-help-title-line-height: var(--spectrum-title-line-height); + + --spectrum-contextual-help-title-color: var(--spectrum-heading-color); + + --spectrum-contextual-help-body-sans-serif-font-family: var(--spectrum-sans-font-family-stack); + --spectrum-contextual-help-body-sans-serif-font-weight: var(--spectrum-body-sans-serif-font-weight); + --spectrum-contextual-help-body-sans-serif-font-style: var(--spectrum-body-sans-serif-font-style); + --spectrum-contextual-help-body-line-height: var(--spectrum-line-height-200); + + --spectrum-contextual-help-body-color: var(--spectrum-body-color); +} + .spectrum-ContextualHelp { position: relative; min-inline-size: var(--mod-spectrum-contextual-help-minimum-width, var(--spectrum-contextual-help-minimum-width)); @@ -21,8 +37,7 @@ } .spectrum-ContextualHelp-popover { - padding-block: var(--mod-spectrum-contextual-help-padding, var(--spectrum-spacing-400)); - padding-inline: var(--mod-spectrum-contextual-help-padding, var(--spectrum-spacing-400)); + padding: var(--mod-spectrum-contextual-help-padding, var(--spectrum-spacing-400)); font-size: var(--mod-spectrum-contextual-help-body-size, var(--spectrum-contextual-help-body-size)); color: var(--highcontrast-contextual-help-body-color, var(--mod-contextual-help-body-color, var(--spectrum-body-color))); @@ -34,9 +49,22 @@ } .spectrum-ContextualHelp-heading { - margin-block-end: var(--mod-spectrum-contextual-help-content-spacing, var(--spectrum-contextual-help-content-spacing)); + font-family: var(--mod-contextual-help-title-sans-serif-font-family, var(--spectrum-contextual-help-title-sans-serif-font-family)); + font-weight: var(--mod-contextual-help-title-font-weight, var(--spectrum-contextual-help-title-font-weight)); font-size: var(--mod-spectrum-contextual-help-heading-size, var(--spectrum-contextual-help-title-size)); - color: var(--highcontrast-contextual-help-heading-color, var(--mod-contextual-help-heading-color, var(--spectrum-heading-color))); + font-style: var(--mod-contextual-help-title-font-style, var(--spectrum-contextual-help-title-font-style)); + line-height: var(--mod-contextual-help-title-line-height, var(--spectrum-contextual-help-title-line-height)); + color: var(--highcontrast-contextual-help-title-color, var(--mod-contextual-help-title-color, var(--spectrum-contextual-help-title-color))); + margin-block-end: var(--mod-spectrum-contextual-help-content-spacing, var(--spectrum-contextual-help-content-spacing)); + } + + .spectrum-ContextualHelp-body { + font-size: var(--mod-contextual-help-body-size, var(--spectrum-contextual-help-body-size)); + font-family: var(--mod-contextual-help-body-sans-serif-font-family, var(--spectrum-contextual-help-body-sans-serif-font-family)); + font-weight: var(--mod-contextual-help-body-sans-serif-font-weight, var(--spectrum-contextual-help-body-sans-serif-font-weight)); + font-style: var(--mod-contextual-help-body-sans-serif-font-style, var(--spectrum-contextual-help-body-sans-serif-font-style)); + line-height: var(--mod-contextual-help-body-line-height, var(--spectrum-contextual-help-body-line-height)); + color: var(--mod-contextual-help-body-color, var(--spectrum-contextual-help-body-color)); } } @@ -46,7 +74,7 @@ @media (forced-colors: active) { .spectrum-ContextualHelp { - --highcontrast-contextual-help-heading-color: CanvasText; + --highcontrast-contextual-help-title-color: CanvasText; --highcontrast-contextual-help-body-color: CanvasText; } } diff --git a/components/contextualhelp/stories/contextualhelp.stories.js b/components/contextualhelp/stories/contextualhelp.stories.js index 4b7abd0296a..4724d48ef34 100644 --- a/components/contextualhelp/stories/contextualhelp.stories.js +++ b/components/contextualhelp/stories/contextualhelp.stories.js @@ -31,13 +31,13 @@ export default { iconName: { name: "Icon", type: { name: "string", required: true }, - defaultValue: "Info", + defaultValue: "InfoCircle", table: { type: { summary: "string" }, category: "Component", defaultValue: { summary: "Info" }, }, - options: ["Info", "Help"], + options: ["InfoCircle", "HelpCircle"], control: "select", }, iconSet: { table: { disable: true } }, @@ -76,13 +76,43 @@ export default { ], control: "select", }, - link: { table: { disable: true } }, + link: { + name: "Display link", + type: { name: "boolean", required: false }, + defaultValue: false, + table: { + summary: "boolean", + category: "Component", + defaultValue: { summary: false } + } + }, + linkText: { + name: "Link text", + type: { name: "string", required: true }, + table: { + type: { summary: "string" }, + category: "Content", + }, + if: { arg: "link", truthy: true }, + }, + linkTarget: { + name: "Link target", + type: { name: "string", required: true }, + table: { + type: { summary: "string" }, + category: "Content", + }, + if: { arg: "link", truthy: true }, + }, }, args: { rootClass: "spectrum-ContextualHelp", - iconName: "Info", + iconName: "InfoCircle", iconSet: "workflow", popoverPlacement: "bottom-start", + link: false, + linkText: "Link text", + linkTarget: "#", title: "Permission required", body: "Your admin must grant you permission before you can create a new document. Please contact your admin for more information.", customStyles: { "inline-size": "275px" }, @@ -180,7 +210,7 @@ TopPopover.storyName = "Default - top popover"; export const HelpDefault = Template.bind({}); HelpDefault.tags = ["!dev"]; HelpDefault.args = { - iconName: "Help", + iconName: "HelpCircle", title: "Need help?", }; HelpDefault.parameters = { @@ -195,7 +225,7 @@ HelpWithLink.args = { text: "Learn about permissions", url: "#", }, - iconName: "Help", + iconName: "HelpCircle", title: "Need help?", body: "Reach out to your admin for help regarding the document you are trying to create.", }; @@ -214,7 +244,7 @@ HelpTopPopover.args = { }, title: "Need help?", body: "Reach out to your admin for help regarding the document you are trying to create.", - iconName: "Help", + iconName: "HelpCircle", }; HelpTopPopover.parameters = { chromatic: { disableSnapshot: true }, @@ -236,7 +266,7 @@ HelpMaxWidthPopover.args = { }, title: "Need help?", body: "Reach out to your admin for help regarding the document you are trying to create.", - iconName: "Help", + iconName: "HelpCircle", }; HelpMaxWidthPopover.parameters = { chromatic: { disableSnapshot: true }, diff --git a/components/contextualhelp/stories/contextualhelp.test.js b/components/contextualhelp/stories/contextualhelp.test.js index 7fea0b99dc3..5b8fd59d90a 100644 --- a/components/contextualhelp/stories/contextualhelp.test.js +++ b/components/contextualhelp/stories/contextualhelp.test.js @@ -25,14 +25,13 @@ export const ContextualHelpGroup = Variants({ "inline-size": "275px", "margin-bottom": "200px", }, - link: { - text: "Learn about permissions", - url: "#", - }, + link: true, + linkText: "Link text", + linkTarget: "#", }, { testHeading: "Help", - iconName: "Help", + iconName: "HelpCircle", customStyles: { "inline-size": "275px", "margin-bottom": "170px", diff --git a/components/contextualhelp/stories/template.js b/components/contextualhelp/stories/template.js index aaeac140d32..2dd62d19df1 100644 --- a/components/contextualhelp/stories/template.js +++ b/components/contextualhelp/stories/template.js @@ -17,6 +17,8 @@ export const Template = ({ title, body, link, + linkText, + linkTarget, popoverPlacement, customStyles = {}, customClasses = [], @@ -44,8 +46,8 @@ export const Template = ({ body ? html`

${body}

` : "", link ? Link({ - text: link.text, - url: link.url, + text: linkText, + url: linkTarget, customClasses: [`${rootClass}-link`], }) : nothing, From 4bc95135186699cf1502474540ca59414e195711 Mon Sep 17 00:00:00 2001 From: Cory Dransfeldt Date: Mon, 9 Jun 2025 16:39:09 -0700 Subject: [PATCH 02/10] fix(contextual-help): simplify link storybook controls --- .../stories/contextualhelp.stories.js | 22 +------------------ .../stories/contextualhelp.test.js | 2 -- components/contextualhelp/stories/template.js | 6 ++--- 3 files changed, 3 insertions(+), 27 deletions(-) diff --git a/components/contextualhelp/stories/contextualhelp.stories.js b/components/contextualhelp/stories/contextualhelp.stories.js index 4724d48ef34..fbf32031aa9 100644 --- a/components/contextualhelp/stories/contextualhelp.stories.js +++ b/components/contextualhelp/stories/contextualhelp.stories.js @@ -77,7 +77,7 @@ export default { control: "select", }, link: { - name: "Display link", + name: "Has link", type: { name: "boolean", required: false }, defaultValue: false, table: { @@ -86,24 +86,6 @@ export default { defaultValue: { summary: false } } }, - linkText: { - name: "Link text", - type: { name: "string", required: true }, - table: { - type: { summary: "string" }, - category: "Content", - }, - if: { arg: "link", truthy: true }, - }, - linkTarget: { - name: "Link target", - type: { name: "string", required: true }, - table: { - type: { summary: "string" }, - category: "Content", - }, - if: { arg: "link", truthy: true }, - }, }, args: { rootClass: "spectrum-ContextualHelp", @@ -111,8 +93,6 @@ export default { iconSet: "workflow", popoverPlacement: "bottom-start", link: false, - linkText: "Link text", - linkTarget: "#", title: "Permission required", body: "Your admin must grant you permission before you can create a new document. Please contact your admin for more information.", customStyles: { "inline-size": "275px" }, diff --git a/components/contextualhelp/stories/contextualhelp.test.js b/components/contextualhelp/stories/contextualhelp.test.js index 5b8fd59d90a..bb9e2be001b 100644 --- a/components/contextualhelp/stories/contextualhelp.test.js +++ b/components/contextualhelp/stories/contextualhelp.test.js @@ -26,8 +26,6 @@ export const ContextualHelpGroup = Variants({ "margin-bottom": "200px", }, link: true, - linkText: "Link text", - linkTarget: "#", }, { testHeading: "Help", diff --git a/components/contextualhelp/stories/template.js b/components/contextualhelp/stories/template.js index 2dd62d19df1..bb817768ddc 100644 --- a/components/contextualhelp/stories/template.js +++ b/components/contextualhelp/stories/template.js @@ -17,8 +17,6 @@ export const Template = ({ title, body, link, - linkText, - linkTarget, popoverPlacement, customStyles = {}, customClasses = [], @@ -46,8 +44,8 @@ export const Template = ({ body ? html`

${body}

` : "", link ? Link({ - text: linkText, - url: linkTarget, + text: "Link text", + url: "#", customClasses: [`${rootClass}-link`], }) : nothing, From 592b6a1476a71b912902e0e8537d396f331cd1b5 Mon Sep 17 00:00:00 2001 From: Cory Dransfeldt Date: Tue, 10 Jun 2025 12:38:39 -0700 Subject: [PATCH 03/10] fix(contextual-help): remove duplicative stories from docs --- .../stories/contextualhelp.stories.js | 60 ------------------- 1 file changed, 60 deletions(-) diff --git a/components/contextualhelp/stories/contextualhelp.stories.js b/components/contextualhelp/stories/contextualhelp.stories.js index fbf32031aa9..657b2a0bd67 100644 --- a/components/contextualhelp/stories/contextualhelp.stories.js +++ b/components/contextualhelp/stories/contextualhelp.stories.js @@ -198,66 +198,6 @@ HelpDefault.parameters = { }; HelpDefault.storyName = "Help icon"; -export const HelpWithLink = Template.bind({}); -HelpWithLink.tags = ["!dev"]; -HelpWithLink.args = { - link: { - text: "Learn about permissions", - url: "#", - }, - iconName: "HelpCircle", - title: "Need help?", - body: "Reach out to your admin for help regarding the document you are trying to create.", -}; -HelpWithLink.parameters = { - chromatic: { disableSnapshot: true }, -}; -HelpWithLink.storyName = "Help icon - with link"; - -export const HelpTopPopover = Template.bind({}); -HelpTopPopover.tags = ["!dev"]; -HelpTopPopover.args = { - popoverPlacement: "top", - customStyles: { - "inline-size": "275px", - "margin-top": "170px", - }, - title: "Need help?", - body: "Reach out to your admin for help regarding the document you are trying to create.", - iconName: "HelpCircle", -}; -HelpTopPopover.parameters = { - chromatic: { disableSnapshot: true }, - docs: { - story: { - height: "auto", - }, - }, -}; -HelpTopPopover.storyName = "Help icon - top popover"; - -export const HelpMaxWidthPopover = Template.bind({}); -HelpMaxWidthPopover.tags = ["!dev"]; -HelpMaxWidthPopover.args = { - customStyles: { - "inline-size": "275px", - "--mod-spectrum-contextual-help-popover-maximum-width": "180px", - "margin-bottom": "270px", - }, - title: "Need help?", - body: "Reach out to your admin for help regarding the document you are trying to create.", - iconName: "HelpCircle", -}; -HelpMaxWidthPopover.parameters = { - chromatic: { disableSnapshot: true }, - docs: { - story: { - height: "auto", - }, - }, -}; -HelpMaxWidthPopover.storyName = "Help icon - max width popover"; - // ********* VRT ONLY ********* // export const WithForcedColors = ContextualHelpGroup.bind({}); WithForcedColors.args = Default.args; From a05f95d954e2c33855fb8b425091d4df2d8f20c2 Mon Sep 17 00:00:00 2001 From: Cory Dransfeldt Date: Wed, 11 Jun 2025 11:58:47 -0700 Subject: [PATCH 04/10] fix(contextual-help): remove WHC property from changelog mods section --- .changeset/legal-lands-warn.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/.changeset/legal-lands-warn.md b/.changeset/legal-lands-warn.md index 454a5aeb28f..6548c1c553a 100644 --- a/.changeset/legal-lands-warn.md +++ b/.changeset/legal-lands-warn.md @@ -37,7 +37,3 @@ All existing popover positioning varations are supported. `--mod-contextual-help-title-sans-serif-font-family` `--highcontrast-contextual-help-heading-color` `--highcontrast-contextual-help-title-color` - -##### Removed mods - -`--highcontrast-contextual-help-heading-color` From 21fcb07bbb255843b7ff0df99982c96d8fc5386b Mon Sep 17 00:00:00 2001 From: Cory Dransfeldt Date: Tue, 17 Jun 2025 13:31:19 -0700 Subject: [PATCH 05/10] fix(contextual-help): mod names + min inline size property --- components/contextualhelp/index.css | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/components/contextualhelp/index.css b/components/contextualhelp/index.css index b94e8d9ed3a..89309dcdfcd 100644 --- a/components/contextualhelp/index.css +++ b/components/contextualhelp/index.css @@ -25,11 +25,13 @@ --spectrum-contextual-help-body-line-height: var(--spectrum-line-height-200); --spectrum-contextual-help-body-color: var(--spectrum-body-color); + + --spectrum-contextual-help-min-inline-size: var(--spectrum-contextual-help-minimum-width); } .spectrum-ContextualHelp { position: relative; - min-inline-size: var(--mod-spectrum-contextual-help-minimum-width, var(--spectrum-contextual-help-minimum-width)); + min-inline-size: var(--mod-contextual-help-min-inline-size, var(--spectrum-contextual-help-min-inline-size)); } .spectrum-ContextualHelp-button { @@ -37,11 +39,11 @@ } .spectrum-ContextualHelp-popover { - padding: var(--mod-spectrum-contextual-help-padding, var(--spectrum-spacing-400)); - font-size: var(--mod-spectrum-contextual-help-body-size, var(--spectrum-contextual-help-body-size)); + padding: var(--mod-contextual-help-padding, var(--spectrum-spacing-400)); + font-size: var(--mod-contextual-help-body-size, var(--spectrum-contextual-help-body-size)); color: var(--highcontrast-contextual-help-body-color, var(--mod-contextual-help-body-color, var(--spectrum-body-color))); - max-inline-size: var(--mod-spectrum-contextual-help-popover-maximum-width); + max-inline-size: var(--mod-contextual-help-popover-maximum-width); .spectrum-ContextualHelp-heading, .spectrum-ContextualHelp-body { @@ -51,11 +53,11 @@ .spectrum-ContextualHelp-heading { font-family: var(--mod-contextual-help-title-sans-serif-font-family, var(--spectrum-contextual-help-title-sans-serif-font-family)); font-weight: var(--mod-contextual-help-title-font-weight, var(--spectrum-contextual-help-title-font-weight)); - font-size: var(--mod-spectrum-contextual-help-heading-size, var(--spectrum-contextual-help-title-size)); + font-size: var(--mod-contextual-help-heading-size, var(--spectrum-contextual-help-title-size)); font-style: var(--mod-contextual-help-title-font-style, var(--spectrum-contextual-help-title-font-style)); line-height: var(--mod-contextual-help-title-line-height, var(--spectrum-contextual-help-title-line-height)); color: var(--highcontrast-contextual-help-title-color, var(--mod-contextual-help-title-color, var(--spectrum-contextual-help-title-color))); - margin-block-end: var(--mod-spectrum-contextual-help-content-spacing, var(--spectrum-contextual-help-content-spacing)); + margin-block-end: var(--mod-contextual-help-content-spacing, var(--spectrum-contextual-help-content-spacing)); } .spectrum-ContextualHelp-body { @@ -69,7 +71,7 @@ } .spectrum-ContextualHelp-link { - margin-block-start: var(--mod-spectrum-contextual-help-link-spacing, var(--spectrum-spacing-300)); + margin-block-start: var(--mod-contextual-help-link-spacing, var(--spectrum-spacing-300)); } @media (forced-colors: active) { From d6b893c8f1de16c007f72ca1ec1696b96d7df7e2 Mon Sep 17 00:00:00 2001 From: Cory Dransfeldt Date: Tue, 17 Jun 2025 14:03:50 -0700 Subject: [PATCH 06/10] fix(contextual-help): fix changeset typo + update formatting --- .changeset/legal-lands-warn.md | 23 +++++++++++++++---- components/contextualhelp/dist/metadata.json | 16 ++++++------- .../stories/contextualhelp.stories.js | 4 ++++ 3 files changed, 31 insertions(+), 12 deletions(-) diff --git a/.changeset/legal-lands-warn.md b/.changeset/legal-lands-warn.md index 6548c1c553a..63e5aac327d 100644 --- a/.changeset/legal-lands-warn.md +++ b/.changeset/legal-lands-warn.md @@ -4,11 +4,11 @@ #### S2 migration for contextual help -This migrates the `contextual help` component to the latest Spectrum 2 designs. Custom properties have been remapped and added per the design specification. +This migrates the contextual help component to the latest Spectrum 2 designs. Custom properties have been remapped and added per the design specification. Typographic and color tokens have been updated per design specifications. -All existing popover positioning varations are supported. +All existing popover positioning variations are supported. ##### New custom properties @@ -35,5 +35,20 @@ All existing popover positioning varations are supported. `--mod-contextual-help-title-font-weight` `--mod-contextual-help-title-line-height` `--mod-contextual-help-title-sans-serif-font-family` -`--highcontrast-contextual-help-heading-color` -`--highcontrast-contextual-help-title-color` +`--mod-contextual-help-content-spacing` +`--mod-contextual-help-heading-size` +`--mod-contextual-help-link-spacing` +`--mod-contextual-help-min-inline-size` +`--mod-contextual-help-padding` +`--mod-contextual-help-popover-maximum-width` + +##### Removed mods + +`--mod-contextual-help-title-sans-serif-font-family` +`--mod-spectrum-contextual-help-body-size` +`--mod-spectrum-contextual-help-content-spacing` +`--mod-spectrum-contextual-help-heading-size` +`--mod-spectrum-contextual-help-link-spacing` +`--mod-spectrum-contextual-help-minimum-width` +`--mod-spectrum-contextual-help-padding` +`--mod-spectrum-contextual-help-popover-maximum-width` diff --git a/components/contextualhelp/dist/metadata.json b/components/contextualhelp/dist/metadata.json index 1262b444e95..63d1981698b 100644 --- a/components/contextualhelp/dist/metadata.json +++ b/components/contextualhelp/dist/metadata.json @@ -15,18 +15,17 @@ "--mod-contextual-help-body-sans-serif-font-style", "--mod-contextual-help-body-sans-serif-font-weight", "--mod-contextual-help-body-size", + "--mod-contextual-help-content-spacing", + "--mod-contextual-help-heading-size", + "--mod-contextual-help-link-spacing", + "--mod-contextual-help-min-inline-size", + "--mod-contextual-help-padding", + "--mod-contextual-help-popover-maximum-width", "--mod-contextual-help-title-color", "--mod-contextual-help-title-font-style", "--mod-contextual-help-title-font-weight", "--mod-contextual-help-title-line-height", - "--mod-contextual-help-title-sans-serif-font-family", - "--mod-spectrum-contextual-help-body-size", - "--mod-spectrum-contextual-help-content-spacing", - "--mod-spectrum-contextual-help-heading-size", - "--mod-spectrum-contextual-help-link-spacing", - "--mod-spectrum-contextual-help-minimum-width", - "--mod-spectrum-contextual-help-padding", - "--mod-spectrum-contextual-help-popover-maximum-width" + "--mod-contextual-help-title-sans-serif-font-family" ], "component": [ "--spectrum-contextual-help-body-color", @@ -36,6 +35,7 @@ "--spectrum-contextual-help-body-sans-serif-font-weight", "--spectrum-contextual-help-body-size", "--spectrum-contextual-help-content-spacing", + "--spectrum-contextual-help-min-inline-size", "--spectrum-contextual-help-minimum-width", "--spectrum-contextual-help-title-color", "--spectrum-contextual-help-title-font-style", diff --git a/components/contextualhelp/stories/contextualhelp.stories.js b/components/contextualhelp/stories/contextualhelp.stories.js index 657b2a0bd67..4a99c70e7f0 100644 --- a/components/contextualhelp/stories/contextualhelp.stories.js +++ b/components/contextualhelp/stories/contextualhelp.stories.js @@ -112,7 +112,11 @@ export default { height: "200px", }, }, + status: { + type: "migrated", + }, }, + tags: ["migrated"] }; /** From 443dc96cc718956ccd68ca6408d8e6c7a7644150 Mon Sep 17 00:00:00 2001 From: Cory Dransfeldt Date: Tue, 17 Jun 2025 14:16:34 -0700 Subject: [PATCH 07/10] fix(contextual-help): abstract out direct token references --- components/contextualhelp/index.css | 13 ++++++++++--- .../stories/contextualhelp.stories.js | 2 +- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/components/contextualhelp/index.css b/components/contextualhelp/index.css index 89309dcdfcd..bc41c5bfadf 100644 --- a/components/contextualhelp/index.css +++ b/components/contextualhelp/index.css @@ -17,7 +17,7 @@ --spectrum-contextual-help-title-font-style: var(--spectrum-title-sans-serif-font-style); --spectrum-contextual-help-title-line-height: var(--spectrum-title-line-height); - --spectrum-contextual-help-title-color: var(--spectrum-heading-color); + --spectrum-contextual-help-title-color: var(--spectrum-title-color); --spectrum-contextual-help-body-sans-serif-font-family: var(--spectrum-sans-font-family-stack); --spectrum-contextual-help-body-sans-serif-font-weight: var(--spectrum-body-sans-serif-font-weight); @@ -27,6 +27,13 @@ --spectrum-contextual-help-body-color: var(--spectrum-body-color); --spectrum-contextual-help-min-inline-size: var(--spectrum-contextual-help-minimum-width); + --spectrum-contextual-help-link-spacing: var(--spectrum-spacing-300); + --spectrum-contextual-help-padding: var(--spectrum-spacing-400); + + /* @passthrough start */ + --mod-popover-corner-radius: var(--spectrum-corner-radius-large-default); + --mod-popover-animation-distance: var(--spectrum-picker-popover-animation-distance); + /* @passthrough end */ } .spectrum-ContextualHelp { @@ -39,7 +46,7 @@ } .spectrum-ContextualHelp-popover { - padding: var(--mod-contextual-help-padding, var(--spectrum-spacing-400)); + padding: var(--mod-contextual-help-padding, var(--spectrum-contextual-help-padding)); font-size: var(--mod-contextual-help-body-size, var(--spectrum-contextual-help-body-size)); color: var(--highcontrast-contextual-help-body-color, var(--mod-contextual-help-body-color, var(--spectrum-body-color))); @@ -71,7 +78,7 @@ } .spectrum-ContextualHelp-link { - margin-block-start: var(--mod-contextual-help-link-spacing, var(--spectrum-spacing-300)); + margin-block-start: var(--mod-contextual-help-link-spacing, var(--spectrum-contextual-help-link-spacing)); } @media (forced-colors: active) { diff --git a/components/contextualhelp/stories/contextualhelp.stories.js b/components/contextualhelp/stories/contextualhelp.stories.js index 4a99c70e7f0..6e37461c4eb 100644 --- a/components/contextualhelp/stories/contextualhelp.stories.js +++ b/components/contextualhelp/stories/contextualhelp.stories.js @@ -113,7 +113,7 @@ export default { }, }, status: { - type: "migrated", + type: "migrated", }, }, tags: ["migrated"] From e45203da4ead6e2ea1ae120c883758084c6a4b56 Mon Sep 17 00:00:00 2001 From: Cory Dransfeldt Date: Tue, 17 Jun 2025 15:04:19 -0700 Subject: [PATCH 08/10] fix(contextual-help): update metadata --- components/contextualhelp/dist/metadata.json | 15 +++++++++++++-- components/contextualhelp/index.css | 11 ++++++++++- components/contextualhelp/stories/template.js | 5 ++++- 3 files changed, 27 insertions(+), 4 deletions(-) diff --git a/components/contextualhelp/dist/metadata.json b/components/contextualhelp/dist/metadata.json index 63d1981698b..6aa3d096aab 100644 --- a/components/contextualhelp/dist/metadata.json +++ b/components/contextualhelp/dist/metadata.json @@ -15,6 +15,7 @@ "--mod-contextual-help-body-sans-serif-font-style", "--mod-contextual-help-body-sans-serif-font-weight", "--mod-contextual-help-body-size", + "--mod-contextual-help-border-radius", "--mod-contextual-help-content-spacing", "--mod-contextual-help-heading-size", "--mod-contextual-help-link-spacing", @@ -34,9 +35,12 @@ "--spectrum-contextual-help-body-sans-serif-font-style", "--spectrum-contextual-help-body-sans-serif-font-weight", "--spectrum-contextual-help-body-size", + "--spectrum-contextual-help-border-radius", "--spectrum-contextual-help-content-spacing", + "--spectrum-contextual-help-link-spacing", "--spectrum-contextual-help-min-inline-size", "--spectrum-contextual-help-minimum-width", + "--spectrum-contextual-help-padding", "--spectrum-contextual-help-title-color", "--spectrum-contextual-help-title-font-style", "--spectrum-contextual-help-title-font-weight", @@ -48,16 +52,23 @@ "--spectrum-body-color", "--spectrum-body-sans-serif-font-style", "--spectrum-body-sans-serif-font-weight", - "--spectrum-heading-color", + "--spectrum-component-to-menu-large", + "--spectrum-component-to-menu-medium", + "--spectrum-corner-radius-large-default", "--spectrum-line-height-200", + "--spectrum-picker-popover-animation-distance", "--spectrum-sans-font-family-stack", "--spectrum-spacing-300", "--spectrum-spacing-400", + "--spectrum-title-color", "--spectrum-title-line-height", "--spectrum-title-sans-serif-font-style", "--spectrum-title-sans-serif-font-weight" ], - "passthroughs": [], + "passthroughs": [ + "--mod-popover-animation-distance", + "--mod-popover-corner-radius" + ], "high-contrast": [ "--highcontrast-contextual-help-body-color", "--highcontrast-contextual-help-title-color" diff --git a/components/contextualhelp/index.css b/components/contextualhelp/index.css index bc41c5bfadf..cd048e64ea6 100644 --- a/components/contextualhelp/index.css +++ b/components/contextualhelp/index.css @@ -30,9 +30,14 @@ --spectrum-contextual-help-link-spacing: var(--spectrum-spacing-300); --spectrum-contextual-help-padding: var(--spectrum-spacing-400); + --spectrum-contextual-help-border-radius: var(--mod-contextual-help-border-radius, var(--mod-popover-corner-radius)); + /* @passthrough start */ - --mod-popover-corner-radius: var(--spectrum-corner-radius-large-default); + /* stylelint-disable-next-line spectrum-tools/no-unused-custom-properties -- used to assign Popover mods */ + --spectrum-picker-popover-animation-distance: var(--spectrum-component-to-menu-medium); + --mod-popover-animation-distance: var(--spectrum-picker-popover-animation-distance); + --mod-popover-corner-radius: var(--spectrum-corner-radius-large-default); /* @passthrough end */ } @@ -46,9 +51,13 @@ } .spectrum-ContextualHelp-popover { + /* stylelint-disable-next-line spectrum-tools/no-unused-custom-properties -- used to assign Popover mods */ + --spectrum-picker-popover-animation-distance: var(--spectrum-component-to-menu-large); + padding: var(--mod-contextual-help-padding, var(--spectrum-contextual-help-padding)); font-size: var(--mod-contextual-help-body-size, var(--spectrum-contextual-help-body-size)); color: var(--highcontrast-contextual-help-body-color, var(--mod-contextual-help-body-color, var(--spectrum-body-color))); + border-radius: var(--spectrum-contextual-help-border-radius); max-inline-size: var(--mod-contextual-help-popover-maximum-width); diff --git a/components/contextualhelp/stories/template.js b/components/contextualhelp/stories/template.js index bb817768ddc..f6097cfd151 100644 --- a/components/contextualhelp/stories/template.js +++ b/components/contextualhelp/stories/template.js @@ -21,6 +21,9 @@ export const Template = ({ customStyles = {}, customClasses = [], } = {}, context = {}) => { + const { globals = {} } = context; + const scale = globals.scale ?? "medium"; + return html`
ActionButton({ ...passthrough, - size: "xs", + size: scale === "medium" ? "xs" : "s", iconName, iconSet, customClasses: [`${rootClass}-button`], From 1949500040ec7b4360441514cb255f96feea8290 Mon Sep 17 00:00:00 2001 From: Cory Dransfeldt Date: Tue, 17 Jun 2025 16:40:06 -0700 Subject: [PATCH 09/10] fix(contextual-help): update border-radius passthrough --- components/contextualhelp/dist/metadata.json | 2 +- components/contextualhelp/index.css | 4 +-- .../stories/contextualhelp.stories.js | 27 +++---------------- .../stories/contextualhelp.test.js | 12 ++------- 4 files changed, 8 insertions(+), 37 deletions(-) diff --git a/components/contextualhelp/dist/metadata.json b/components/contextualhelp/dist/metadata.json index 6aa3d096aab..35dea0cd529 100644 --- a/components/contextualhelp/dist/metadata.json +++ b/components/contextualhelp/dist/metadata.json @@ -15,7 +15,6 @@ "--mod-contextual-help-body-sans-serif-font-style", "--mod-contextual-help-body-sans-serif-font-weight", "--mod-contextual-help-body-size", - "--mod-contextual-help-border-radius", "--mod-contextual-help-content-spacing", "--mod-contextual-help-heading-size", "--mod-contextual-help-link-spacing", @@ -58,6 +57,7 @@ "--spectrum-line-height-200", "--spectrum-picker-popover-animation-distance", "--spectrum-sans-font-family-stack", + "--spectrum-spacing-100", "--spectrum-spacing-300", "--spectrum-spacing-400", "--spectrum-title-color", diff --git a/components/contextualhelp/index.css b/components/contextualhelp/index.css index cd048e64ea6..0103c395376 100644 --- a/components/contextualhelp/index.css +++ b/components/contextualhelp/index.css @@ -30,13 +30,13 @@ --spectrum-contextual-help-link-spacing: var(--spectrum-spacing-300); --spectrum-contextual-help-padding: var(--spectrum-spacing-400); - --spectrum-contextual-help-border-radius: var(--mod-contextual-help-border-radius, var(--mod-popover-corner-radius)); + --spectrum-contextual-help-border-radius: var(--mod-popover-corner-radius); /* @passthrough start */ /* stylelint-disable-next-line spectrum-tools/no-unused-custom-properties -- used to assign Popover mods */ --spectrum-picker-popover-animation-distance: var(--spectrum-component-to-menu-medium); - --mod-popover-animation-distance: var(--spectrum-picker-popover-animation-distance); + --mod-popover-animation-distance: var(--spectrum-spacing-100); --mod-popover-corner-radius: var(--spectrum-corner-radius-large-default); /* @passthrough end */ } diff --git a/components/contextualhelp/stories/contextualhelp.stories.js b/components/contextualhelp/stories/contextualhelp.stories.js index 6e37461c4eb..117912f633b 100644 --- a/components/contextualhelp/stories/contextualhelp.stories.js +++ b/components/contextualhelp/stories/contextualhelp.stories.js @@ -95,7 +95,7 @@ export default { link: false, title: "Permission required", body: "Your admin must grant you permission before you can create a new document. Please contact your admin for more information.", - customStyles: { "inline-size": "275px" }, + customStyles: { "inline-size": "var(--spectrum-contextual-help-min-inline-size)" }, }, parameters: { actions: { @@ -144,28 +144,6 @@ WithLink.parameters = { }; WithLink.storyName = "Default - info icon with link"; -/** - * In order to further customize the contextual help popover, implementations can set `--mod-spectrum-contextual-help-popover-maximum-width` to their desired max width. - */ -export const MaxWidthPopover = Template.bind({}); -MaxWidthPopover.tags = ["!dev"]; -MaxWidthPopover.args = { - customStyles: { - "inline-size": "275px", - "--mod-spectrum-contextual-help-popover-maximum-width": "180px", - "margin-bottom": "270px", - }, -}; -MaxWidthPopover.parameters = { - chromatic: { disableSnapshot: true }, - docs: { - story: { - height: "auto", - }, - }, -}; -MaxWidthPopover.storyName = "Default - max width popover"; - /** * This is an example of the contextual help component within a popover with a placement of `top`. Read more about the 22 available placement positions in the [popover documentation](/docs/components-popover--docs). */ @@ -174,7 +152,6 @@ TopPopover.tags = ["!dev"]; TopPopover.args = { popoverPlacement: "top", customStyles: { - "inline-size": "275px", "margin-top": "170px", }, }; @@ -190,6 +167,8 @@ TopPopover.storyName = "Default - top popover"; /** * When displaying help or resources to learn more, the contextual help should use the help icon. The content in this variant provides more detailed, in-depth guidance about a task, UI element, tool or keyboard shortcuts. + * + * All variants and positions of the contextual help component can be configured with a help icon. */ export const HelpDefault = Template.bind({}); HelpDefault.tags = ["!dev"]; diff --git a/components/contextualhelp/stories/contextualhelp.test.js b/components/contextualhelp/stories/contextualhelp.test.js index bb9e2be001b..c0b64328f14 100644 --- a/components/contextualhelp/stories/contextualhelp.test.js +++ b/components/contextualhelp/stories/contextualhelp.test.js @@ -8,15 +8,7 @@ export const ContextualHelpGroup = Variants({ testHeading: "Default", customStyles: { "inline-size": "275px", - "margin-bottom": "170px", - }, - }, - { - testHeading: "Max-width popover", - customStyles: { - "inline-size": "275px", - "margin-bottom": "275px", - "--mod-spectrum-contextual-help-popover-maximum-width": "150px", + "margin-bottom": "200px", }, }, { @@ -32,7 +24,7 @@ export const ContextualHelpGroup = Variants({ iconName: "HelpCircle", customStyles: { "inline-size": "275px", - "margin-bottom": "170px", + "margin-bottom": "200px", }, }, ], From ef683644d237c6fbe48d9594d5f3320042614978 Mon Sep 17 00:00:00 2001 From: Cory Dransfeldt Date: Fri, 20 Jun 2025 08:43:22 -0700 Subject: [PATCH 10/10] fix(contextual-help): remove unnecessary custom properties --- components/contextualhelp/dist/metadata.json | 4 ---- components/contextualhelp/index.css | 9 --------- 2 files changed, 13 deletions(-) diff --git a/components/contextualhelp/dist/metadata.json b/components/contextualhelp/dist/metadata.json index 35dea0cd529..a64ded05750 100644 --- a/components/contextualhelp/dist/metadata.json +++ b/components/contextualhelp/dist/metadata.json @@ -34,7 +34,6 @@ "--spectrum-contextual-help-body-sans-serif-font-style", "--spectrum-contextual-help-body-sans-serif-font-weight", "--spectrum-contextual-help-body-size", - "--spectrum-contextual-help-border-radius", "--spectrum-contextual-help-content-spacing", "--spectrum-contextual-help-link-spacing", "--spectrum-contextual-help-min-inline-size", @@ -51,11 +50,8 @@ "--spectrum-body-color", "--spectrum-body-sans-serif-font-style", "--spectrum-body-sans-serif-font-weight", - "--spectrum-component-to-menu-large", - "--spectrum-component-to-menu-medium", "--spectrum-corner-radius-large-default", "--spectrum-line-height-200", - "--spectrum-picker-popover-animation-distance", "--spectrum-sans-font-family-stack", "--spectrum-spacing-100", "--spectrum-spacing-300", diff --git a/components/contextualhelp/index.css b/components/contextualhelp/index.css index 0103c395376..c416b8395c0 100644 --- a/components/contextualhelp/index.css +++ b/components/contextualhelp/index.css @@ -30,12 +30,7 @@ --spectrum-contextual-help-link-spacing: var(--spectrum-spacing-300); --spectrum-contextual-help-padding: var(--spectrum-spacing-400); - --spectrum-contextual-help-border-radius: var(--mod-popover-corner-radius); - /* @passthrough start */ - /* stylelint-disable-next-line spectrum-tools/no-unused-custom-properties -- used to assign Popover mods */ - --spectrum-picker-popover-animation-distance: var(--spectrum-component-to-menu-medium); - --mod-popover-animation-distance: var(--spectrum-spacing-100); --mod-popover-corner-radius: var(--spectrum-corner-radius-large-default); /* @passthrough end */ @@ -51,13 +46,9 @@ } .spectrum-ContextualHelp-popover { - /* stylelint-disable-next-line spectrum-tools/no-unused-custom-properties -- used to assign Popover mods */ - --spectrum-picker-popover-animation-distance: var(--spectrum-component-to-menu-large); - padding: var(--mod-contextual-help-padding, var(--spectrum-contextual-help-padding)); font-size: var(--mod-contextual-help-body-size, var(--spectrum-contextual-help-body-size)); color: var(--highcontrast-contextual-help-body-color, var(--mod-contextual-help-body-color, var(--spectrum-body-color))); - border-radius: var(--spectrum-contextual-help-border-radius); max-inline-size: var(--mod-contextual-help-popover-maximum-width);