diff --git a/.changeset/legal-lands-warn.md b/.changeset/legal-lands-warn.md new file mode 100644 index 00000000000..63e5aac327d --- /dev/null +++ b/.changeset/legal-lands-warn.md @@ -0,0 +1,54 @@ +--- +"@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 variations 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` +`--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 8711f77b47f..a64ded05750 100644 --- a/components/contextualhelp/dist/metadata.json +++ b/components/contextualhelp/dist/metadata.json @@ -10,30 +10,63 @@ ], "modifiers": [ "--mod-contextual-help-body-color", - "--mod-contextual-help-heading-color", - "--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-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-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" ], "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-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", + "--spectrum-contextual-help-title-line-height", + "--spectrum-contextual-help-title-sans-serif-font-family", "--spectrum-contextual-help-title-size" ], "global": [ "--spectrum-body-color", - "--spectrum-heading-color", + "--spectrum-body-sans-serif-font-style", + "--spectrum-body-sans-serif-font-weight", + "--spectrum-corner-radius-large-default", + "--spectrum-line-height-200", + "--spectrum-sans-font-family-stack", + "--spectrum-spacing-100", "--spectrum-spacing-300", - "--spectrum-spacing-400" + "--spectrum-spacing-400", + "--spectrum-title-color", + "--spectrum-title-line-height", + "--spectrum-title-sans-serif-font-style", + "--spectrum-title-sans-serif-font-weight" + ], + "passthroughs": [ + "--mod-popover-animation-distance", + "--mod-popover-corner-radius" ], - "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..c416b8395c0 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,9 +11,34 @@ * 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-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); + --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-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-animation-distance: var(--spectrum-spacing-100); + --mod-popover-corner-radius: var(--spectrum-corner-radius-large-default); + /* @passthrough end */ +} + .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 { @@ -21,12 +46,11 @@ } .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)); - font-size: var(--mod-spectrum-contextual-help-body-size, var(--spectrum-contextual-help-body-size)); + 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))); - 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 { @@ -34,19 +58,32 @@ } .spectrum-ContextualHelp-heading { - margin-block-end: var(--mod-spectrum-contextual-help-content-spacing, var(--spectrum-contextual-help-content-spacing)); - 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-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-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-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)); } } .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-contextual-help-link-spacing)); } @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..117912f633b 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,16 +76,26 @@ export default { ], control: "select", }, - link: { table: { disable: true } }, + link: { + name: "Has link", + type: { name: "boolean", required: false }, + defaultValue: false, + table: { + summary: "boolean", + category: "Component", + defaultValue: { summary: false } + } + }, }, args: { rootClass: "spectrum-ContextualHelp", - iconName: "Info", + iconName: "InfoCircle", iconSet: "workflow", popoverPlacement: "bottom-start", + 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: { @@ -102,7 +112,11 @@ export default { height: "200px", }, }, + status: { + type: "migrated", + }, }, + tags: ["migrated"] }; /** @@ -130,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). */ @@ -160,7 +152,6 @@ TopPopover.tags = ["!dev"]; TopPopover.args = { popoverPlacement: "top", customStyles: { - "inline-size": "275px", "margin-top": "170px", }, }; @@ -176,11 +167,13 @@ 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"]; HelpDefault.args = { - iconName: "Help", + iconName: "HelpCircle", title: "Need help?", }; HelpDefault.parameters = { @@ -188,66 +181,6 @@ HelpDefault.parameters = { }; HelpDefault.storyName = "Help icon"; -export const HelpWithLink = Template.bind({}); -HelpWithLink.tags = ["!dev"]; -HelpWithLink.args = { - link: { - text: "Learn about permissions", - url: "#", - }, - iconName: "Help", - 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: "Help", -}; -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: "Help", -}; -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; diff --git a/components/contextualhelp/stories/contextualhelp.test.js b/components/contextualhelp/stories/contextualhelp.test.js index 7fea0b99dc3..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", }, }, { @@ -25,17 +17,14 @@ export const ContextualHelpGroup = Variants({ "inline-size": "275px", "margin-bottom": "200px", }, - link: { - text: "Learn about permissions", - url: "#", - }, + link: true, }, { testHeading: "Help", - iconName: "Help", + iconName: "HelpCircle", customStyles: { "inline-size": "275px", - "margin-bottom": "170px", + "margin-bottom": "200px", }, }, ], diff --git a/components/contextualhelp/stories/template.js b/components/contextualhelp/stories/template.js index aaeac140d32..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`], @@ -44,8 +47,8 @@ export const Template = ({ body ? html`

${body}

` : "", link ? Link({ - text: link.text, - url: link.url, + text: "Link text", + url: "#", customClasses: [`${rootClass}-link`], }) : nothing,