@cdc/core 4.26.1 → 4.26.3

package/components/Layout/components/Visualization/visualizations.scss

@@ -1,46 +1,263 @@
-.cdc-open-viz-module {
-  .cdc-chart-inner-container .cove-component__content {
-    padding: 0 0 27px 0 !important;
-  }
-  &.isEditor {
+.cove-visualization {
+  &.is-editor {
     overflow: auto;
     display: grid;
+    position: relative;
     transition: grid-template-columns 400ms ease-in-out;
     min-height: 100vh;
 
     .editor-panel__toggle {
-      transition: left 400ms ease-in-out;
+      transition: left 400ms ease-in-out, background 0.1s;
     }
 
     .sidebar {
-      transition: left 400ms ease-in-out;
+      overflow: hidden;
+    }
+
+    // Override dashboard's .editor-panel absolute positioning that conflicts with the grid layout.
+    // .cove-visualization.type-dashboard scopes .editor-panel { position: absolute } (specificity 0,3,0),
+    // so we need 4 classes here (specificity 0,4,0) to win.
+    .editor-panel.sidebar {
+      position: static;
+      z-index: auto;
+      overflow: hidden;
+      top: auto;
+      bottom: auto;
+      width: auto;
     }
 
     &.editor-panel--visible {
       grid-template-areas: 'panel content';
       grid-template-columns: 350px calc(100% - 350px);
-      overflow: hidden;
+
+      .cove-visualization__outer {
+        overflow: hidden;
+      }
     }
 
     &.editor-panel--hidden {
       grid-template-areas: 'panel content';
       grid-template-columns: 0px 100%;
+      overflow: hidden;
     }
 
     .cove-editor__content,
-    .cove-component__content {
+    .cove-visualization__outer,
+    .cove-visualization__inner {
       grid-area: content;
       position: relative;
       left: 0;
       width: 100% !important;
-      grid-area: content;
+    }
+
+    .cove-editor__content {
       padding: 1rem;
+    }
 
-      // Prevent double padding on nested .cove-component__content divs
-      // (e.g., in markup-include, waffle-chart, filtered-text)
-      .cove-component__content {
-        padding: 0;
-      }
+    .cove-visualization__outer {
+      padding: 1rem;
     }
   }
 }
+
+// Developer highlight tool — only active when .is-editor + config.visual.highlightWrappers
+// Enabled via ?isCoveDeveloper=true URL param + "Highlight Layout Wrappers" checkbox
+.cove-visualization.is-editor.cove-highlight-wrappers {
+  outline: 2px dashed #0050d8;
+  position: relative;
+
+  &::before {
+    background: #0050d8;
+    color: #fff;
+    content: 'cove-visualization';
+    font-family: monospace;
+    font-size: 10px;
+    line-height: 1;
+    padding: 2px 4px;
+    pointer-events: none;
+    position: absolute;
+    top: 0;
+    left: 0;
+    z-index: 9999;
+  }
+
+  .cove-visualization__outer {
+    outline: 2px dashed #00a91c;
+    position: relative;
+
+    &::before {
+      background: #00a91c;
+      color: #fff;
+      content: '__outer';
+      font-family: monospace;
+      font-size: 10px;
+      line-height: 1;
+      padding: 2px 4px;
+      pointer-events: none;
+      position: absolute;
+      top: 0;
+      left: 0;
+      z-index: 9999;
+    }
+  }
+
+  .cove-visualization__inner {
+    outline: 2px dashed #e52207;
+    position: relative;
+
+    &::before {
+      background: #e52207;
+      color: #fff;
+      content: '__inner';
+      font-family: monospace;
+      font-size: 10px;
+      line-height: 1;
+      padding: 2px 4px;
+      pointer-events: none;
+      position: absolute;
+      top: 0;
+      left: 0;
+      z-index: 9999;
+    }
+  }
+
+  .cove-visualization__title,
+  .cove-visualization__header {
+    outline: 2px dashed #8a2be2;
+    position: relative;
+
+    &::before {
+      background: #8a2be2;
+      color: #fff;
+      content: '__title';
+      font-family: monospace;
+      font-size: 10px;
+      line-height: 1;
+      padding: 2px 4px;
+      pointer-events: none;
+      position: absolute;
+      top: 0;
+      left: 0;
+      z-index: 9999;
+    }
+  }
+
+  .cove-visualization__body {
+    outline: 2px dashed #e52207;
+    position: relative;
+
+    &::before {
+      background: #e52207;
+      color: #fff;
+      content: '__body';
+      font-family: monospace;
+      font-size: 10px;
+      line-height: 1;
+      padding: 2px 4px;
+      pointer-events: none;
+      position: absolute;
+      top: 0;
+      left: 0;
+      z-index: 9999;
+    }
+  }
+
+  .cove-visualization__message {
+    outline: 2px dashed #0050d8;
+    position: relative;
+
+    &::before {
+      background: #0050d8;
+      color: #fff;
+      content: '__message';
+      font-family: monospace;
+      font-size: 10px;
+      line-height: 1;
+      padding: 2px 4px;
+      pointer-events: none;
+      position: absolute;
+      top: 0;
+      left: 0;
+      z-index: 9999;
+    }
+  }
+
+  .cove-visualization__body-wrap {
+    outline: 2px dashed #e66f0e;
+    position: relative;
+
+    &::before {
+      background: #e66f0e;
+      color: #fff;
+      content: '__body-wrap';
+      font-family: monospace;
+      font-size: 10px;
+      line-height: 1;
+      padding: 2px 4px;
+      pointer-events: none;
+      position: absolute;
+      top: 0;
+      left: 0;
+      z-index: 9999;
+    }
+  }
+
+}
+
+.cove-visualization {
+  font-size: var(--app-font-size);
+
+  .cove-visualization__body,
+  .cove-visualization__body-wrap,
+  .cove-visualization__message-section,
+  .cove-visualization__content-section,
+  .cove-visualization__body-subtext-section,
+  .cove-visualization__body-footer-section,
+  .cove-visualization__subtext-section {
+    color: var(--baseColor);
+    font-family: var(--visualization-body-font-family, var(--app-font-main));
+    line-height: var(--visualization-body-line-height, 1.5);
+  }
+
+  .cove-visualization__content-section,
+  .cove-visualization__message-section,
+  .cove-visualization__body-subtext-section,
+  .cove-visualization__body-footer-section,
+  .cove-visualization__subtext-section {
+    width: 100%;
+  }
+
+  .cove-visualization__title~.cove-visualization__body .cove-visualization__body-wrap,
+  .cove-visualization__body.component--has-legacy-border .cove-visualization__body-wrap,
+  .cove-visualization__body.component--has-border-color-theme .cove-visualization__body-wrap,
+  .cove-visualization__body.component--has-background .cove-visualization__body-wrap {
+    padding-top: var(--cove-visualization-section-gap, 1.5rem);
+    padding-bottom: var(--cove-visualization-section-gap, 1.5rem);
+  }
+
+  .cove-visualization__body.component--has-legacy-border .cove-visualization__content-section,
+  .cove-visualization__body.component--has-border-color-theme .cove-visualization__content-section,
+  .cove-visualization__body.component--has-background .cove-visualization__content-section {
+    padding-inline: 0;
+  }
+
+  &.type-data-bite .cove-visualization__body-wrap {
+    padding-top: var(--cove-visualization-section-gap, 1.5rem);
+    padding-bottom: var(--cove-visualization-section-gap, 1.5rem);
+  }
+
+  .cove-visualization__body-wrap {
+    display: flex;
+    flex-direction: column;
+    row-gap: var(--cove-visualization-section-gap, 1.5rem);
+
+    // Prevent content margins from stacking with row-gap
+    >*> :first-child {
+      margin-top: 0;
+    }
+
+    >*> :last-child {
+      margin-bottom: 0;
+    }
+  }
+}

package/components/Layout/components/VisualizationContainer.test.tsx

@@ -0,0 +1,67 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import VisualizationContainer from './VisualizationContainer'
+
+describe('VisualizationContainer', () => {
+  it('renders the shared outer shell contract for dashboard wrappers', () => {
+    const { container } = render(
+      <VisualizationContainer
+        config={{ type: 'dashboard', theme: 'theme-blue' }}
+        currentViewport='md'
+        imageId='dashboard-image'
+        isEditor={false}
+        renderResponsive={false}
+      >
+        <div>Dashboard body</div>
+      </VisualizationContainer>
+    )
+
+    const shell = container.querySelector('.cove-visualization')
+
+    expect(shell).toHaveClass('cdc-open-viz-module', 'type-dashboard', 'md', 'theme-blue')
+    expect(shell).toHaveAttribute('data-download-id', 'dashboard-image')
+    expect(shell?.querySelector('.cove-visualization__outer')).toBeNull()
+  })
+
+  it('renders the editor panel and responsive wrapper when enabled', () => {
+    const { container } = render(
+      <VisualizationContainer
+        config={{ type: 'chart', showEditorPanel: true }}
+        currentViewport='lg'
+        editorPanel={<div data-testid='editor-panel'>Editor Panel</div>}
+        isEditor={true}
+      >
+        <div>Chart body</div>
+      </VisualizationContainer>
+    )
+
+    expect(screen.getByTestId('editor-panel')).toBeInTheDocument()
+    expect(container.querySelector('.cove-visualization')).toHaveClass('type-chart', 'is-editor', 'editor-panel--visible')
+    expect(container.querySelector('.cove-visualization__outer')).toBeInTheDocument()
+  })
+
+  it('hides the editor panel class when editor panels are disabled in config', () => {
+    const { container } = render(
+      <VisualizationContainer config={{ type: 'map', showEditorPanel: false }} isEditor={true}>
+        <div>Map body</div>
+      </VisualizationContainer>
+    )
+
+    expect(container.querySelector('.cove-visualization')).toHaveClass('editor-panel--hidden')
+  })
+
+  it('uses the map header theme on the shared visualization shell', () => {
+    const { container } = render(
+      <VisualizationContainer
+        config={{ type: 'map', general: { headerColor: 'theme-purple' } }}
+        currentViewport='lg'
+        isEditor={false}
+      >
+        <div>Map body</div>
+      </VisualizationContainer>
+    )
+
+    expect(container.querySelector('.cove-visualization')).toHaveClass('type-map', 'theme-purple')
+  })
+})

package/components/Layout/components/VisualizationContainer.tsx

@@ -0,0 +1,37 @@
+import React, { forwardRef } from 'react'
+import Responsive from './Responsive'
+import Visualization, { type VisualizationShellConfig } from './Visualization'
+
+type VisualizationContainerProps = {
+  children: React.ReactNode
+  className?: string
+  config: VisualizationShellConfig
+  currentViewport?: string
+  editorPanel?: React.ReactNode
+  imageId?: string
+  isEditor: boolean
+  renderResponsive?: boolean
+}
+
+const VisualizationContainer = forwardRef<HTMLDivElement, VisualizationContainerProps>(
+  ({ children, className, config, currentViewport, editorPanel, imageId, isEditor, renderResponsive = true }, ref) => {
+    return (
+      <Visualization
+        ref={ref}
+        config={config}
+        isEditor={isEditor}
+        showEditorPanel={config?.showEditorPanel}
+        currentViewport={currentViewport}
+        imageId={imageId}
+        className={className}
+      >
+        {isEditor && editorPanel}
+        {renderResponsive ? <Responsive isEditor={isEditor}>{children}</Responsive> : children}
+      </Visualization>
+    )
+  }
+)
+
+VisualizationContainer.displayName = 'VisualizationContainer'
+
+export default VisualizationContainer

package/components/Layout/components/VisualizationContent.test.tsx

@@ -0,0 +1,182 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import VisualizationContent from './VisualizationContent'
+
+describe('VisualizationContent', () => {
+  it('renders the standard inner, body, and body-wrap layers by default', () => {
+    const { container } = render(
+      <VisualizationContent innerClassName='inner-extra' bodyClassName='body-extra' bodyWrapClassName='wrap-extra'>
+        <div>Inner content</div>
+      </VisualizationContent>
+    )
+
+    const inner = container.querySelector('.cove-visualization__inner')
+    const body = container.querySelector('.cove-visualization__body')
+    const bodyWrap = container.querySelector('.cove-visualization__body-wrap')
+    const content = container.querySelector('.cove-visualization__content-section')
+
+    expect(inner).toHaveClass('inner-extra')
+    expect(body).toHaveClass('body-extra')
+    expect(bodyWrap).toHaveClass('wrap-extra')
+    expect(inner?.firstElementChild).toBe(body)
+    expect(body?.firstElementChild).toBe(bodyWrap)
+    expect(bodyWrap?.firstElementChild).toBe(content)
+    expect(screen.getByText('Inner content')).toBeInTheDocument()
+  })
+
+  it('renders header and footer outside the body wrapper', () => {
+    const { container } = render(
+      <VisualizationContent
+        header={<div data-testid='header'>Header</div>}
+        footer={<div data-testid='footer'>Footer</div>}
+      >
+        <div>Wrapped content</div>
+      </VisualizationContent>
+    )
+
+    expect(screen.getByTestId('header')).toBeInTheDocument()
+    expect(screen.getByTestId('footer')).toBeInTheDocument()
+    expect(container.querySelector('.cove-visualization__body-wrap')?.textContent).toContain('Wrapped content')
+  })
+
+  it('renders message content inside the body-wrap before the wrapped content', () => {
+    const { container } = render(
+      <VisualizationContent message={<div data-testid='message'>Message</div>}>
+        <div>Wrapped content</div>
+      </VisualizationContent>
+    )
+
+    const body = container.querySelector('.cove-visualization__body')
+    const messageLayer = container.querySelector('.cove-visualization__message')
+    const message = container.querySelector('.cove-visualization__message-section')
+    const bodyWrap = container.querySelector('.cove-visualization__body-wrap')
+    const content = container.querySelector('.cove-visualization__content-section')
+
+    expect(screen.getByTestId('message')).toBeInTheDocument()
+    expect(messageLayer).toBe(message)
+    expect(body?.firstElementChild).toBe(bodyWrap)
+    expect(bodyWrap?.firstElementChild).toBe(message)
+    expect(bodyWrap?.children[1]).toBe(content)
+  })
+
+  it('adds the shared no-subtext body state only when outer subtext is absent', () => {
+    const { container: withoutSubtext } = render(
+      <VisualizationContent header={<div>Header</div>} message={<div>Message</div>}>
+        <div>Wrapped content</div>
+      </VisualizationContent>
+    )
+    const { container: withSubtext } = render(
+      <VisualizationContent header={<div>Header</div>} subtext={<div>Subtext</div>}>
+        <div>Wrapped content</div>
+      </VisualizationContent>
+    )
+
+    expect(withoutSubtext.querySelector('.cove-visualization__body')).toHaveClass(
+      'cove-visualization__body--no-subtext'
+    )
+    expect(withSubtext.querySelector('.cove-visualization__body')).not.toHaveClass(
+      'cove-visualization__body--no-subtext'
+    )
+  })
+
+  it('applies custom classes to the message wrapper', () => {
+    const { container } = render(
+      <VisualizationContent message={<div data-testid='message'>Message</div>} messageClassName='introText mb-4'>
+        <div>Wrapped content</div>
+      </VisualizationContent>
+    )
+
+    const message = container.querySelector('.cove-visualization__message')
+
+    expect(message).toHaveClass('introText')
+    expect(message).toHaveClass('mb-4')
+  })
+
+  it('applies the introText wrapper class when requested', () => {
+    const { container } = render(
+      <VisualizationContent message={<div data-testid='message'>Message</div>} messageIsIntroText>
+        <div>Wrapped content</div>
+      </VisualizationContent>
+    )
+
+    const message = container.querySelector('.cove-visualization__message')
+
+    expect(message).toHaveClass('introText')
+  })
+
+  it('renders subtext content inside the body after the body-wrap', () => {
+    const { container } = render(
+      <VisualizationContent subtext={<div data-testid='subtext'>Subtext</div>}>
+        <div>Wrapped content</div>
+      </VisualizationContent>
+    )
+
+    const body = container.querySelector('.cove-visualization__body')
+    const bodyWrap = container.querySelector('.cove-visualization__body-wrap')
+    const subtext = container.querySelector('.cove-visualization__subtext-section')
+
+    expect(screen.getByTestId('subtext')).toBeInTheDocument()
+    expect(body?.firstElementChild).toBe(bodyWrap)
+    expect(body?.lastElementChild).toBe(subtext)
+    expect(subtext).not.toHaveClass('mt-4')
+    expect(subtext).not.toHaveClass('mb-4')
+    expect(subtext).not.toHaveAttribute('style')
+  })
+
+  it('renders body subtext content inside the body-wrap after the wrapped content', () => {
+    const { container } = render(
+      <VisualizationContent bodySubtext={<div data-testid='body-subtext'>Body Subtext</div>}>
+        <div>Wrapped content</div>
+      </VisualizationContent>
+    )
+
+    const bodyWrap = container.querySelector('.cove-visualization__body-wrap')
+    const content = container.querySelector('.cove-visualization__content-section')
+    const bodySubtext = container.querySelector('.cove-visualization__body-subtext-section')
+
+    expect(screen.getByTestId('body-subtext')).toBeInTheDocument()
+    expect(bodyWrap?.lastElementChild).toBe(bodySubtext)
+    expect(bodyWrap?.firstElementChild).toBe(content)
+    expect(bodySubtext).not.toHaveClass('mt-4')
+    expect(bodySubtext).not.toHaveClass('mb-4')
+    expect(bodySubtext).not.toHaveAttribute('style')
+  })
+
+  it('renders body footer content inside the body-wrap after body subtext', () => {
+    const { container } = render(
+      <VisualizationContent
+        bodySubtext={<div data-testid='body-subtext'>Body Subtext</div>}
+        bodyFooter={<div data-testid='body-footer'>Body Footer</div>}
+      >
+        <div>Wrapped content</div>
+      </VisualizationContent>
+    )
+
+    const bodyWrap = container.querySelector('.cove-visualization__body-wrap')
+    const content = container.querySelector('.cove-visualization__content-section')
+    const bodySubtext = container.querySelector('.cove-visualization__body-subtext-section')
+    const bodyFooter = container.querySelector('.cove-visualization__body-footer-section')
+
+    expect(screen.getByTestId('body-footer')).toBeInTheDocument()
+    expect(bodyWrap?.children[0]).toBe(content)
+    expect(bodyWrap?.children[1]).toBe(bodySubtext)
+    expect(bodyWrap?.lastElementChild).toBe(bodyFooter)
+  })
+
+  it('passes through non-class inner div props, including refs', () => {
+    const innerRef = React.createRef<HTMLDivElement>()
+
+    const { container } = render(
+      <VisualizationContent innerClassName='inner-extra' innerProps={{ 'aria-label': 'Visualization content', ref: innerRef }}>
+        <div>Inner content</div>
+      </VisualizationContent>
+    )
+
+    const inner = container.querySelector('.cove-visualization__inner')
+
+    expect(inner).toHaveAttribute('aria-label', 'Visualization content')
+    expect(inner).toHaveClass('inner-extra')
+    expect(innerRef.current).toBe(inner)
+  })
+})

package/components/Layout/components/VisualizationContent.tsx

@@ -0,0 +1,75 @@
+import React from 'react'
+
+type VisualizationContentInnerProps = Omit<React.ComponentPropsWithRef<'div'>, 'className'>
+
+type VisualizationContentProps = {
+  bodyFooter?: React.ReactNode
+  bodySubtext?: React.ReactNode
+  bodyClassName?: string
+  bodyWrapClassName?: string
+  children: React.ReactNode
+  filters?: React.ReactNode
+  footer?: React.ReactNode
+  header?: React.ReactNode
+  innerClassName?: string
+  innerProps?: VisualizationContentInnerProps
+  message?: React.ReactNode
+  messageClassName?: string
+  messageIsIntroText?: boolean
+  subtext?: React.ReactNode
+}
+
+const VisualizationContent = ({
+  bodyFooter,
+  bodySubtext,
+  bodyClassName,
+  bodyWrapClassName,
+  children,
+  filters,
+  footer,
+  header,
+  innerClassName,
+  innerProps,
+  message,
+  messageClassName,
+  messageIsIntroText,
+  subtext
+}: VisualizationContentProps) => {
+  const resolvedInnerClasses = ['cove-visualization__inner', innerClassName].filter(Boolean).join(' ')
+  const bodyClasses = ['cove-visualization__body', !subtext && 'cove-visualization__body--no-subtext', bodyClassName].filter(Boolean).join(' ')
+  const bodyWrapClasses = ['cove-visualization__body-wrap', bodyWrapClassName].filter(Boolean).join(' ')
+
+  return (
+    <div {...innerProps} className={resolvedInnerClasses}>
+      {header}
+      <div className={bodyClasses}>
+        <div className={bodyWrapClasses}>
+          {message ? (
+            <section
+              className={[
+                'cove-visualization__message',
+                'cove-visualization__message-section',
+                messageIsIntroText && 'introText',
+                messageClassName
+              ]
+                .filter(Boolean)
+                .join(' ')}
+            >
+              {message}
+            </section>
+          ) : null}
+          {filters ? <section className='cove-visualization__filters-section'>{filters}</section> : null}
+          <section className='cove-visualization__content-section'>{children}</section>
+          {bodySubtext ? (
+            <section className='cove-visualization__body-subtext-section'>{bodySubtext}</section>
+          ) : null}
+          {bodyFooter ? <section className='cove-visualization__body-footer-section'>{bodyFooter}</section> : null}
+        </div>
+        {subtext ? <section className='cove-visualization__subtext-section'>{subtext}</section> : null}
+      </div>
+      {footer}
+    </div>
+  )
+}
+
+export default VisualizationContent

package/components/Layout/index.tsx

@@ -1,11 +1,11 @@
 import Responsive from './components/Responsive'
 import Sidebar from './components/Sidebar'
+import VisualizationContainer from './components/VisualizationContainer'
+import VisualizationContent from './components/VisualizationContent'
 import VisualizationWrapper from './components/Visualization'
 
-const Layout = {
-  Responsive,
-  Sidebar,
-  VisualizationWrapper
-}
+export { Responsive, Sidebar, VisualizationContainer, VisualizationContent, VisualizationWrapper }
 
+/** @deprecated Use named imports instead: `import { Responsive, Sidebar, VisualizationContainer, VisualizationContent } from '@cdc/core/components/Layout'` */
+const Layout = { Responsive, Sidebar, VisualizationContainer, VisualizationContent, VisualizationWrapper }
 export default Layout

package/components/Layout/styles/editor-utils.scss

@@ -1,7 +1,7 @@
 $editorAnimationTimer: 400ms;
 $primary: #3e92d5;
 
-.cdc-open-viz-module .cove-editor-utils__hotkeys {
+.cove-visualization .cove-editor-utils__hotkeys {
   display: inline-flex;
   flex-flow: row nowrap;
   position: fixed;
@@ -54,7 +54,7 @@ $primary: #3e92d5;
   }
 }
 
-.cdc-open-viz-module .cove-editor-utils__breakpoints {
+.cove-visualization .cove-editor-utils__breakpoints {
   position: fixed;
   bottom: 5rem;
   right: 4rem;
@@ -97,7 +97,7 @@ $primary: #3e92d5;
   list-style: none;
 }
 
-.cdc-open-viz-module .cove-editor-utils__breakpoints-item {
+.cove-visualization .cove-editor-utils__breakpoints-item {
   display: block;
   position: relative;
   margin-right: 1rem;