LG-4899: getLgIds

.changeset/shy-gorillas-lie.md

@@ -0,0 +1,27 @@
+---
+'@leafygreen-ui/confirmation-modal': major
+'@leafygreen-ui/gallery-indicator': major
+'@leafygreen-ui/password-input': major
+'@leafygreen-ui/split-button': major
+'@leafygreen-ui/form-footer': major
+'@leafygreen-ui/form-field': major
+'@leafygreen-ui/text-input': major
+'@leafygreen-ui/typography': major
+'@leafygreen-ui/text-area': major
+'@leafygreen-ui/checkbox': major
+'@leafygreen-ui/select': major
+'@leafygreen-ui/toggle': major
+'@leafygreen-ui/table': major
+'@leafygreen-ui/code': major
+'@leafygreen-ui/menu': major
+'@leafygreen-ui/tabs': major
+---
+
+Updates `data-lgid` to use scope based test IDs. These test IDs are generated using the helper utility `getLgIds`. For more information [check out the section in the styleguide about getLgIds](https://github.com/mongodb/leafygreen-ui/blob/main/STYLEGUIDE.md#getlgids).
+
+Removes public exports for:
+- `LGIDs`
+- `LGIDS_CHECKBOX`
+- `LGIDS_FORM_FIELD`
+- `LGIDS_SELECT`
+- `LGIDS_TYPOGRAPHY`

.changeset/tough-dryers-wonder.md

@@ -0,0 +1,5 @@
+---
+'@leafygreen-ui/date-picker': patch
+---
+
+Updates spec file to use updated test ids for `@leafygreen-ui/form-field` components

STYLEGUIDE.md

@@ -18,6 +18,8 @@
   - [Passing darkMode to children](#passing-darkMode-to-children)
   - [File Structure](https://github.com/mongodb/leafygreen-ui/blob/main/stories/Folder-Structure.stories.mdx)
   - [API Patterns](#api-patterns)
+    - [Input errors](#input-errors)
+  - [getLgIds](#getlgids)
 - [References](#references)
 
 # Contribution Guide
@@ -637,6 +639,81 @@ return (
 - Use `errorMessage` prop to set the error message that is displayed next to the input.
 - If `state='error'` but `errorMessage` is not defined, require `aria-describedby`
 
+## getLgIds
+
+The `getLgIds` utility function generates test IDs for components in the LeafyGreen UI library.
+
+The function accepts an optional root identifier, allowing consumers to set a unique base ID for each instance of a component. This base is then used to generate, scoped test IDs, ensuring predictable targeting in tests.
+
+#### Usage
+
+Each component includes a `getLgIds.ts` file that exports the `getLgIds` utility. This function returns an object containing IDs for each trackable element within the component.
+
+For more information on naming test IDs, [check out the section on BEM-ish patterns](#follow-bem-ish-patterns-when-hard-coding-a-data-testid-or-data-lgid).
+
+```js
+// getLgIds.ts
+
+export const DEFAULT_LGID_ROOT = 'lg-component';
+
+export const getLgIds = (root: `lg-${string}` = DEFAULT_LGID_ROOT) => {
+  const ids = {
+    root,
+    button: `${root}-button`,
+    input: `${root}-input`,
+  } as const;
+  return ids;
+};
+
+export type GetLgIdsReturnType = ReturnType<typeof getLgIds>;
+```
+
+Inside the component you can use the test IDs by calling `getLgIds()`:
+
+```js
+// Component.tsx
+
+const lgIds = getLgIds();
+
+// lgIds.root = 'lg-component'
+// lgIds.button = 'lg-component-button'
+// lgIds.input -> 'lg-component-input'
+```
+
+#### Component.tsx
+
+```js
+export const Component = forwardRef<
+  HTMLDivElement,
+  ComponentProps,
+>(
+  (
+    {
+      'data-lgid': dataLgId = getLgIds().root,
+      ...rest
+    },
+    fwdRef: React.Ref<any>,
+  ) => {
+    const lgIds = getLgIds(dataLgId);
+
+    return (
+      <div
+        data-testid={lgIds.root}
+        data-lgid={lgIds.root}
+        ref={fwdRef}
+      >
+        <button
+          data-testid={lgIds.button}
+          data-lgid={lgIds.button}
+        >
+          Click Me I'm Irish
+       </button>
+      </div>
+    );
+  },
+);
+```
+
 ## References
 
 - [Airbnb Javascript Style Guide](https://github.com/airbnb/javascript)

packages/button/src/Button/Button.tsx

@@ -11,7 +11,7 @@ import { BaseFontSize } from '@leafygreen-ui/tokens';
 import { ButtonContent } from '../ButtonContent/ButtonContent';
 import { ButtonClassName } from '../styles';
 import { BaseButtonProps, Size, Variant } from '../types';
-import { DEFAULT_LGID_ROOT, getLgIds } from '../utils';
+import { getLgIds } from '../utils';
 
 import { getClassName } from './Button.styles';
 
@@ -24,7 +24,7 @@ export const Button = InferredPolymorphic<BaseButtonProps, 'button'>(
       variant = Variant.Default,
       size = Size.Default,
       darkMode: darkModeProp,
-      'data-lgid': dataLgId = DEFAULT_LGID_ROOT,
+      'data-lgid': dataLgId = getLgIds().root,
       baseFontSize = BaseFontSize.Body1,
       disabled = false,
       onClick,

packages/button/src/utils/getLgIds.ts

@@ -1,6 +1,8 @@
+import { LgIdString } from '@leafygreen-ui/lib';
+
 export const DEFAULT_LGID_ROOT = 'lg-button';
 
-export const getLgIds = (root: `lg-${string}` = DEFAULT_LGID_ROOT) => {
+export const getLgIds = (root: LgIdString = DEFAULT_LGID_ROOT) => {
   return {
     root,
   } as const;

packages/button/src/utils/getTestUtils.ts

@@ -1,12 +1,12 @@
-// import { queryByLgId } from '@lg-tools/test-harnesses';
-// import { findByLgId } from '@lg-tools/test-harnesses';
 import { findByLgId, getByLgId, queryByLgId } from '@lg-tools/test-harnesses';
 
+import { LgIdString } from '@leafygreen-ui/lib';
+
 import { DEFAULT_LGID_ROOT, getLgIds } from './getLgIds';
 import { GetTestUtilsReturnType } from './getTestUtils.types';
 
 export const getTestUtils = <T extends HTMLElement = HTMLElement>(
-  lgId: `lg-${string}` = DEFAULT_LGID_ROOT,
+  lgId: LgIdString = DEFAULT_LGID_ROOT,
 ): GetTestUtilsReturnType<T> => {
   const lgIds = getLgIds(lgId);
 

packages/checkbox/src/Checkbox/Checkbox.tsx

@@ -13,7 +13,7 @@ import {
 } from '@leafygreen-ui/typography';
 
 import { Check } from '../Check';
-import { LGIDS_CHECKBOX } from '../constants';
+import { getLgIds } from '../utils/getLgIds';
 
 import {
   checkWrapperClassName,
@@ -45,7 +45,7 @@ const Checkbox = React.forwardRef(
       checked: checkedProp,
       className,
       darkMode: darkModeProp,
-      'data-lgid': dataLgId = LGIDS_CHECKBOX.root,
+      'data-lgid': dataLgId = getLgIds().root,
       description,
       disabled = false,
       id: idProp,
@@ -63,6 +63,8 @@ const Checkbox = React.forwardRef(
     const { darkMode, theme } = useDarkMode(darkModeProp);
     const baseFontSize = useUpdatedBaseFontSize(baseFontSizeProp);
 
+    const lgIds = getLgIds(dataLgId);
+
     const [checked, setChecked] = React.useState(defaultChecked);
     const isChecked = React.useMemo(
       () => (checkedProp != null ? checkedProp : checked),
@@ -124,7 +126,7 @@ const Checkbox = React.forwardRef(
             },
             className,
           )}
-          data-lgid={dataLgId}
+          data-lgid={lgIds.root}
           style={style}
         >
           <Label
@@ -134,6 +136,7 @@ const Checkbox = React.forwardRef(
             className={cx(labelStyle, labelHoverStyle[theme], {
               [disabledLabelStyle]: disabled,
             })}
+            data-lgid={lgIds.root}
           >
             <input
               {...rest}
@@ -178,7 +181,11 @@ const Checkbox = React.forwardRef(
           </Label>
 
           {description && (
-            <Description className={descriptionStyle} disabled={disabled}>
+            <Description
+              className={descriptionStyle}
+              disabled={disabled}
+              data-lgid={lgIds.root}
+            >
               {description}
             </Description>
           )}

packages/checkbox/src/constants.ts

@@ -7,9 +7,3 @@ export const insetPct = 100 - hypotenusePct;
 export const rippleScale = 2.25;
 export const rippleTransitionScale = 4;
 export const rippleTransitionDelay = -rippleTransitionScale / rippleScale;
-
-const LGID_ROOT = 'lg-checkbox';
-
-export const LGIDS_CHECKBOX = {
-  root: LGID_ROOT,
-} as const;

packages/checkbox/src/index.ts

@@ -1,3 +1,7 @@
 export { type CheckboxProps, checkWrapperClassName, default } from './Checkbox';
-export { LGIDS_CHECKBOX } from './constants';
-export { getTestUtils } from './utils';
+export {
+  DEFAULT_LGID_ROOT,
+  getLgIds,
+  type GetLgIdsReturnType,
+  getTestUtils,
+} from './utils';

packages/checkbox/src/utils/getLgIds.ts

@@ -0,0 +1,12 @@
+import { LgIdString } from '@leafygreen-ui/lib';
+
+export const DEFAULT_LGID_ROOT = 'lg-checkbox';
+
+export const getLgIds = (root: LgIdString = DEFAULT_LGID_ROOT) => {
+  const ids = {
+    root,
+  } as const;
+  return ids;
+};
+
+export type GetLgIdsReturnType = ReturnType<typeof getLgIds>;

packages/checkbox/src/utils/getTestUtils.tsx

@@ -1,34 +1,36 @@
 import { getByLgId, queryBySelector } from '@lg-tools/test-harnesses';
 
-import { LGIDS_TYPOGRAPHY } from '@leafygreen-ui/typography';
-
-import { LGIDS_CHECKBOX } from '../constants';
+import { LgIdString } from '@leafygreen-ui/lib';
+import { getLgIds as getLgTypographyLgIds } from '@leafygreen-ui/typography';
 
+import { DEFAULT_LGID_ROOT, getLgIds } from './getLgIds';
 import { CheckboxTestUtilsReturnType } from './getTestUtils.types';
 
 export const getTestUtils = (
-  lgId: string = LGIDS_CHECKBOX.root,
+  lgId: LgIdString = DEFAULT_LGID_ROOT,
 ): CheckboxTestUtilsReturnType => {
+  const lgIds = getLgIds(lgId);
+  const typographyLgIds = getLgTypographyLgIds(lgIds.root);
   /**
    * Queries the DOM for the element using the `data-lgid` data attribute.
    * Will throw if no element is found.
    */
-  const element = getByLgId!(lgId);
+  const element = getByLgId!(lgIds.root);
 
   /**
    * Queries the `element` for the label element. Will return `null` if the label is not found.
    */
   const getLabel = queryBySelector<HTMLLabelElement>(
     element,
-    `[data-lgid=${LGIDS_TYPOGRAPHY.label}]`,
+    `[data-lgid=${typographyLgIds.label}]`,
   );
 
   /**
    * Queries the `element` for the description element. Will return `null` if the desription is not found.
    */
   const getDescription = queryBySelector<HTMLElement>(
     element,
-    `[data-lgid=${LGIDS_TYPOGRAPHY.description}]`,
+    `[data-lgid=${typographyLgIds.description}]`,
   );
 
   /**

packages/checkbox/src/utils/index.ts

@@ -1 +1,6 @@
+export {
+  DEFAULT_LGID_ROOT,
+  getLgIds,
+  type GetLgIdsReturnType,
+} from './getLgIds';
 export { getTestUtils } from './getTestUtils';

packages/code/src/Code/Code.tsx

@@ -14,7 +14,7 @@ import { numOfCollapsedLinesOfCode } from '../constants';
 import CopyButton from '../CopyButton/CopyButton';
 import { Syntax } from '../Syntax';
 import { Language } from '../types';
-import { DEFAULT_LGID_ROOT, getLgIds } from '../utils/getLgIds';
+import { getLgIds } from '../utils/getLgIds';
 
 import {
   getCodeStyles,
@@ -46,7 +46,7 @@ function Code({
   onCopy,
   panel,
   customKeywords,
-  'data-lgid': dataLgId = DEFAULT_LGID_ROOT,
+  'data-lgid': dataLgId = getLgIds().root,
   baseFontSize: baseFontSizeProp,
   ...rest
 }: CodeProps) {
@@ -184,12 +184,12 @@ function Code({
       language={languageProp}
       isLoading={isLoading}
       showPanel={showPanel}
-      lgids={lgIds}
+      lgIds={lgIds}
     >
       <div
         className={getWrapperStyles({ theme, className })}
         data-language={languageProp}
-        data-lgid={dataLgId}
+        data-lgid={lgIds.root}
       >
         <div
           className={getCodeStyles({

packages/code/src/CodeContext/CodeContext.tsx

@@ -7,9 +7,13 @@ import React, {
 
 import LeafyGreenProvider from '@leafygreen-ui/leafygreen-provider';
 
+import { getLgIds } from '../utils';
+
 import { type CodeProviderProps } from './CodeContext.types';
 
-export const CodeContext = createContext<Partial<CodeProviderProps>>({});
+export const CodeContext = createContext<Partial<CodeProviderProps>>({
+  lgIds: getLgIds(),
+});
 
 export const useCodeContext = () =>
   useContext<CodeProviderProps>(
@@ -23,7 +27,7 @@ const CodeContextProvider = ({
   language,
   isLoading,
   showPanel,
-  lgids,
+  lgIds,
 }: PropsWithChildren<CodeProviderProps>) => {
   const CodeProvider = (CodeContext as React.Context<CodeProviderProps>)
     .Provider;
@@ -34,9 +38,9 @@ const CodeContextProvider = ({
       language,
       showPanel,
       isLoading,
-      lgids,
+      lgIds,
     };
-  }, [contents, language, showPanel, isLoading, lgids]);
+  }, [contents, language, showPanel, isLoading, lgIds]);
 
   return (
     <LeafyGreenProvider darkMode={darkMode}>

packages/code/src/CodeContext/CodeContext.types.ts

@@ -28,5 +28,5 @@ export type CodeProviderProps = DarkModeProps & {
   /**
    * LGIDs for the code snippet.
    */
-  lgids: GetLgIdsReturnType;
+  lgIds: GetLgIdsReturnType;
 };

packages/code/src/CopyButton/CopyButton.spec.tsx

@@ -26,7 +26,7 @@ describe('CopyButton', () => {
     return render(
       <CodeContextProvider
         // @ts-expect-error - other ids are missing but not needed for test
-        lgids={{
+        lgIds={{
           copyButton: `lg-code-copy_button`,
           copyTooltip: `lg-code-copy_tooltip`,
         }}