diff --git a/.changeset/poor-coins-fix.md b/.changeset/poor-coins-fix.md new file mode 100644 index 00000000..45665280 --- /dev/null +++ b/.changeset/poor-coins-fix.md @@ -0,0 +1,5 @@ +--- +"@primer/css": minor +--- + +Updating deprecations.js file to be more straightforward diff --git a/__tests__/css.test.js b/__tests__/css.test.js index 40dc5b3a..32c237ac 100644 --- a/__tests__/css.test.js +++ b/__tests__/css.test.js @@ -1,7 +1,5 @@ import { getCurrentVersion, - getDeprecatedSelectors, - getDeprecatedVariables, getPackageStats, getSelectorDiff, getVariableDiff @@ -10,17 +8,6 @@ import semver from 'semver' let selectorsDiff, variablesDiff, version -// Because of a change in analyzer this was incorrectly in the list -const variableAllowList = ['$marketing-all-spacers'] -const selectorAllowList = [ - '.Truncate .Truncate-text', - '.Truncate .Truncate-text+.Truncate-text', - '.Truncate .Truncate-text.Truncate-text--expandable:active', - '.Truncate .Truncate-text.Truncate-text--expandable:focus', - '.Truncate .Truncate-text.Truncate-text--expandable:hover', - '.Truncate .Truncate-text.Truncate-text--primary' -] - beforeAll(async () => { selectorsDiff = getSelectorDiff() variablesDiff = getVariableDiff() @@ -33,48 +20,3 @@ describe('css', () => { expect(supportStats.size).toEqual(0) }) }) - -describe('deprecations', () => { - it('A selector was marked as deprecated but not removed from the codebase', () => { - const removed = selectorsDiff['removed'] - const deprecations = getDeprecatedSelectors(version.raw) - if (deprecations.length) { - // Selectors were marked to be deprecated in this version, - // but were not removed from the codebase. Please remove these selectors. - expect(deprecations.sort()).toEqual(removed.sort()) // eslint-disable-line jest/no-conditional-expect - } - }) - - it('A selector was removed from the codebase but not added to upcoming major release deprecations file.', () => { - const removedSelectors = selectorsDiff['removed'].filter(v => !selectorAllowList.includes(v)) - - if (version.minor !== 0 && version.patch !== 0) { - const nextMajor = semver.inc(version.raw, 'major') - const deprecations = getDeprecatedSelectors(nextMajor) - // Some classes were removed from the codebase, but not found - // in the next upcoming major release deprecation.js - expect(deprecations.sort()).toEqual(expect.arrayContaining(removedSelectors.sort())) // eslint-disable-line jest/no-conditional-expect - } - }) - - it('A variable was marked as deprecated but not removed from the codebase', () => { - const removed = variablesDiff.removed - const deprecations = getDeprecatedVariables(version.raw) - if (deprecations.length) { - // Variables were marked to be deprecated in this version, - // but were not removed from the codebase. Please remove these variables. - expect(deprecations.sort()).toEqual(removed.sort()) // eslint-disable-line jest/no-conditional-expect - } - }) - - it('A variable was removed from the codebase and added to upcoming major release deprecations file.', () => { - const removed = variablesDiff.removed.filter(v => !variableAllowList.includes(v)) - if (version.minor !== 0 && version.patch !== 0) { - const nextMajor = semver.inc(version.raw, 'major') - const deprecations = getDeprecatedVariables(nextMajor) - // Some variables were removed from the codebase, but not found - // in the next upcoming major release deprecation.json - expect(deprecations).toEqual(expect.arrayContaining(removed)) // eslint-disable-line jest/no-conditional-expect - } - }) -}) diff --git a/__tests__/utils/css.js b/__tests__/utils/css.js index cb8508af..c3b44314 100644 --- a/__tests__/utils/css.js +++ b/__tests__/utils/css.js @@ -33,20 +33,6 @@ export function getCurrentVersion() { return semver.parse(pkg.version) } -export function getDeprecatedSelectors(version) { - if (getCurrentVersion().raw === version) return [] - let deprecations = JSON.parse(fs.readFileSync(join(currentPath, './dist/deprecations.json'))) - deprecations = deprecations.versions[version] || [] - return deprecations.reduce((list, deprecation) => list.concat(deprecation.selectors), []).filter(v => v) -} - -export function getDeprecatedVariables(version) { - if (getCurrentVersion().raw === version) return [] - let deprecations = JSON.parse(fs.readFileSync(join(currentPath, './dist/deprecations.json'))) - deprecations = deprecations.versions[version] || [] - return deprecations.reduce((list, deprecation) => list.concat(deprecation.variables), []).filter(v => v) -} - export function getPackageStats(packageName) { const stats = JSON.parse(fs.readFileSync(join(currentPath, './dist', `./stats/${packageName}.json`))) return stats diff --git a/deprecations.js b/deprecations.js index a162d17f..33f67f41 100644 --- a/deprecations.js +++ b/deprecations.js @@ -1,749 +1,24 @@ +/** + Deprecated Selectors + ------------------------- + These are deprecated selectors and should not be used. They include a replacement value, + which can be an array or null. + + * 'deprecated-selector': 'replacement-selector' <-- Replace with this selector. + * 'deprecated-selector': ['replacement-1', 'replacement-2'] <-- Replace with one of these selectors. + * 'deprecated-selector': null <-- No option available, remove selector. +*/ + import fs from 'fs' -/* - * This object's keys are (semver) version numbers, and the - * values are arrays of objects each with a "selectors" - * array and a "message" string. - */ -const versionDeprecations = { - '17.6.1': [ - { - selectors: [ - '.break-word' - ], - message: 'The .break-word class has been deprecated, use .wb-break-word instead.' - } - ], - '17.0.0': [ - { - variables: ['$h000-size', '$h000-size-mobile'], - message: `This variable is deprecated, please refer to the Marketing Typography documentation.` - }, - { - selectors: ['.h000-mktg', '.h00-mktg', '.lead-mktg'], - message: `This selector is deprecated, please refer to the Marketing Typography documentation.` - }, - { - selectors: [ - '.p-7', - '.p-8', - '.p-9', - '.p-10', - '.p-11', - '.p-12', - '.p-sm-7', - '.p-sm-8', - '.p-sm-9', - '.p-sm-10', - '.p-sm-11', - '.p-sm-12', - '.p-md-7', - '.p-md-8', - '.p-md-9', - '.p-md-10', - '.p-md-11', - '.p-md-12', - '.p-lg-7', - '.p-lg-8', - '.p-lg-9', - '.p-lg-10', - '.p-lg-11', - '.p-lg-12', - '.p-xl-7', - '.p-xl-8', - '.p-xl-9', - '.p-xl-10', - '.p-xl-11', - '.p-xl-12' - ], - message: `This selector is deprecated, please use pt-X, pr-X, pb-X, and pl-X to set paddings on all sides above spacing level 6.` - }, - { - selectors: [ - '.top-n0', - '.right-n0', - '.bottom-n0', - '.left-n0', - '.top-md-n0', - '.right-md-n0', - '.bottom-md-n0', - '.left-md-n0', - '.top-lg-n0', - '.right-lg-n0', - '.bottom-lg-n0', - '.left-lg-n0', - '.mt-n0', - '.mb-n0', - '.mt-sm-n0', - '.mb-sm-n0', - '.mt-md-n0', - '.mb-md-n0', - '.mt-lg-n0', - '.mb-lg-n0', - '.mt-xl-n0', - '.mb-xl-n0' - ], - message: `This selector is deprecated, please use a non-negative selector to set the value to 0 (e.g. top-md-0).` - }, - { - selectors: ['.bg-shade-gradient'], - message: `This selector is deprecated, please use "color-bg-secondary" instead of "bg-shade-gradient".` - }, - { - selectors: ['.color-border-overlay'], - message: `Please use the ".color-border-primary" class instead of ".color-border-overlay".` - }, - { - selectors: [':-ms-input-placeholder'], - message: 'Browserslist update to match github has removed the need for this pseudoselector' - } - ], - '16.0.0': [ - { - selectors: [ - '.btn-blue', - '.btn-blue:focus', - '.btn-blue.focus', - '.btn-blue:hover', - '.btn-blue.hover', - '.btn-blue:active', - '.btn-blue.selected', - '.btn-blue[aria-selected=true]', - '[open]>.btn-blue', - '.btn-blue:disabled', - '.btn-blue.disabled', - '.btn-blue[aria-disabled=true]', - '.btn-blue .Counter', - '.markdown-body li', - '.input-dark', - '.input-dark:-ms-input-placeholder', - '.input-dark::-ms-input-placeholder', - '.input-dark::placeholder', - '.input-dark.focus', - '.input-dark:focus', - '::-ms-input-placeholder', - '.border-blue', - '.border-blue-light', - '.border-green', - '.border-green-light', - '.border-red', - '.border-red-light', - '.border-purple', - '.border-yellow', - '.border-gray-light', - '.border-gray-dark', - '.border-black-fade', - '.border-white-fade', - '.border-white-fade-15', - '.border-white-fade-30', - '.border-white-fade-50', - '.border-white-fade-70', - '.border-white-fade-85', - '.box-shadow', - '.box-shadow-medium', - '.box-shadow-large', - '.box-shadow-extra-large', - '.bg-white', - '.bg-blue', - '.bg-blue-light', - '.bg-gray-dark', - '.bg-gray', - '.bg-gray-light', - '.bg-green', - '.bg-green-light', - '.bg-red', - '.bg-red-light', - '.bg-yellow', - '.bg-yellow-light', - '.bg-yellow-dark', - '.bg-purple', - '.bg-pink', - '.bg-purple-light', - '.bg-orange', - '.color-gray-0', - '.bg-gray-0', - '.color-gray-1', - '.bg-gray-1', - '.color-gray-2', - '.bg-gray-2', - '.color-gray-3', - '.bg-gray-3', - '.color-gray-4', - '.bg-gray-4', - '.color-gray-5', - '.bg-gray-5', - '.color-gray-6', - '.bg-gray-6', - '.color-gray-7', - '.bg-gray-7', - '.color-gray-8', - '.bg-gray-8', - '.color-gray-9', - '.bg-gray-9', - '.color-blue-0', - '.bg-blue-0', - '.color-blue-1', - '.bg-blue-1', - '.color-blue-2', - '.bg-blue-2', - '.color-blue-3', - '.bg-blue-3', - '.color-blue-4', - '.bg-blue-4', - '.color-blue-5', - '.bg-blue-5', - '.color-blue-6', - '.bg-blue-6', - '.color-blue-7', - '.bg-blue-7', - '.color-blue-8', - '.bg-blue-8', - '.color-blue-9', - '.bg-blue-9', - '.color-green-0', - '.bg-green-0', - '.color-green-1', - '.bg-green-1', - '.color-green-2', - '.bg-green-2', - '.color-green-3', - '.bg-green-3', - '.color-green-4', - '.bg-green-4', - '.color-green-5', - '.bg-green-5', - '.color-green-6', - '.bg-green-6', - '.color-green-7', - '.bg-green-7', - '.color-green-8', - '.bg-green-8', - '.color-green-9', - '.bg-green-9', - '.color-yellow-0', - '.bg-yellow-0', - '.color-yellow-1', - '.bg-yellow-1', - '.color-yellow-2', - '.bg-yellow-2', - '.color-yellow-3', - '.bg-yellow-3', - '.color-yellow-4', - '.bg-yellow-4', - '.color-yellow-5', - '.bg-yellow-5', - '.color-yellow-6', - '.bg-yellow-6', - '.color-yellow-7', - '.bg-yellow-7', - '.color-yellow-8', - '.bg-yellow-8', - '.color-yellow-9', - '.bg-yellow-9', - '.color-orange-0', - '.bg-orange-0', - '.color-orange-1', - '.bg-orange-1', - '.color-orange-2', - '.bg-orange-2', - '.color-orange-3', - '.bg-orange-3', - '.color-orange-4', - '.bg-orange-4', - '.color-orange-5', - '.bg-orange-5', - '.color-orange-6', - '.bg-orange-6', - '.color-orange-7', - '.bg-orange-7', - '.color-orange-8', - '.bg-orange-8', - '.color-orange-9', - '.bg-orange-9', - '.color-red-0', - '.bg-red-0', - '.color-red-1', - '.bg-red-1', - '.color-red-2', - '.bg-red-2', - '.color-red-3', - '.bg-red-3', - '.color-red-4', - '.bg-red-4', - '.color-red-5', - '.bg-red-5', - '.color-red-6', - '.bg-red-6', - '.color-red-7', - '.bg-red-7', - '.color-red-8', - '.bg-red-8', - '.color-red-9', - '.bg-red-9', - '.color-purple-0', - '.bg-purple-0', - '.color-purple-1', - '.bg-purple-1', - '.color-purple-2', - '.bg-purple-2', - '.color-purple-3', - '.bg-purple-3', - '.color-purple-4', - '.bg-purple-4', - '.color-purple-5', - '.bg-purple-5', - '.color-purple-6', - '.bg-purple-6', - '.color-purple-7', - '.bg-purple-7', - '.color-purple-8', - '.bg-purple-8', - '.color-purple-9', - '.bg-purple-9', - '.color-pink-0', - '.bg-pink-0', - '.color-pink-1', - '.bg-pink-1', - '.color-pink-2', - '.bg-pink-2', - '.color-pink-3', - '.bg-pink-3', - '.color-pink-4', - '.bg-pink-4', - '.color-pink-5', - '.bg-pink-5', - '.color-pink-6', - '.bg-pink-6', - '.color-pink-7', - '.bg-pink-7', - '.color-pink-8', - '.bg-pink-8', - '.color-pink-9', - '.bg-pink-9', - '.text-blue', - '.text-red', - '.text-gray-light', - '.text-gray', - '.text-gray-dark', - '.text-green', - '.text-yellow', - '.text-orange', - '.text-orange-light', - '.text-purple', - '.text-pink', - '.text-white', - '.link-gray', - '.link-gray:hover', - '.link-gray-dark', - '.link-gray-dark:hover', - '.link-hover-blue:hover', - '.muted-link', - '.muted-link:hover', - '.text-shadow-dark', - '.text-shadow-light', - '.dropdown-menu-dark', - '.dropdown-menu-dark::before', - '.dropdown-menu-dark::after', - '.dropdown-menu-dark .dropdown-header', - '.dropdown-menu-dark .dropdown-divider', - '.dropdown-menu-dark .dropdown-item', - '.dropdown-menu-dark.dropdown-menu-w::before', - '.dropdown-menu-dark.dropdown-menu-w::after', - '.dropdown-menu-dark.dropdown-menu-e::before', - '.dropdown-menu-dark.dropdown-menu-e::after', - '.dropdown-menu-dark.dropdown-menu-ne::before', - '.dropdown-menu-dark.dropdown-menu-ne::after', - '.Label--outline', - '.Label--gray', - '.Label--gray-darker', - '.Label--yellow', - '.Label--orange', - '.Label--red', - '.Label--outline-green', - '.Label--green', - '.Label--blue', - '.Label--purple', - '.Label--pink', - '.State--green', - '.State--red', - '.State--purple', - '.Counter--gray-light', - '.Counter--gray', - '.btn-transparent:active' - ], - message: `This selector is not available in Primer CSS 16.0.0. Please refer to the documentation.` - }, - { - variables: [ - '$bg-black', - '$bg-black-fade', - '$bg-blue', - '$bg-blue-light', - '$bg-diffstat-added', - '$bg-diffstat-deleted', - '$bg-diffstat-neutral', - '$bg-gray', - '$bg-gray-dark', - '$bg-gray-light', - '$bg-green', - '$bg-green-light', - '$bg-orange', - '$bg-pink', - '$bg-purple', - '$bg-purple-light', - '$bg-red', - '$bg-red-light', - '$bg-white', - '$bg-yellow', - '$bg-yellow-dark', - '$bg-yellow-light', - '$black', - '$black-fade-15', - '$black-fade-30', - '$black-fade-50', - '$black-fade-70', - '$black-fade-85', - '$blue', - '$blue-000', - '$blue-100', - '$blue-200', - '$blue-300', - '$blue-400', - '$blue-500', - '$blue-600', - '$blue-700', - '$blue-800', - '$blue-900', - '$border-black-fade', - '$border-blue', - '$border-blue-light', - '$border-color', - '$border-color-button', - '$border-gray', - '$border-gray-dark', - '$border-gray-darker', - '$border-gray-light', - '$border-green', - '$border-green-light', - '$border-purple', - '$border-red', - '$border-red-light', - '$border-white', - '$border-white-fade', - '$border-yellow', - '$box-shadow', - '$box-shadow-extra-large', - '$box-shadow-focus', - '$box-shadow-highlight', - '$box-shadow-inset', - '$box-shadow-large', - '$box-shadow-medium', - '$btn-active-shadow', - '$btn-input-focus-shadow', - '$form-control-shadow', - '$gray', - '$gray-000', - '$gray-100', - '$gray-200', - '$gray-300', - '$gray-400', - '$gray-500', - '$gray-600', - '$gray-700', - '$gray-800', - '$gray-900', - '$gray-dark', - '$gray-light', - '$green', - '$green-000', - '$green-100', - '$green-200', - '$green-300', - '$green-400', - '$green-500', - '$green-600', - '$green-700', - '$green-800', - '$green-900', - '$orange', - '$orange-000', - '$orange-100', - '$orange-200', - '$orange-300', - '$orange-400', - '$orange-500', - '$orange-600', - '$orange-700', - '$orange-800', - '$orange-900', - '$pink-000', - '$pink-100', - '$pink-200', - '$pink-300', - '$pink-400', - '$pink-500', - '$pink-600', - '$pink-700', - '$pink-800', - '$pink-900', - '$purple', - '$purple-000', - '$purple-100', - '$purple-200', - '$purple-300', - '$purple-400', - '$purple-500', - '$purple-600', - '$purple-700', - '$purple-800', - '$purple-900', - '$red', - '$red-000', - '$red-100', - '$red-200', - '$red-300', - '$red-400', - '$red-500', - '$red-600', - '$red-700', - '$red-800', - '$red-900', - '$text-black', - '$text-blue', - '$text-gray', - '$text-gray-dark', - '$text-gray-light', - '$text-green', - '$text-orange', - '$text-orange-light', - '$text-pink', - '$text-purple', - '$text-red', - '$text-white', - '$text-yellow', - '$tooltip-background-color', - '$tooltip-text-color', - '$white', - '$white-fade-15', - '$white-fade-30', - '$white-fade-50', - '$white-fade-70', - '$white-fade-85', - '$yellow', - '$yellow-000', - '$yellow-100', - '$yellow-200', - '$yellow-300', - '$yellow-400', - '$yellow-500', - '$yellow-600', - '$yellow-700', - '$yellow-800', - '$yellow-900', - '$blue-mktg', - '$green-mktg' - ], - message: `This variable is not available in Primer CSS 16.0.0. Please refer to the documentation.` - } - ], - '15.0.0': [ - { - selectors: [ - '.btn-outline:active .Counter', - '.btn-outline.selected .Counter', - '.btn-outline[aria-selected=true] .Counter', - '.tabnav .Counter', - '.SideNav-item:hover::before', - '.SideNav-item:focus::before', - '.UnderlineNav-item:hover .UnderlineNav-octicon', - '.UnderlineNav-item:focus .UnderlineNav-octicon', - '.UnderlineNav--right .UnderlineNav-item', - '.pagination::before', - '.pagination::after', - '.pagination a:first-child', - '.pagination span:first-child', - '.pagination em:first-child', - '.pagination a:last-child', - '.pagination span:last-child', - '.pagination em:last-child', - '.pagination .selected', - '.IssueLabel--big .g-emoji', - '.IssueLabel--big:hover', - '.SelectMenu-item[aria-checked="true"]', - '.SelectMenu-item[aria-checked="true"] .SelectMenu-icon--check', - '.SelectMenu-tab:not([aria-checked="true"]):hover', - '.SelectMenu-tab:not([aria-checked="true"]):active', - '.SelectMenu-tab:not([aria-selected="true"]):hover' - ], - message: `This selector is not available in Primer CSS 15.0.0. Please refer to the documentation.` - } - ], - '14.4.0': [ - { - selectors: [ - '.breadcrumb-item[aria-current]', - '.breadcrumb-item[aria-current]::after', - '.menu-item[aria-current]', - '.menu-item[aria-current]::before', - '.tabnav-tab[aria-current]', - '.filter-item[aria-current]', - '.SideNav-item[aria-current="page"]', - '.SideNav-item[aria-current="page"]::before', - '.SideNav-subItem[aria-current="page"]', - '.subnav-item[aria-current]', - '.UnderlineNav-item[aria-current]', - '.UnderlineNav-item[aria-current] .UnderlineNav-octicon', - '.pagination [aria-current]', - '.pagination [aria-current]:hover' - ], - message: `These selectors are not needed anymore.` - } - ], - '14.0.0': [ - { - selectors: [ - '.SelectMenu-item+.SelectMenu-item', - '.SelectMenu-divider:first-child', - '.SelectMenu-divider:last-child', - '.SelectMenu--hasFilter .SelectMenu-item:last-child', - '.SelectMenu-item[aria-checked="true"] .SelectMenu-icon' - ], - message: `These selectors are deprecated and not used anymore.` - }, - { - selectors: [ - '.flex-item-equal', - '.flex-sm-item-equal', - '.flex-md-item-equal', - '.flex-lg-item-equal', - '.flex-xl-item-equal' - ], - message: `This variable is deprecated. Use "flex-1" instead.` - }, - { - selectors: ['.UnderlineNav-item.selected', '.UnderlineNav-item.selected .UnderlineNav-octicon'], - message: `Please use aria-selected="true" to indicate the selected state of an UnderlineNav item.` - }, - { - variables: ['$status-pending'], - message: `This variable is deprecated.` - }, - { - variables: ['$highlight-yellow'], - message: `This variable is deprecated.` - }, - { - variables: ['$repo-private-text', '$repo-private-bg', '$repo-private-icon'], - message: `These variables are deprecated.` - }, - { - variables: ['$marketingSpacers', '$allSpacers'], - message: `Please use the $marketing-spacers and $marketing-all-spacers variables.` - }, - { - variables: ['$exploregrid-item-border-radius'], - message: `This variable is deprecated. Use "4px" instead.` - }, - { - variables: ['$stats-switcher-py', '$stats-viewport-height'], - message: `These variables are deprecated.` - }, - { - variables: ['$min_tab_size', '$max_tab_size'], - message: `These variables are deprecated.` - } - ], - '13.0.0': [ - { - selectors: [ - '.btn-purple', - '.btn-purple:focus', - '.btn-purple.focus', - '.btn-purple:hover', - '.btn-purple.hover', - '.btn-purple:active', - '.btn-purple.selected', - '[open]>.btn-purple', - '.btn-purple:disabled', - '.btn-purple.disabled', - '.btn-purple .Counter' - ], - message: `Please don't make purple buttons.` - }, - { - selectors: ['.text-pending'], - message: `Please use the "text-yellow" class instead of "text-pending".` - }, - { - selectors: ['.bg-pending'], - message: `Please use the "bg-yellow-dark" class instead of "bg-pending".` - }, - { - selectors: [ - '.container', - '.container::before', - '.container::after', - '.columns', - '.columns::before', - '.columns::after', - '.column', - '.one-third', - '.two-thirds', - '.one-fourth', - '.one-half', - '.three-fourths', - '.one-fifth', - '.four-fifths' - ], - message: `Please use [grid classes](https://primer.style/css/objects/grid).` - }, - { - selectors: ['.centered'], - message: `You can use the "mx-auto" class to center any element.` - }, - { - selectors: [ - '.dropdown-menu-content', - '.dropdown.active .dropdown-menu-content', - '.dropdown-menu-content.anim-scale-in' - ], - message: `The "dropdown-menu-content" class is unnecessary.` - } - ] -} +const deprecations = JSON.parse(fs.readFileSync('./dist/deprecations.json')) -import semver from 'semver' -const pkg = JSON.parse(fs.readFileSync('./package.json')) -const {version: CURRENT_VERSION} = pkg - -// map selectors to the version and message of their deprecation -const selectorDeprecations = new Map() -const variableDeprecations = new Map() -for (const [version, deps] of Object.entries(versionDeprecations)) { - for (const {selectors = [], variables = [], message} of deps) { - for (const selector of selectors) { - selectorDeprecations.set(selector, {version, message}) - } - for (const variable of variables) { - variableDeprecations.set(variable, {version, message}) - } - } -} - -function isSelectorDeprecated(selector, version = CURRENT_VERSION) { - const deprecation = selectorDeprecations.get(selector) - return deprecation ? semver.gte(deprecation.version, version) : false -} - -function isVariableDeprecated(variable, version = CURRENT_VERSION) { - const deprecation = variableDeprecations.get(variable) - return deprecation ? semver.gte(deprecation.version, version) : false -} +const deprecatedSelectors = deprecations['selectors'] +const deprecatedSassVariables = deprecations['variables'] +const deprecatedSassMixins = deprecations['mixins'] export { - versionDeprecations, - selectorDeprecations, - variableDeprecations, - isSelectorDeprecated, - isVariableDeprecated + deprecatedSelectors, + deprecatedSassVariables, + deprecatedSassMixins } diff --git a/docs/content/tools/deprecations.md b/docs/content/tools/deprecations.md index 1939505b..5204370d 100644 --- a/docs/content/tools/deprecations.md +++ b/docs/content/tools/deprecations.md @@ -4,57 +4,62 @@ title: Deprecation data As of version 12.7.0, we publish CSS selector and SCSS variable deprecation data (as of 14.0.0) with `@primer/css`. You can access the data via the [Node API](#node) or as [JSON](#json). -**Keep in mind that this data includes both active and _planned_ deprecations.** The [Node API](#node) is the best way to determine whether a selector or variable is deprecated for the version of `@primer/css` you've installed. +To deprecate a class, variable, or mixin, add the element to the [deprecations.js](https://github.com/primer/css/blob/main/deprecations.js) file with it's replacement value. + +The replacement can be: + +* A `String` for a direct replacement. +* An `Array` for multiple replacement options. +* `null` to indicate there is no replacement. + +This could look something like this: + +```js +const deprecations = { + "deprecated-1": "replacement", + "deprecated-2": ["replacement-1", "replacement-2"], + "deprecated-3": null +} +``` ## JSON The JSON data is available in the unpacked node module's `dist/deprecations.json`, and is an object with the following structure: -* `versions` is an object whose keys are version numbers (e.g. `13.0.0`) and values are deprecation messages, each of which has a `message` string and a `selectors` and/or `variables` array: +```json +{ + "selectors" {...}, + "variables": {...}, + "mixins": {...} +} +``` - ```json - { - "versions": { - "14.0.0": [ - { - "variables": ["$min_tab_size", "$max_tab_size"], - "message": "These variables have been deprecated." - } - ], - "13.0.0": [ - { - "selectors": [".btn-purple"], - "message": "Please don't make purple buttons." - } - ] - } - } - ``` - - Deprecation messages strings may include Markdown so that they can be included in the [changelog]. - -* `selectors` is an object mapping CSS selectors (e.g. `.btn-purple`) to the version in which they are _or will be_ deprecated: +* `selectors` is an object mapping CSS selectors to their replacements. If the replacement is an Array, then there's multiple options. If the replacement is null then there are no replacements. ```json { "selectors": { - ".btn-purple": { - "version": "13.0.0", - "message": "Please don't make purple buttons." - } + "deprecated-class": "replacement-class" } } ``` -* `variables` is an object mapping SCSS variables (including the leading `$`, e.g. `$status-pending`) to the version in which they are or will be deprecated: +* `variables` is an object mapping SCSS variables to their replacement SCSS variable. ```json { "variables": { - "$status-pending": { - "version": "14.0.0", - "message": "This variable is unused in Primer, and is deprecated." - } + "$deprecated-variable": "$replacement-variable" + } + } + ``` + +* `mixins` is an object mapping SCSS mixins to their replacement SCSS mixins. + + ```json + { + "mixins": { + "deprecated-mixin": "replacement-mixin" } } ``` @@ -65,65 +70,13 @@ The JSON data is available in the unpacked node module's `dist/deprecations.json The Node API for selector deprecations is available at `@primer/css/deprecations`. -**Note:** Because we have chosen not to bundle any runtime dependencies with -`@primer/css`, you will need to install the [semver] dependency yourself: - -```shell -npm install semver -``` - -### `versionDeprecations` -This is the object literal form of the [JSON data's](#json) `versions` object. -For instance, to list all of the deprecations: +### Example: ```js -const {versionDeprecations} = require('@primer/css/deprecations') -for (const [version, deprecations] of Object.entries(versionDeprecations)) { - console.log(`${version}: ${deprecations.length} deprecations`) -} +const { + deprecatedSelectors, + deprecatedSassVariables, + deprecatedSassMixins +} = require('@primer/css/deprecations') + ``` - -### `selectorDeprecations` -This is a [Map] object with keys for each CSS selector mapped to the deprecation info: - -```js -const {selectorDeprecations} = require('@primer/css/deprecations') -console.log(`Purple buttons are going away? ${selectorDeprecations.has('.btn-purple')}`) -// "Purple buttons are going away? true" -``` - -### `isSelectorDeprecated(selector[, version])` -Returns `true` if the CSS `selector` will have been deprecated (removed) _by_ the specified [semver] version. - -```js -const {isSelectorDeprecated} = require('@primer/css/deprecations') -console.log(`Purple buttons are bad? ${isSelectorDeprecated('.btn-purple')}`) -// "Purple buttons are bad? true" -console.log(`Primary buttons are bad? ${isSelectorDeprecated('.btn-primary')}`) -// "Primary buttons are bad? false" -``` - -### `variableDeprecations` -This is a [Map] object with keys for each SCSS variable mapped to the deprecation info: - -```js -const {selectorDeprecations} = require('@primer/css/deprecations') -console.log(`Will $status-pending be deprecated? ${variableDeprecations.has('$status-pending')}`) -// "Will $status-pending be deprecated? true" -``` - -### `isVariableDeprecated(variable[, version])` -Returns `true` if the named SCSS variable (including the leading `$`) will have been deprecated (removed) _by_ the specified [semver] version. - -```js -const {isVariableDeprecated} = require('@primer/css/deprecations') -console.log(`$status-pending deprecated? ${isVariableDeprecated('$status-pending')}`) -// "$status-pending deprecated? true" -console.log(`$yellow-700 deprecated? ${isVariableDeprecated('$yellow-700')}`) -// "$yellow-700 deprecated false" -``` - - -[semver]: https://npm.im/semver -[changelog]: https://github.com/primer/css/tree/main/CHANGELOG.md -[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map diff --git a/package.json b/package.json index f53c8b98..019d7a12 100644 --- a/package.json +++ b/package.json @@ -24,7 +24,7 @@ ], "scripts": { "dist": "script/dist.js", - "stylelint": "stylelint --quiet src", + "stylelint": "stylelint --quiet src/**/*.scss", "eslint": "eslint deprecations.js __tests__ script", "prepublishOnly": "script/prepublish", "start": "yarn dev", diff --git a/script/analyze-variables.js b/script/analyze-variables.js index a2eb811e..f9247657 100755 --- a/script/analyze-variables.js +++ b/script/analyze-variables.js @@ -93,5 +93,5 @@ export default analyzeVariables const args = process.argv.slice(2) const file = args.length ? args.shift() : 'src/support/index.scss' const variables = await analyzeVariables(file) - console.log(JSON.stringify(variables, null, 2)) + JSON.stringify(variables, null, 2) })() diff --git a/script/dist.js b/script/dist.js index 440e3d25..f9947b1e 100755 --- a/script/dist.js +++ b/script/dist.js @@ -5,11 +5,10 @@ import postcss from 'postcss' import loadConfig from 'postcss-load-config' import {dirname, join} from 'path' -import {versionDeprecations, selectorDeprecations, variableDeprecations} from '../deprecations.js' import analyzeVariables from './analyze-variables.js' import fsExtra from 'fs-extra' -const {remove, mkdirp, readFile, writeFile} = fsExtra +const {copy, remove, mkdirp, readFile, writeFile} = fsExtra const inDir = 'src' const outDir = 'dist' @@ -69,7 +68,7 @@ async function dist() { const meta = {bundles} await writeFile(join(outDir, 'meta.json'), JSON.stringify(meta, null, 2), encoding) await writeVariableData() - await writeDeprecationData() + await copy(join(inDir, 'deprecations.json'), join(outDir, 'deprecations.json')) } catch (error) { console.error(error) process.exitCode = 1 @@ -91,22 +90,6 @@ function getPathName(path) { return path.replace(/\//g, '-') } -function writeDeprecationData() { - const data = { - versions: versionDeprecations, - selectors: mapToObject(selectorDeprecations), - variables: mapToObject(variableDeprecations) - } - return writeFile(join(outDir, 'deprecations.json'), JSON.stringify(data, null, 2)) - - function mapToObject(map) { - return Array.from(map.entries()).reduce((obj, [key, value]) => { - obj[key] = value - return obj - }, {}) - } -} - dist() async function writeVariableData() { diff --git a/src/deprecations.json b/src/deprecations.json new file mode 100644 index 00000000..ea950e2c --- /dev/null +++ b/src/deprecations.json @@ -0,0 +1,504 @@ +{ + "selectors": { + "centered": "mx-auto", + "dropdown-menu-content": null, + "break-word": "wb-break-word", + "h000-mktg": null, + "h00-mktg": null, + "lead-mktg": null, + "p-7": "pt-7 pr-7 pb-7 pl-7", + "p-8": "pt-8 pr-8 pb-8 pl-8", + "p-9": "pt-9 pr-9 pb-9 pl-9", + "p-10": "pt-10 pr-10 pb-10 pl-10", + "p-11": "pt-11 pr-11 pb-11 pl-11", + "p-12": "pt-12 pr-12 pb-12 pl-12", + "p-sm-7": "pt-sm-7 pr-sm-7 pb-sm-7 pl-sm-7", + "p-sm-8": "pt-sm-8 pr-sm-8 pb-sm-8 pl-sm-8", + "p-sm-9": "pt-sm-9 pr-sm-9 pb-sm-9 pl-sm-9", + "p-sm-10": "pt-sm-10 pr-sm-10 pb-sm-10 pl-sm-10", + "p-sm-11": "pt-sm-11 pr-sm-11 pb-sm-11 pl-sm-11", + "p-sm-12": "pt-sm-12 pr-sm-12 pb-sm-12 pl-sm-12", + "p-md-7": "pt-md-7 pr-md-7 pb-md-7 pl-md-7", + "p-md-8": "pt-md-8 pr-md-8 pb-md-8 pl-md-8", + "p-md-9": "pt-md-9 pr-md-9 pb-md-9 pl-md-9", + "p-md-10": "pt-md-10 pr-md-10 pb-md-10 pl-md-10", + "p-md-11": "pt-md-11 pr-md-11 pb-md-11 pl-md-11", + "p-md-12": "pt-md-12 pr-md-12 pb-md-12 pl-md-12", + "p-lg-7": "pt-lg-7 pr-lg-7 pb-lg-7 pl-lg-7", + "p-lg-8": "pt-lg-8 pr-lg-8 pb-lg-8 pl-lg-8", + "p-lg-9": "pt-lg-9 pr-lg-9 pb-lg-9 pl-lg-9", + "p-lg-10": "pt-lg-10 pr-lg-10 pb-lg-10 pl-lg-10", + "p-lg-11": "pt-lg-11 pr-lg-11 pb-lg-11 pl-lg-11", + "p-lg-12": "pt-lg-12 pr-lg-12 pb-lg-12 pl-lg-12", + "p-xl-7": "pt-xl-7 pr-xl-7 pb-xl-7 pl-xl-7", + "p-xl-8": "pt-xl-8 pr-xl-8 pb-xl-8 pl-xl-8", + "p-xl-9": "pt-xl-9 pr-xl-9 pb-xl-9 pl-xl-9", + "p-xl-10": "pt-xl-10 pr-xl-10 pb-xl-10 pl-xl-10", + "p-xl-11": "pt-xl-11 pr-xl-11 pb-xl-11 pl-xl-11", + "p-xl-12": "pt-xl-12 pr-xl-12 pb-xl-12 pl-xl-12", + "top-n0": "top-0", + "right-n0": "right-0", + "bottom-n0": "bottom-0", + "left-n0": "left-0", + "top-md-n0": "top-md-0", + "right-md-n0": "right-md-0", + "bottom-md-n0": "bottom-md-0", + "left-md-n0": "left-md-0", + "top-lg-n0": "top-lg-0", + "right-lg-n0": "right-lg-0", + "bottom-lg-n0": "bottom-lg-0", + "left-lg-n0": "left-lg-0", + "mt-n0": "mt-0", + "mb-n0": "mb-0", + "mt-sm-n0": "mt-sm-0", + "mb-sm-n0": "mb-sm-0", + "mt-md-n0": "mt-md-0", + "mb-md-n0": "mb-md-0", + "mt-lg-n0": "mt-lg-0", + "mb-lg-n0": "mb-lg-0", + "mt-xl-n0": "mt-xl-0", + "mb-xl-n0": "mb-xl-0", + "bg-shade-gradient": "color-bg-secondary", + "color-border-overlay": "color-border-primary", + "btn-blue": null, + "input-dark": null, + "border-blue": null, + "border-blue-light": null, + "border-green": null, + "border-green-light": null, + "border-red": null, + "border-red-light": null, + "border-purple": null, + "border-yellow": null, + "border-gray-light": null, + "border-gray-dark": null, + "border-black-fade": null, + "border-white-fade": null, + "border-white-fade-15": null, + "border-white-fade-30": null, + "border-white-fade-50": null, + "border-white-fade-70": null, + "border-white-fade-85": null, + "box-shadow": null, + "box-shadow-medium": null, + "box-shadow-large": null, + "box-shadow-extra-large": null, + "bg-white": null, + "bg-blue": null, + "bg-blue-light": null, + "bg-gray-dark": null, + "bg-gray": null, + "bg-gray-light": null, + "bg-green": null, + "bg-green-light": null, + "bg-red": null, + "bg-red-light": null, + "bg-yellow": null, + "bg-yellow-light": null, + "bg-yellow-dark": null, + "bg-purple": null, + "bg-pink": null, + "bg-purple-light": null, + "bg-orange": null, + "color-gray-0": null, + "bg-gray-0": null, + "color-gray-1": null, + "bg-gray-1": null, + "color-gray-2": null, + "bg-gray-2": null, + "color-gray-3": null, + "bg-gray-3": null, + "color-gray-4": null, + "bg-gray-4": null, + "color-gray-5": null, + "bg-gray-5": null, + "color-gray-6": null, + "bg-gray-6": null, + "color-gray-7": null, + "bg-gray-7": null, + "color-gray-8": null, + "bg-gray-8": null, + "color-gray-9": null, + "bg-gray-9": null, + "color-blue-0": null, + "bg-blue-0": null, + "color-blue-1": null, + "bg-blue-1": null, + "color-blue-2": null, + "bg-blue-2": null, + "color-blue-3": null, + "bg-blue-3": null, + "color-blue-4": null, + "bg-blue-4": null, + "color-blue-5": null, + "bg-blue-5": null, + "color-blue-6": null, + "bg-blue-6": null, + "color-blue-7": null, + "bg-blue-7": null, + "color-blue-8": null, + "bg-blue-8": null, + "color-blue-9": null, + "bg-blue-9": null, + "color-green-0": null, + "bg-green-0": null, + "color-green-1": null, + "bg-green-1": null, + "color-green-2": null, + "bg-green-2": null, + "color-green-3": null, + "bg-green-3": null, + "color-green-4": null, + "bg-green-4": null, + "color-green-5": null, + "bg-green-5": null, + "color-green-6": null, + "bg-green-6": null, + "color-green-7": null, + "bg-green-7": null, + "color-green-8": null, + "bg-green-8": null, + "color-green-9": null, + "bg-green-9": null, + "color-yellow-0": null, + "bg-yellow-0": null, + "color-yellow-1": null, + "bg-yellow-1": null, + "color-yellow-2": null, + "bg-yellow-2": null, + "color-yellow-3": null, + "bg-yellow-3": null, + "color-yellow-4": null, + "bg-yellow-4": null, + "color-yellow-5": null, + "bg-yellow-5": null, + "color-yellow-6": null, + "bg-yellow-6": null, + "color-yellow-7": null, + "bg-yellow-7": null, + "color-yellow-8": null, + "bg-yellow-8": null, + "color-yellow-9": null, + "bg-yellow-9": null, + "color-orange-0": null, + "bg-orange-0": null, + "color-orange-1": null, + "bg-orange-1": null, + "color-orange-2": null, + "bg-orange-2": null, + "color-orange-3": null, + "bg-orange-3": null, + "color-orange-4": null, + "bg-orange-4": null, + "color-orange-5": null, + "bg-orange-5": null, + "color-orange-6": null, + "bg-orange-6": null, + "color-orange-7": null, + "bg-orange-7": null, + "color-orange-8": null, + "bg-orange-8": null, + "color-orange-9": null, + "bg-orange-9": null, + "color-red-0": null, + "bg-red-0": null, + "color-red-1": null, + "bg-red-1": null, + "color-red-2": null, + "bg-red-2": null, + "color-red-3": null, + "bg-red-3": null, + "color-red-4": null, + "bg-red-4": null, + "color-red-5": null, + "bg-red-5": null, + "color-red-6": null, + "bg-red-6": null, + "color-red-7": null, + "bg-red-7": null, + "color-red-8": null, + "bg-red-8": null, + "color-red-9": null, + "bg-red-9": null, + "color-purple-0": null, + "bg-purple-0": null, + "color-purple-1": null, + "bg-purple-1": null, + "color-purple-2": null, + "bg-purple-2": null, + "color-purple-3": null, + "bg-purple-3": null, + "color-purple-4": null, + "bg-purple-4": null, + "color-purple-5": null, + "bg-purple-5": null, + "color-purple-6": null, + "bg-purple-6": null, + "color-purple-7": null, + "bg-purple-7": null, + "color-purple-8": null, + "bg-purple-8": null, + "color-purple-9": null, + "bg-purple-9": null, + "color-pink-0": null, + "bg-pink-0": null, + "color-pink-1": null, + "bg-pink-1": null, + "color-pink-2": null, + "bg-pink-2": null, + "color-pink-3": null, + "bg-pink-3": null, + "color-pink-4": null, + "bg-pink-4": null, + "color-pink-5": null, + "bg-pink-5": null, + "color-pink-6": null, + "bg-pink-6": null, + "color-pink-7": null, + "bg-pink-7": null, + "color-pink-8": null, + "bg-pink-8": null, + "color-pink-9": null, + "bg-pink-9": null, + "text-blue": null, + "text-red": null, + "text-gray-light": null, + "text-gray": null, + "text-gray-dark": null, + "text-green": null, + "text-yellow": null, + "text-orange": null, + "text-orange-light": null, + "text-purple": null, + "text-pink": null, + "text-white": null, + "link-gray": null, + "link-gray-dark": null, + "muted-link": null, + "text-shadow-dark": null, + "text-shadow-light": null, + "dropdown-menu-dark": null, + "Label--outline": null, + "Label--gray": null, + "Label--gray-darker": null, + "Label--yellow": null, + "Label--orange": null, + "Label--red": null, + "Label--outline-green": null, + "Label--green": null, + "Label--blue": null, + "Label--purple": null, + "Label--pink": null, + "State--green": null, + "State--red": null, + "State--purple": null, + "Counter--gray-light": null, + "Counter--gray": null, + "flex-item-equal": "flex-1", + "flex-sm-item-equal": "flex-sm-1", + "flex-md-item-equal": "flex-md-1", + "flex-lg-item-equal": "flex-lg-1", + "flex-xl-item-equal": "flex-xl-1", + "btn-purple": null, + "text-pending": "text-yellow", + "bg-pending": "bg-yellow-dark", + "container": null, + "columns": null, + "column": null, + "one-third": null, + "two-thirds": null, + "one-fourth": null, + "one-half": null, + "three-fourths": null, + "one-fifth": null, + "four-fifths": null + }, + + "variables": { + "$h000-size": null, + "$h000-size-mobile": null, + "$bg-black": null, + "$bg-black-fade": null, + "$bg-blue": null, + "$bg-blue-light": null, + "$bg-diffstat-added": null, + "$bg-diffstat-deleted": null, + "$bg-diffstat-neutral": null, + "$bg-gray": null, + "$bg-gray-dark": null, + "$bg-gray-light": null, + "$bg-green": null, + "$bg-green-light": null, + "$bg-orange": null, + "$bg-pink": null, + "$bg-purple": null, + "$bg-purple-light": null, + "$bg-red": null, + "$bg-red-light": null, + "$bg-white": null, + "$bg-yellow": null, + "$bg-yellow-dark": null, + "$bg-yellow-light": null, + "$black": null, + "$black-fade-15": null, + "$black-fade-30": null, + "$black-fade-50": null, + "$black-fade-70": null, + "$black-fade-85": null, + "$blue": null, + "$blue-000": null, + "$blue-100": null, + "$blue-200": null, + "$blue-300": null, + "$blue-400": null, + "$blue-500": null, + "$blue-600": null, + "$blue-700": null, + "$blue-800": null, + "$blue-900": null, + "$border-black-fade": null, + "$border-blue": null, + "$border-blue-light": null, + "$border-color": null, + "$border-color-button": null, + "$border-gray": null, + "$border-gray-dark": null, + "$border-gray-darker": null, + "$border-gray-light": null, + "$border-green": null, + "$border-green-light": null, + "$border-purple": null, + "$border-red": null, + "$border-red-light": null, + "$border-white": null, + "$border-white-fade": null, + "$border-yellow": null, + "$box-shadow": null, + "$box-shadow-extra-large": null, + "$box-shadow-focus": null, + "$box-shadow-highlight": null, + "$box-shadow-inset": null, + "$box-shadow-large": null, + "$box-shadow-medium": null, + "$btn-active-shadow": null, + "$btn-input-focus-shadow": null, + "$form-control-shadow": null, + "$gray": null, + "$gray-000": null, + "$gray-100": null, + "$gray-200": null, + "$gray-300": null, + "$gray-400": null, + "$gray-500": null, + "$gray-600": null, + "$gray-700": null, + "$gray-800": null, + "$gray-900": null, + "$gray-dark": null, + "$gray-light": null, + "$green": null, + "$green-000": null, + "$green-100": null, + "$green-200": null, + "$green-300": null, + "$green-400": null, + "$green-500": null, + "$green-600": null, + "$green-700": null, + "$green-800": null, + "$green-900": null, + "$orange": null, + "$orange-000": null, + "$orange-100": null, + "$orange-200": null, + "$orange-300": null, + "$orange-400": null, + "$orange-500": null, + "$orange-600": null, + "$orange-700": null, + "$orange-800": null, + "$orange-900": null, + "$pink-000": null, + "$pink-100": null, + "$pink-200": null, + "$pink-300": null, + "$pink-400": null, + "$pink-500": null, + "$pink-600": null, + "$pink-700": null, + "$pink-800": null, + "$pink-900": null, + "$purple": null, + "$purple-000": null, + "$purple-100": null, + "$purple-200": null, + "$purple-300": null, + "$purple-400": null, + "$purple-500": null, + "$purple-600": null, + "$purple-700": null, + "$purple-800": null, + "$purple-900": null, + "$red": null, + "$red-000": null, + "$red-100": null, + "$red-200": null, + "$red-300": null, + "$red-400": null, + "$red-500": null, + "$red-600": null, + "$red-700": null, + "$red-800": null, + "$red-900": null, + "$text-black": null, + "$text-blue": null, + "$text-gray": null, + "$text-gray-dark": null, + "$text-gray-light": null, + "$text-green": null, + "$text-orange": null, + "$text-orange-light": null, + "$text-pink": null, + "$text-purple": null, + "$text-red": null, + "$text-white": null, + "$text-yellow": null, + "$tooltip-background-color": null, + "$tooltip-text-color": null, + "$white": null, + "$white-fade-15": null, + "$white-fade-30": null, + "$white-fade-50": null, + "$white-fade-70": null, + "$white-fade-85": null, + "$yellow": null, + "$yellow-000": null, + "$yellow-100": null, + "$yellow-200": null, + "$yellow-300": null, + "$yellow-400": null, + "$yellow-500": null, + "$yellow-600": null, + "$yellow-700": null, + "$yellow-800": null, + "$yellow-900": null, + "$blue-mktg": null, + "$green-mktg": null, + "$status-pending": null, + "$highlight-yellow": null, + "$repo-private-text": null, + "$repo-private-bg": null, + "$repo-private-icon": null, + "$marketingSpacers": "$marketing-spacers", + "$allSpacers": "$marketing-all-spacers", + "$exploregrid-item-border-radius": "4px", + "$stats-switcher-py": null, + "$stats-viewport-height": null, + "$min_tab_size": null, + "$max_tab_size": null + }, + + "mixins": { + "rem": null + } +}