Prefix all component classes with .Hyp-

Currently, the SASS entrypoint for this package generates all styles for all shared components. While we may wish to adapt that piece of the puzzle at some point to give more granular control, some protection is needed in the short term at the very least to protect against CSS conflicts for generically-named components like `Panel`, `Modal`, `Dialog`, etc., for applications that use this package but might not yet actually use those individual components (i.e. have implementations of their own at present). Utility and pattern classes (which are not currently part of the public API but will and may be, respectively) are already prefixed with `.hyp-`. Adhering to the same general naming principle, these changes add a `.Hyp-` prefix to all component classes, resulting in, e.g. `.Hyp-Panel`. Use of these classes is currently an internal concern only, so these changes should have no effect for consuming applications. Customization of common component styling, such as it has been done thus far, uses mixins and doesn't directly reference class names. This change should also make it easier to spot whether a component is common or local to the application.
hypothesis · Jun 7, 2021 · aac81bf · aac81bf
1 parent b394593
commit aac81bf
Show file tree

Hide file tree

Showing 15 changed files with 56 additions and 58 deletions.
diff --git a/src/components/Dialog.js b/src/components/Dialog.js
@@ -102,8 +102,8 @@ export function Dialog({
     <div
       aria-labelledby={dialogTitleId}
       className={classnames(
-        'Dialog',
-        { 'Dialog--closeable': !!onCancel },
+        'Hyp-Dialog',
+        { 'Hyp-Dialog--closeable': !!onCancel },
         contentClass
       )}
       ref={rootEl}
@@ -112,21 +112,21 @@ export function Dialog({
     >
       <header>
         {icon && (
-          <div className="Dialog__header-icon">
+          <div className="Hyp-Dialog__header-icon">
             <SvgIcon name={icon} title={title} data-testid="header-icon" />
           </div>
         )}
-        <h2 className="Dialog__title" id={dialogTitleId}>
+        <h2 className="Hyp-Dialog__title" id={dialogTitleId}>
           {title}
         </h2>
         {onCancel && (
-          <div className="Dialog__close">
+          <div className="Hyp-Dialog__close">
             <IconButton icon="cancel" title="Close" onClick={onCancel} />
           </div>
         )}
       </header>
       <div>{children}</div>
-      <div className="Dialog__actions">
+      <div className="Hyp-Dialog__actions">
         {onCancel && (
           <LabeledButton data-testid="cancel-button" onClick={onCancel}>
             {cancelLabel}

diff --git a/src/components/Modal.js b/src/components/Modal.js
@@ -34,8 +34,8 @@ export function Modal({ children, onCancel, ...restProps }) {
 
   return (
     <>
-      <div className="Modal__overlay" />
-      <div className="Modal" ref={modalContainerRef}>
+      <div className="Hyp-Modal__overlay" />
+      <div className="Hyp-Modal" ref={modalContainerRef}>
         <Dialog onCancel={onCancel} {...restProps}>
           {children}
         </Dialog>

diff --git a/src/components/Panel.js b/src/components/Panel.js
@@ -22,17 +22,19 @@ export function Panel({ children, icon, onClose, title }) {
   const withCloseButton = !!onClose;
   return (
     <div
-      className={classnames('Panel', { 'Panel--closeable': withCloseButton })}
+      className={classnames('Hyp-Panel', {
+        'Hyp-Panel--closeable': withCloseButton,
+      })}
     >
       <header>
         {icon && (
-          <div className="Panel__header-icon">
+          <div className="Hyp-Panel__header-icon">
             <SvgIcon name={icon} title={title} />
           </div>
         )}
-        <h2 className="Panel__title">{title}</h2>
+        <h2 className="Hyp-Panel__title">{title}</h2>
         {withCloseButton && (
-          <div className="Panel__close">
+          <div className="Hyp-Panel__close">
             <IconButton icon="cancel" title="Close" onClick={onClose} />
           </div>
         )}

diff --git a/src/components/SvgIcon.js b/src/components/SvgIcon.js
@@ -68,7 +68,7 @@ export function SvgIcon({ name, className = '', inline = false, title = '' }) {
 
   return (
     <span
-      className={classnames('SvgIcon', { 'SvgIcon--inline': inline })}
+      className={classnames('Hyp-SvgIcon', { 'Hyp-SvgIcon--inline': inline })}
       dangerouslySetInnerHTML={{ __html: markup }}
       ref={element}
       {...spanProps}

diff --git a/src/components/buttons.js b/src/components/buttons.js
@@ -87,7 +87,7 @@ function ButtonBase({
  *
  * @param {IconButtonProps} props
  */
-export function IconButton({ className = 'IconButton', ...restProps }) {
+export function IconButton({ className = 'Hyp-IconButton', ...restProps }) {
   const { icon } = restProps;
   return (
     <ButtonBase className={className} {...restProps}>
@@ -103,7 +103,7 @@ export function IconButton({ className = 'IconButton', ...restProps }) {
  */
 export function LabeledButton({
   children,
-  className = 'LabeledButton',
+  className = 'Hyp-LabeledButton',
   ...restProps
 }) {
   const { icon, iconPosition = 'left' } = restProps;
@@ -122,5 +122,5 @@ export function LabeledButton({
  * @param {ButtonBaseProps} props
  */
 export function LinkButton(props) {
-  return <ButtonBase className="LinkButton" {...props} />;
+  return <ButtonBase className="Hyp-LinkButton" {...props} />;
 }
diff --git a/src/components/test/Dialog-test.js b/src/components/test/Dialog-test.js
@@ -20,7 +20,7 @@ describe('Dialog', () => {
         <span>content</span>
       </Dialog>
     );
-    assert.isTrue(wrapper.find('.Dialog').hasClass('foo'));
+    assert.isTrue(wrapper.find('.Hyp-Dialog').hasClass('foo'));
   });
 
   it('renders buttons', () => {

diff --git a/src/components/test/Panel-test.js b/src/components/test/Panel-test.js
@@ -24,7 +24,7 @@ describe('Panel', () => {
 
   it('renders the provided title', () => {
     const wrapper = createPanel({ title: 'My Panel' });
-    const titleEl = wrapper.find('.Panel__title');
+    const titleEl = wrapper.find('.Hyp-Panel__title');
     assert.equal(titleEl.text(), 'My Panel');
   });
 

diff --git a/src/components/test/SvgIcon-test.js b/src/components/test/SvgIcon-test.js
@@ -65,16 +65,16 @@ describe('SvgIcon', () => {
     const container = document.createElement('div');
     render(<SvgIcon name="arrow-left" />, container);
     const wrapper = container.querySelector('span');
-    assert.isTrue(wrapper.classList.contains('SvgIcon'));
-    assert.isFalse(wrapper.classList.contains('SvgIcon--inline'));
+    assert.isTrue(wrapper.classList.contains('Hyp-SvgIcon'));
+    assert.isFalse(wrapper.classList.contains('Hyp-SvgIcon--inline'));
   });
 
   it('appends an inline class to wrapper if `inline` prop is `true`', () => {
     const container = document.createElement('div');
     render(<SvgIcon name="arrow-left" inline={true} />, container);
     const wrapper = container.querySelector('span');
-    assert.isTrue(wrapper.classList.contains('SvgIcon'));
-    assert.isTrue(wrapper.classList.contains('SvgIcon--inline'));
+    assert.isTrue(wrapper.classList.contains('Hyp-SvgIcon'));
+    assert.isTrue(wrapper.classList.contains('Hyp-SvgIcon--inline'));
   });
 
   it('sets a title to the containing `span` element if `title` is present', () => {

diff --git a/src/components/test/buttons-test.js b/src/components/test/buttons-test.js
@@ -9,6 +9,7 @@ import mockImportedComponents from '../../../test/util/mock-imported-components'
 
 // Add common tests for a button component for stuff provided by `ButtonBase`
 function addCommonTests({ componentName, createComponentFn, withIcon = true }) {
+  const className = `Hyp-${componentName}`;
   describe(`${componentName} common support`, () => {
     if (withIcon) {
       it('renders the indicated icon', () => {
@@ -17,7 +18,7 @@ function addCommonTests({ componentName, createComponentFn, withIcon = true }) {
         const icon = wrapper.find('SvgIcon');
         assert.equal(icon.prop('name'), 'fakeIcon');
         // Icon is positioned "left" even if it is the only element in the <button>
-        assert.isTrue(button.hasClass(`${componentName}--icon-left`));
+        assert.isTrue(button.hasClass(`${className}--icon-left`));
       });
     }
 
@@ -53,43 +54,37 @@ function addCommonTests({ componentName, createComponentFn, withIcon = true }) {
     it('uses a default className', () => {
       const wrapper = createComponentFn();
 
-      assert.isTrue(wrapper.find('button').hasClass(componentName));
+      assert.isTrue(wrapper.find('button').hasClass(className));
     });
 
     ['primary', 'light', 'dark'].forEach(variant => {
       it('renders a valid variant', () => {
         const wrapper = createComponentFn({ variant });
 
         assert.isTrue(
-          wrapper.find('button').hasClass(`${componentName}--${variant}`)
+          wrapper.find('button').hasClass(`${className}--${variant}`)
         );
       });
     });
 
     it('sets a `normal` variant modifier class by default', () => {
       const wrapper = createComponentFn();
 
-      assert.isTrue(
-        wrapper.find('button').hasClass(`${componentName}--normal`)
-      );
+      assert.isTrue(wrapper.find('button').hasClass(`${className}--normal`));
     });
 
     ['small', 'medium', 'large'].forEach(size => {
       it('renders a valid size', () => {
         const wrapper = createComponentFn({ size });
 
-        assert.isTrue(
-          wrapper.find('button').hasClass(`${componentName}--${size}`)
-        );
+        assert.isTrue(wrapper.find('button').hasClass(`${className}--${size}`));
       });
     });
 
     it('sets a `medium` size modifier class by default', () => {
       const wrapper = createComponentFn();
 
-      assert.isTrue(
-        wrapper.find('button').hasClass(`${componentName}--medium`)
-      );
+      assert.isTrue(wrapper.find('button').hasClass(`${className}--medium`));
     });
 
     it('overrides className when provided', () => {
@@ -102,7 +97,7 @@ function addCommonTests({ componentName, createComponentFn, withIcon = true }) {
       assert.isTrue(
         wrapper.find('button').hasClass('CustomClassName--primary')
       );
-      assert.isFalse(wrapper.find('button').hasClass(componentName));
+      assert.isFalse(wrapper.find('button').hasClass(className));
     });
 
     it('adds inline styles when provided', () => {
@@ -245,7 +240,7 @@ describe('buttons', () => {
       const icon = wrapper.find('SvgIcon');
       const button = wrapper.find('button');
       assert.equal(icon.prop('name'), 'fakeIcon');
-      assert.isTrue(button.hasClass('LabeledButton--icon-right'));
+      assert.isTrue(button.hasClass('Hyp-LabeledButton--icon-right'));
     });
 
     it('does not render an icon if none indicated', () => {

diff --git a/styles/README.md b/styles/README.md
@@ -57,14 +57,14 @@ Mixins in `mixins` and utility styles in `util` loosely apply [Atomic Design](ht
 
 The directory that a SASS module lives in dictates what it should provide (styles, mixins, variables, etc.) and what kind of dependencies it is allowed:
 
-| Directory    | Description                  | Provides  | Dependencies          |
-| ------------ | ---------------------------- | --------- | --------------------- |
-| `base`       | Reset and element styles     | styles    | mixins, variables[^1] |
-| `components` | Styles for shared components | styles    | any                   |
-| `mixins`     | Mixins                       | mixins    | mixins[^2], variables |
-| `patterns`   | Pattern styles               | styles    | mixins                |
-| `util`       | Utility styles               | styles    | mixins                |
-| `variables`  | Variables                    | variables | none                  |
+| Directory    | Description                                                 | Provides  | Dependencies          |
+| ------------ | ----------------------------------------------------------- | --------- | --------------------- |
+| `base`       | Reset and element styles. Used only by the pattern library. | styles    | mixins, variables[^1] |
+| `components` | Styles for shared components                                | styles    | any                   |
+| `mixins`     | Mixins                                                      | mixins    | mixins[^2], variables |
+| `patterns`   | Pattern styles                                              | styles    | mixins                |
+| `util`       | Utility styles                                              | styles    | mixins                |
+| `variables`  | Variables                                                   | variables | none                  |
 
 ## CSS Output and Ordering
 
@@ -85,13 +85,14 @@ Note `utils` in last position, to assure these classes override other rules.
 
 ### Selectors and Class naming
 
-We use [BEM (Block Element Modifier)](http://getbem.com/) methodology for class naming.
+All class-name selectors generated by this package's SASS must be prefixed (see details below). We use [BEM (Block Element Modifier)](http://getbem.com/) methodology for class naming.
 
-- `base` modules should use element selectors (no class names).
-- Component class names should use PascalCase, e.g. `.HelpPanel`. All other classnames require a .`hyp-` prefix.
-- All utility and pattern classnames should be prefixed with `.hyp-`.
-- Atomic-level utility classes should be prefixed with `.hyp-u-`, e.g. `.hyp-u-border--left`. These are classes that may be used additively to adjust styling on a single element.
-- Composite (molecule, organism) class names do not require `u`-prefixes, but should be lower-case, e.g. `.hyp-frame`.
+_Note_: `base` modules use element selectors (no class names). These element selectors and resets are used by the pattern library internally and are not currently part of the public API.
+
+- Component class names should be prefixed with `.Hyp-` and use PascalCase, e.g. `.Hyp-SomePanel`.
+- All other class names should be kebab-case:
+  - Pattern (module, organism, etc.) class names should be prefixed with `.hyp-`, e.g. `.hyp-card`.
+  - Utility class names should be prefixed with `.hyp-u-`, e.g. `.hyp-u-border--left`. These are classes that may be used individually to adjust styling on a single element.
 
 ### Variables
 

diff --git a/styles/components/Dialog.scss b/styles/components/Dialog.scss
@@ -1,5 +1,5 @@
 @use '../mixins/patterns/organisms';
 
-.Dialog {
+.Hyp-Dialog {
   @include organisms.panel;
 }
diff --git a/styles/components/Modal.scss b/styles/components/Modal.scss
@@ -1,10 +1,10 @@
 @use '../mixins/layout';
 @use '../mixins/patterns/molecules';
 
-.Modal__overlay {
+.Hyp-Modal__overlay {
   @include layout.overlay;
 }
 
-.Modal {
+.Hyp-Modal {
   @include molecules.modal;
 }
diff --git a/styles/components/Panel.scss b/styles/components/Panel.scss
@@ -1,5 +1,5 @@
 @use '../mixins/patterns/organisms';
 
-.Panel {
+.Hyp-Panel {
   @include organisms.panel;
 }
diff --git a/styles/components/SvgIcon.scss b/styles/components/SvgIcon.scss
@@ -1,5 +1,5 @@
 /* Make the wrapper element's size match the contained `svg` element  */
-.SvgIcon {
+.Hyp-SvgIcon {
   display: flex;
 
   &--inline {

diff --git a/styles/components/buttons/_styles.scss b/styles/components/buttons/_styles.scss
@@ -1,16 +1,16 @@
 @use 'mixins';
 
 // A button with text, and optionally an icon
-.LabeledButton {
+.Hyp-LabeledButton {
   @include mixins.LabeledButton;
 }
 
 // A button with only an icon and no label/text
-.IconButton {
+.Hyp-IconButton {
   @include mixins.IconButton;
 }
 
 // A button styled to appear as a link, with underline on hover
-.LinkButton {
+.Hyp-LinkButton {
   @include mixins.LinkButton;
 }