@atlaskit/heading 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @atlaskit/heading
 
+## 1.6.0
+
+### Minor Changes
+
+- [#68604](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/68604) [`fdf7f6635426`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/fdf7f6635426) - Modified mapping of `variant` to the HTML element that gets rendered. Previously `xlarge` would render a `h2`, `large` would render a `h3` etc... Now `xlarge` renders a `h1` and so on...
+
+## 1.5.1
+
+### Patch Changes
+
+- [#70023](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/70023) [`e2d35320717b`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/e2d35320717b) - Fix types to set either level or variant to be required props to prevent exceptions being thrown.
+
 ## 1.5.0
 
 ### Minor Changes

package/codemods/1.6.0-level-to-variant.tsx

@@ -0,0 +1,82 @@
+import core, {
+  API,
+  ASTPath,
+  FileInfo,
+  ImportDeclaration,
+  Options,
+} from 'jscodeshift';
+
+export default function transformer(
+  fileInfo: FileInfo,
+  { jscodeshift: j }: API,
+  options: Options,
+) {
+  const base = j(fileInfo.source);
+  const headingSpecifier = getDefaultSpecifier(j, base, '@atlaskit/heading');
+  if (!headingSpecifier) {
+    return;
+  }
+
+  replaceLevelWithVariant(j, base, headingSpecifier);
+
+  return base.toSource();
+}
+
+const levelToVariantMap = {
+  h900: 'xxlarge',
+  h800: 'xlarge',
+  h700: 'large',
+  h600: 'medium',
+  h500: 'small',
+  h400: 'xsmall',
+  h300: 'xxsmall',
+  // We may want to auto-transform h100s and h200s in the future
+  // h200: 'xxsmall',
+  // h100: 'xxsmall',
+};
+
+function replaceLevelWithVariant(
+  j: core.JSCodeshift,
+  source: ReturnType<typeof j>,
+  specifier: string,
+) {
+  source.findJSXElements(specifier).forEach(element => {
+    j(element)
+      .find(j.JSXAttribute, { name: { type: 'JSXIdentifier', name: 'level' } })
+      .forEach(attr => {
+        const attrValue = j(attr).nodes()[0].value;
+        if (attrValue.type === 'StringLiteral') {
+          const replacementValue =
+            levelToVariantMap[
+              attrValue.value as keyof typeof levelToVariantMap
+            ];
+          if (replacementValue) {
+            j(attr).replaceWith(
+              j.jsxAttribute(
+                j.jsxIdentifier('variant'),
+                j.stringLiteral(replacementValue),
+              ),
+            );
+          }
+        }
+      });
+  });
+}
+
+function getDefaultSpecifier(
+  j: core.JSCodeshift,
+  source: any,
+  specifier: string,
+) {
+  const specifiers = source
+    .find(j.ImportDeclaration)
+    .filter(
+      (path: ASTPath<ImportDeclaration>) =>
+        path.node.source.value === specifier,
+    )
+    .find(j.ImportDefaultSpecifier);
+  if (!specifiers.length) {
+    return null;
+  }
+  return specifiers.nodes()[0]!.local!.name;
+}

package/codemods/__tests__/_framework.tsx

@@ -0,0 +1,46 @@
+import { API, FileInfo, Options } from 'jscodeshift';
+
+import noop from '@atlaskit/ds-lib/noop';
+
+const applyTransform = require('jscodeshift/dist/testUtils').applyTransform;
+
+type Transformer = (file: FileInfo, jscodeshift: API, options: Options) => void;
+
+type TestArgs = {
+  it: string;
+  original: string;
+  expected: string;
+  transformer: Transformer;
+  mode?: 'only' | 'skip' | 'standard';
+  before?: () => void;
+  after?: () => void;
+};
+
+export function check({
+  it: name,
+  original,
+  expected,
+  transformer,
+  before = noop,
+  after = noop,
+  mode = 'standard',
+}: TestArgs) {
+  const run = mode === 'only' ? it.only : mode === 'skip' ? it.skip : it;
+  run(name, () => {
+    before();
+    try {
+      const output: string = applyTransform(
+        { default: transformer, parser: 'tsx' },
+        {},
+        { source: original },
+      );
+      expect(output).toBe(expected.trim());
+    } catch (e) {
+      // a failed assertion will throw
+      after();
+      throw e;
+    }
+    // will only be hit if we don't throw
+    after();
+  });
+}

package/codemods/__tests__/next-level-to-variant.tsx

@@ -0,0 +1,80 @@
+jest.autoMockOff();
+
+import transformer from '../1.6.0-level-to-variant';
+
+import { check } from './_framework';
+
+check({
+  transformer,
+  it: 'should replace level with variant only on Heading component',
+  original: `
+    import Heading from '@atlaskit/heading';
+
+    function App() {
+      return <>
+        <Heading level="h700" as="h3">hello</Heading>
+        <SomethingElse level="h700">still here</SomethingElse>
+      </>;
+    }
+  `,
+  expected: `
+    import Heading from '@atlaskit/heading';
+
+    function App() {
+      return <>
+        <Heading variant="large" as="h3">hello</Heading>
+        <SomethingElse level="h700">still here</SomethingElse>
+      </>;
+    }
+  `,
+});
+
+check({
+  transformer,
+  it: 'should do nothing if level is h200 or h100',
+  original: `
+    import Heading from '@atlaskit/heading';
+
+    function App() {
+      return <>
+        <Heading level="h300">hello</Heading>
+        <Heading level="h200">hello</Heading>
+        <Heading level="h100">hello</Heading>
+      </>;
+    }
+  `,
+  expected: `
+    import Heading from '@atlaskit/heading';
+
+    function App() {
+      return <>
+        <Heading variant="xxsmall">hello</Heading>
+        <Heading level="h200">hello</Heading>
+        <Heading level="h100">hello</Heading>
+      </>;
+    }
+  `,
+});
+
+check({
+  transformer,
+  it: 'should do nothing if variant already exists',
+  original: `
+    import Heading from '@atlaskit/heading';
+
+    function App() {
+      return <>
+        <Heading variant="large">hello</Heading>
+      </>;
+    }
+  `,
+  expected: `
+    import Heading from '@atlaskit/heading';
+
+    function App() {
+      return <>
+        <Heading variant="large">hello</Heading>
+      </>;
+    }
+  `,
+});

package/dist/cjs/heading.partial.js

@@ -11,14 +11,14 @@ var _headingContext = require("./heading-context");
 /** @jsx jsx */
 
 // https://atlassian.design/foundations/typography
-var levelMap = {
+var variantTagMap = {
   xxlarge: 'h1',
-  xlarge: 'h2',
-  large: 'h3',
-  medium: 'h4',
-  small: 'h5',
-  xsmall: 'h6',
-  xxsmall: 'div'
+  xlarge: 'h1',
+  large: 'h2',
+  medium: 'h3',
+  small: 'h4',
+  xsmall: 'h5',
+  xxsmall: 'h6'
 };
 var headingResetStyles = (0, _react.css)({
   color: "var(--ds-text, #172B4D)",
@@ -33,16 +33,12 @@ var inverseStyles = (0, _react.css)({
 /**
  * __Heading__
  *
- * A heading is a typography component used to display text in different sizes and formats.
+ * Heading is a typography component used to display text in defined sizes and styles.
  *
  * @example
  *
  * ```jsx
- * import Heading from '@atlaskit/heading';
- *
- * const HeadingXXL = () => (
- *   <Heading level="xxlarge">XXL</Heading>
- * );
+ * <Heading variant="xxlarge">Page title</Heading>
  * ```
  */
 var Heading = function Heading(_ref) {
@@ -56,13 +52,16 @@ var Heading = function Heading(_ref) {
   if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production' && as && typeof as !== 'string') {
     throw new Error('`as` prop should be a string.');
   }
-  var _useHeading = (0, _headingContext.useHeading)(levelMap[variant]),
+
+  // Technically variant can be undefined here due to how the types work.
+  // Once removing the level prop this assertion can be removed since variant will be a required prop.
+  var _useHeading = (0, _headingContext.useHeading)(variantTagMap[variant]),
     _useHeading2 = (0, _slicedToArray2.default)(_useHeading, 2),
     hLevel = _useHeading2[0],
     inferredElement = _useHeading2[1];
-  var Markup = as || inferredElement;
-  var needsAriaRole = Markup === 'div' && hLevel;
-  return (0, _react.jsx)(Markup, {
+  var Component = as || inferredElement;
+  var needsAriaRole = Component === 'div' && hLevel;
+  return (0, _react.jsx)(Component, {
     id: id,
     "data-testid": testId,
     role: needsAriaRole ? 'heading' : undefined,

package/dist/es2019/heading.partial.js

@@ -2,14 +2,14 @@
 import { css, jsx } from '@emotion/react';
 import { useHeading } from './heading-context';
 // https://atlassian.design/foundations/typography
-const levelMap = {
+const variantTagMap = {
   xxlarge: 'h1',
-  xlarge: 'h2',
-  large: 'h3',
-  medium: 'h4',
-  small: 'h5',
-  xsmall: 'h6',
-  xxsmall: 'div'
+  xlarge: 'h1',
+  large: 'h2',
+  medium: 'h3',
+  small: 'h4',
+  xsmall: 'h5',
+  xxsmall: 'h6'
 };
 const headingResetStyles = css({
   color: "var(--ds-text, #172B4D)",
@@ -24,16 +24,12 @@ const inverseStyles = css({
 /**
  * __Heading__
  *
- * A heading is a typography component used to display text in different sizes and formats.
+ * Heading is a typography component used to display text in defined sizes and styles.
  *
  * @example
  *
  * ```jsx
- * import Heading from '@atlaskit/heading';
- *
- * const HeadingXXL = () => (
- *   <Heading level="xxlarge">XXL</Heading>
- * );
+ * <Heading variant="xxlarge">Page title</Heading>
  * ```
  */
 const Heading = ({
@@ -47,10 +43,13 @@ const Heading = ({
   if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production' && as && typeof as !== 'string') {
     throw new Error('`as` prop should be a string.');
   }
-  const [hLevel, inferredElement] = useHeading(levelMap[variant]);
-  const Markup = as || inferredElement;
-  const needsAriaRole = Markup === 'div' && hLevel;
-  return jsx(Markup, {
+
+  // Technically variant can be undefined here due to how the types work.
+  // Once removing the level prop this assertion can be removed since variant will be a required prop.
+  const [hLevel, inferredElement] = useHeading(variantTagMap[variant]);
+  const Component = as || inferredElement;
+  const needsAriaRole = Component === 'div' && hLevel;
+  return jsx(Component, {
     id: id,
     "data-testid": testId,
     role: needsAriaRole ? 'heading' : undefined,

package/dist/esm/heading.partial.js

@@ -3,14 +3,14 @@ import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
 import { css, jsx } from '@emotion/react';
 import { useHeading } from './heading-context';
 // https://atlassian.design/foundations/typography
-var levelMap = {
+var variantTagMap = {
   xxlarge: 'h1',
-  xlarge: 'h2',
-  large: 'h3',
-  medium: 'h4',
-  small: 'h5',
-  xsmall: 'h6',
-  xxsmall: 'div'
+  xlarge: 'h1',
+  large: 'h2',
+  medium: 'h3',
+  small: 'h4',
+  xsmall: 'h5',
+  xxsmall: 'h6'
 };
 var headingResetStyles = css({
   color: "var(--ds-text, #172B4D)",
@@ -25,16 +25,12 @@ var inverseStyles = css({
 /**
  * __Heading__
  *
- * A heading is a typography component used to display text in different sizes and formats.
+ * Heading is a typography component used to display text in defined sizes and styles.
  *
  * @example
  *
  * ```jsx
- * import Heading from '@atlaskit/heading';
- *
- * const HeadingXXL = () => (
- *   <Heading level="xxlarge">XXL</Heading>
- * );
+ * <Heading variant="xxlarge">Page title</Heading>
  * ```
  */
 var Heading = function Heading(_ref) {
@@ -48,13 +44,16 @@ var Heading = function Heading(_ref) {
   if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production' && as && typeof as !== 'string') {
     throw new Error('`as` prop should be a string.');
   }
-  var _useHeading = useHeading(levelMap[variant]),
+
+  // Technically variant can be undefined here due to how the types work.
+  // Once removing the level prop this assertion can be removed since variant will be a required prop.
+  var _useHeading = useHeading(variantTagMap[variant]),
     _useHeading2 = _slicedToArray(_useHeading, 2),
     hLevel = _useHeading2[0],
     inferredElement = _useHeading2[1];
-  var Markup = as || inferredElement;
-  var needsAriaRole = Markup === 'div' && hLevel;
-  return jsx(Markup, {
+  var Component = as || inferredElement;
+  var needsAriaRole = Component === 'div' && hLevel;
+  return jsx(Component, {
     id: id,
     "data-testid": testId,
     role: needsAriaRole ? 'heading' : undefined,

package/dist/types/heading.partial.d.ts

@@ -4,16 +4,12 @@ import type { HeadingProps } from './types';
 /**
  * __Heading__
  *
- * A heading is a typography component used to display text in different sizes and formats.
+ * Heading is a typography component used to display text in defined sizes and styles.
  *
  * @example
  *
  * ```jsx
- * import Heading from '@atlaskit/heading';
- *
- * const HeadingXXL = () => (
- *   <Heading level="xxlarge">XXL</Heading>
- * );
+ * <Heading variant="xxlarge">Page title</Heading>
  * ```
  */
 declare const Heading: ({ children, variant, id, testId, as, color, }: HeadingProps) => jsx.JSX.Element;

package/dist/types/types.d.ts

@@ -47,7 +47,7 @@ export type HeadingProps = {
      * It's important to note that the final DOM may be impacted by the parent heading level context because of inferred accessibility level correction.
      * Therefore, it is recommended to check the final DOM to confirm the actual rendered HTML element.
      */
-    level?: 'h900' | 'h800' | 'h700' | 'h600' | 'h500' | 'h400' | 'h300' | 'h200' | 'h100';
+    level: 'h900' | 'h800' | 'h700' | 'h600' | 'h500' | 'h400' | 'h300' | 'h200' | 'h100';
     /**
      * Heading style variant. This style is detached from the specific heading level applied to allow for more flexibility.
      * Use instead of the deprecated `level` prop.
@@ -61,5 +61,5 @@ export type HeadingProps = {
      *
      * This prop will only work if the typography theme is applied.
      */
-    variant?: HeadingVariant;
+    variant: HeadingVariant;
 });

package/dist/types-ts4.5/heading.partial.d.ts

@@ -4,16 +4,12 @@ import type { HeadingProps } from './types';
 /**
  * __Heading__
  *
- * A heading is a typography component used to display text in different sizes and formats.
+ * Heading is a typography component used to display text in defined sizes and styles.
  *
  * @example
  *
  * ```jsx
- * import Heading from '@atlaskit/heading';
- *
- * const HeadingXXL = () => (
- *   <Heading level="xxlarge">XXL</Heading>
- * );
+ * <Heading variant="xxlarge">Page title</Heading>
  * ```
  */
 declare const Heading: ({ children, variant, id, testId, as, color, }: HeadingProps) => jsx.JSX.Element;

package/dist/types-ts4.5/types.d.ts

@@ -47,7 +47,7 @@ export type HeadingProps = {
      * It's important to note that the final DOM may be impacted by the parent heading level context because of inferred accessibility level correction.
      * Therefore, it is recommended to check the final DOM to confirm the actual rendered HTML element.
      */
-    level?: 'h900' | 'h800' | 'h700' | 'h600' | 'h500' | 'h400' | 'h300' | 'h200' | 'h100';
+    level: 'h900' | 'h800' | 'h700' | 'h600' | 'h500' | 'h400' | 'h300' | 'h200' | 'h100';
     /**
      * Heading style variant. This style is detached from the specific heading level applied to allow for more flexibility.
      * Use instead of the deprecated `level` prop.
@@ -61,5 +61,5 @@ export type HeadingProps = {
      *
      * This prop will only work if the typography theme is applied.
      */
-    variant?: HeadingVariant;
+    variant: HeadingVariant;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlaskit/heading",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "A heading is a typography component used to display text in different sizes and formats.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
@@ -32,7 +32,7 @@
     "codegen": "ts-node ./scripts/codegen.tsx"
   },
   "dependencies": {
-    "@atlaskit/tokens": "^1.34.0",
+    "@atlaskit/tokens": "^1.35.0",
     "@babel/runtime": "^7.0.0",
     "@emotion/react": "^11.7.1"
   },
@@ -47,6 +47,7 @@
     "@atlassian/atlassian-frontend-prettier-config-1.0.0": "npm:@atlassian/atlassian-frontend-prettier-config@1.0.0",
     "@atlassian/codegen": "^0.1.0",
     "@testing-library/react": "^12.1.5",
+    "jscodeshift": "^0.13.0",
     "prettier": "^2.8.0",
     "react-dom": "^16.8.0",
     "ts-node": "^10.9.1",