@hubspot/cms-component-library 0.1.0 → 0.2.0

package/components/componentLibrary/Logo/stories/Logo.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import Logo from '../index.js';
+import { LogoProps } from '../types.js';
+import { withLogoStyles } from './LogoDecorator.js';
+import { SBContainer, SBFocusWrapper } from '@sb-utils';
+
+const meta: Meta<LogoProps> = {
+  title: 'Component Library/Logo',
+  component: Logo,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `The Logo component displays a brand logo with configurable sizing. It automatically wraps the logo in a link if provided in the brand settings, and supports both real brand logos and dummy logo data for development.`,
+      },
+    },
+  },
+  decorators: [withLogoStyles],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    useDummyLogo: true,
+    loading: 'eager',
+  },
+};
+
+export const SizeVariations: Story = {
+  name: 'Size Variations',
+  render: () => (
+    <SBContainer flex direction="column" gap="large">
+      <SBContainer addBackground>
+        <h4>No Max Constraints</h4>
+        <p>Logo uses its natural dimensions</p>
+        <Logo useDummyLogo />
+      </SBContainer>
+
+      <SBContainer addBackground>
+        <h4>Max Width Only (120px)</h4>
+        <p>Width is constrained, height scales proportionally</p>
+        <Logo useDummyLogo maxWidth="120px" />
+      </SBContainer>
+
+      <SBContainer addBackground>
+        <h4>Max Height Only (60px)</h4>
+        <p>Height is constrained, width scales proportionally</p>
+        <Logo useDummyLogo maxHeight="60px" />
+      </SBContainer>
+
+      <SBContainer addBackground>
+        <h4>Max Width (150px) and Max Height (50px)</h4>
+        <p>Both dimensions are constrained, logo fits within bounds</p>
+        <Logo useDummyLogo maxWidth="150px" maxHeight="50px" />
+      </SBContainer>
+    </SBContainer>
+  ),
+};
+
+export const InteractionStates: Story = {
+  name: 'Interaction States',
+  render: () => (
+    <SBContainer flex direction="column" gap="large">
+      <SBContainer addBackground>
+        <h4>With Link (Clickable)</h4>
+        <p>The logo is wrapped in a link and shows hover/focus states</p>
+        <p>
+          <strong>Try:</strong> Hover over and tab to focus
+        </p>
+        <Logo useDummyLogo />
+      </SBContainer>
+
+      <SBContainer addBackground>
+        <h4>Focus State</h4>
+        <p>
+          In production, this focus outline appears when navigating with the
+          keyboard (Tab key). This Storybook demo auto-applies the focus state
+          to show how it looks.
+        </p>
+        <SBFocusWrapper>
+          <Logo useDummyLogo />
+        </SBFocusWrapper>
+      </SBContainer>
+    </SBContainer>
+  ),
+};

package/components/componentLibrary/Logo/stories/LogoDecorator.module.scss

@@ -0,0 +1,10 @@
+.decoratorContainer {
+  padding: 20px;
+  --hscl-logo-display: inline-block;
+  --hscl-logo-maxWidth: 100%;
+  --hscl-logo-maxHeight: none;
+  --hscl-logo-cursor-hover: pointer;
+  --hscl-logo-outlineWidth-focus: 2px;
+  --hscl-logo-outlineColor-focus: #007aff;
+  --hscl-logo-outlineOffset-focus: 2px;
+}

package/components/componentLibrary/Logo/stories/LogoDecorator.tsx

@@ -0,0 +1,8 @@
+import type { Decorator } from '@storybook/react';
+import styles from './LogoDecorator.module.scss';
+
+export const withLogoStyles: Decorator = Story => (
+  <div className={styles.decoratorContainer}>
+    <Story />
+  </div>
+);

package/components/componentLibrary/Logo/types.tsx

@@ -0,0 +1,16 @@
+export type LogoData = {
+  src: string;
+  alt?: string;
+  width?: number;
+  height?: number;
+  link?: string;
+};
+
+export type LogoProps = {
+  useDummyLogo?: boolean;
+  className?: string;
+  style?: React.CSSProperties;
+  maxWidth?: string;
+  maxHeight?: string;
+  loading?: 'lazy' | 'eager' | 'disabled';
+};

package/components/componentLibrary/Menu/ContentFields.tsx

@@ -0,0 +1,16 @@
+import { MenuField } from '@hubspot/cms-components/fields';
+import { ContentFieldsProps } from './types.js';
+
+const ContentFields = ({
+  menuLabel = 'Menu',
+  menuName = 'menu',
+  menuDefault = 'default',
+}: ContentFieldsProps) => {
+  return (
+    <>
+      <MenuField label={menuLabel} name={menuName} default={menuDefault} />
+    </>
+  );
+};
+
+export default ContentFields;

package/components/componentLibrary/Menu/MenuItem/Chevron/index.module.scss

@@ -0,0 +1,6 @@
+.menuItemChevron {
+  width: 9px;
+  height: auto;
+  fill: var(--hscl-menuItem-chevron-fill, currentColor);
+  padding: 0;
+}

package/components/componentLibrary/Menu/MenuItem/Chevron/index.tsx

@@ -0,0 +1,17 @@
+import cx from '../../../utils/classname.js';
+import styles from './index.module.scss';
+
+export const ChevronIcon = () => {
+  return (
+    <svg
+      className={cx(styles.menuItemChevron, 'menuItemChevron')}
+      viewBox="0 0 28 17"
+      fill="currentColor"
+      xmlns="http://www.w3.org/2000/svg"
+      aria-hidden="true"
+      role="img"
+    >
+      <path d="M12.5875 15.8886C13.3687 16.6699 14.6375 16.6699 15.4187 15.8886L27.4187 3.88862C28.2 3.10737 28.2 1.83862 27.4187 1.05737C26.6375 0.276123 25.3687 0.276123 24.5875 1.05737L14 11.6449L3.41249 1.06362C2.63124 0.282372 1.36249 0.282372 0.581238 1.06362C-0.200012 1.84487 -0.200012 3.11362 0.581238 3.89487L12.5812 15.8949L12.5875 15.8886Z" />
+    </svg>
+  );
+};

package/components/componentLibrary/Menu/MenuItem/index.module.scss

@@ -0,0 +1,7 @@
+.link {
+  display: inline-flex;
+  flex-direction: row;
+  align-items: center;
+  gap: var(--hscl-menuItem-link-gap, 8px);
+  justify-content: flex-start;
+}

package/components/componentLibrary/Menu/MenuItem/index.tsx

@@ -0,0 +1,266 @@
+import { useRef, useState } from 'react';
+import { EnrichedMenuDataItem } from '../types.js';
+import { ChevronIcon } from './Chevron/index.js';
+import { HandleKeyDownProps, MenuItemProps } from './types.js';
+import styles from './index.module.scss';
+
+const MenuItem = ({
+  item,
+  level,
+  maxDepth,
+  addArrows = false,
+  className = '',
+  useNavigationControls = false,
+  style = {},
+}: MenuItemProps) => {
+  const itemRef = useRef<HTMLLIElement>(null);
+  const linkRef = useRef<HTMLAnchorElement>(null);
+  const [isSubmenuOpen, setIsSubmenuOpen] = useState(false);
+  const hasUrl = Boolean(item?.url && item.url.trim() !== '');
+  const hasChildren = Boolean(item?.children?.length);
+  const shouldShowChildren = maxDepth
+    ? hasChildren && level < maxDepth
+    : hasChildren;
+
+  const focusElement = (element: Element | null | undefined) => {
+    if (element instanceof HTMLElement) {
+      element.focus();
+    }
+  };
+
+  const focusNextSibling = () => {
+    const nextSibling = itemRef.current?.nextElementSibling;
+    if (nextSibling) {
+      focusElement(nextSibling);
+    } else {
+      focusFirstSibling();
+    }
+  };
+
+  const focusPreviousSibling = () => {
+    const previousSibling = itemRef.current?.previousElementSibling;
+    if (previousSibling) {
+      focusElement(previousSibling);
+    } else {
+      focusLastSibling();
+    }
+  };
+
+  const focusParentItem = () => {
+    const parentItem = itemRef.current?.parentElement?.closest('li');
+    focusElement(parentItem);
+  };
+
+  const focusParentNav = () => {
+    const parentNav = itemRef.current?.closest('nav');
+    focusElement(parentNav);
+  };
+
+  const focusFirstSibling = () => {
+    const parent = itemRef.current?.parentElement;
+    focusElement(parent?.firstElementChild);
+  };
+
+  const focusLastSibling = () => {
+    const parent = itemRef.current?.parentElement;
+    focusElement(parent?.lastElementChild);
+  };
+
+  const openSubmenu = () => {
+    setIsSubmenuOpen(true);
+
+    requestAnimationFrame(() => {
+      const firstChild = itemRef.current?.querySelector('ul > li');
+      focusElement(firstChild);
+    });
+  };
+
+  const closeSubmenu = () => {
+    setIsSubmenuOpen(false);
+  };
+
+  const activateLink = () => {
+    linkRef.current?.click();
+  };
+
+  const navigateToSiblingAndCloseSubmenu = (direction: 'next' | 'previous') => {
+    closeSubmenu();
+    if (direction === 'next') {
+      focusNextSibling();
+    } else {
+      focusPreviousSibling();
+    }
+  };
+
+  const returnToParentAndCloseSubmenu = () => {
+    focusParentItem();
+    closeSubmenu();
+  };
+
+  const exitMenuAndCloseSubmenu = () => {
+    closeSubmenu();
+    itemRef.current?.blur();
+  };
+
+  const handleKeyDown = ({ event, menuLevel }: HandleKeyDownProps) => {
+    const isTopLevel = menuLevel === 1;
+
+    event.stopPropagation();
+
+    switch (event.key) {
+      case 'ArrowRight':
+        event.preventDefault();
+        if (isTopLevel) {
+          navigateToSiblingAndCloseSubmenu('next');
+        } else if (shouldShowChildren) {
+          openSubmenu();
+        }
+        break;
+
+      case 'ArrowLeft':
+        event.preventDefault();
+        if (isTopLevel) {
+          navigateToSiblingAndCloseSubmenu('previous');
+        } else {
+          returnToParentAndCloseSubmenu();
+        }
+        break;
+
+      case 'ArrowDown':
+        event.preventDefault();
+        if (isTopLevel && shouldShowChildren) {
+          openSubmenu();
+        } else {
+          focusNextSibling();
+        }
+        break;
+
+      case 'ArrowUp':
+        event.preventDefault();
+        if (isTopLevel) {
+          focusParentNav();
+        } else {
+          focusPreviousSibling();
+        }
+        break;
+
+      case 'Enter':
+      case ' ':
+        event.preventDefault();
+        activateLink();
+        break;
+
+      case 'Escape':
+        event.preventDefault();
+        if (isTopLevel) {
+          exitMenuAndCloseSubmenu();
+        } else {
+          returnToParentAndCloseSubmenu();
+        }
+        break;
+
+      case 'Home':
+        event.preventDefault();
+        focusFirstSibling();
+        break;
+
+      case 'End':
+        event.preventDefault();
+        focusLastSibling();
+        break;
+
+      default:
+        break;
+    }
+  };
+
+  const renderContent = () => {
+    if (hasUrl) {
+      const linkAttributes =
+        item.linkTarget === '_blank'
+          ? { target: '_blank', rel: 'noopener noreferrer' }
+          : {};
+
+      return (
+        <a
+          ref={linkRef}
+          href={item.url!}
+          className={styles.link}
+          tabIndex={-1}
+          {...linkAttributes}
+        >
+          {item.label}
+          {shouldShowChildren && addArrows && <ChevronIcon />}
+        </a>
+      );
+    }
+
+    return (
+      <span className={styles.link}>
+        {item.label}
+        {shouldShowChildren && addArrows && <ChevronIcon />}
+      </span>
+    );
+  };
+
+  const handleBlur = (event: React.FocusEvent) => {
+    const relatedTarget = event.relatedTarget as Node | null;
+
+    // Keep submenu open if focus is moving to a child (drilling down)
+    if (
+      relatedTarget &&
+      itemRef.current?.contains(relatedTarget) &&
+      relatedTarget !== itemRef.current
+    ) {
+      return;
+    }
+
+    // Close submenu when moving away (up to parent, sideways to sibling, or outside)
+    setIsSubmenuOpen(false);
+  };
+
+  const itemStyle = {
+    ...style,
+    '--hscl-menuItem-level': level,
+  };
+
+  return (
+    <li
+      ref={itemRef}
+      className={className}
+      style={itemStyle}
+      data-level={level}
+      data-submenu-open={
+        useNavigationControls ? (isSubmenuOpen ? 'true' : 'false') : undefined
+      }
+      tabIndex={useNavigationControls ? -1 : 0}
+      role="menuitem"
+      aria-expanded={
+        useNavigationControls && shouldShowChildren ? isSubmenuOpen : undefined
+      }
+      {...(useNavigationControls && {
+        onKeyDown: event => handleKeyDown({ event, menuLevel: level }),
+        onBlur: handleBlur,
+      })}
+    >
+      {renderContent()}
+
+      {shouldShowChildren && (
+        <ul>
+          {item.children.map((child: EnrichedMenuDataItem) => (
+            <MenuItem
+              key={child._id}
+              item={child}
+              level={level + 1}
+              maxDepth={maxDepth}
+              addArrows={addArrows}
+              useNavigationControls={useNavigationControls}
+            />
+          ))}
+        </ul>
+      )}
+    </li>
+  );
+};
+
+export default MenuItem;

package/components/componentLibrary/Menu/MenuItem/types.ts

@@ -0,0 +1,17 @@
+import { CSSProperties, KeyboardEvent } from 'react';
+import { EnrichedMenuDataItem } from '../types.js';
+
+export type MenuItemProps = {
+  item: EnrichedMenuDataItem;
+  level: number;
+  maxDepth?: number;
+  addArrows?: boolean;
+  className?: string;
+  useNavigationControls?: boolean;
+  style?: CSSProperties;
+};
+
+export type HandleKeyDownProps = {
+  event: KeyboardEvent;
+  menuLevel: number;
+};

package/components/componentLibrary/Menu/NavigationMenu/ContentFields.tsx

@@ -0,0 +1,20 @@
+import BaseContentFields from '../ContentFields.js';
+import { NavigationMenuContentFieldProps } from './types.js';
+
+const ContentFields = ({
+  menuLabel,
+  menuName,
+  menuDefault,
+}: NavigationMenuContentFieldProps) => {
+  return (
+    <>
+      <BaseContentFields
+        menuLabel={menuLabel}
+        menuName={menuName}
+        menuDefault={menuDefault}
+      />
+    </>
+  );
+};
+
+export default ContentFields;

package/components/componentLibrary/Menu/NavigationMenu/index.tsx

@@ -0,0 +1,18 @@
+// @ts-expect-error -- ?island not typed
+import NavigationMenuIsland from './islands/NavigationMenuIsland.js?island';
+import { NavigationMenuProps } from './islands/types.js';
+import { Island } from '@hubspot/cms-components';
+import ContentFields from './ContentFields.js';
+
+const NavigationMenuComponent = (props: NavigationMenuProps) => {
+  return <Island module={NavigationMenuIsland} {...props} />;
+};
+
+type NavigationComponentType = typeof NavigationMenuComponent & {
+  ContentFields: typeof ContentFields;
+};
+
+const NavigationMenu = NavigationMenuComponent as NavigationComponentType;
+NavigationMenu.ContentFields = ContentFields;
+
+export default NavigationMenu;

package/components/componentLibrary/Menu/NavigationMenu/islands/NavigationMenuIsland.tsx

@@ -0,0 +1,95 @@
+import MenuItem from '../../MenuItem/index.js';
+import Flex from '../../../Flex/index.js';
+import styles from './index.module.scss';
+import { NavigationMenuProps } from './types.js';
+import cx from '../../../utils/classname.js';
+import { addIdsToMenuItems } from '../../utils/transformMenuData.js';
+import { useMemo, useRef } from 'react';
+
+const NavigationMenuIsland = ({
+  justifyMenu = 'flex-start',
+  className = '',
+  navAriaLabel = 'Navigation',
+  style = {},
+  linkColor,
+  linkColorHover,
+  backgroundColor,
+  backgroundColorHover,
+  submenuLinkColor,
+  submenuLinkColorHover,
+  submenuBackgroundColor,
+  submenuBackgroundColorHover,
+  menuData,
+}: NavigationMenuProps) => {
+  if (!menuData?.pagesTree?.children) return null;
+
+  const menuItems = useMemo(
+    () => addIdsToMenuItems(menuData.pagesTree.children),
+    [menuData]
+  );
+  const level = 1;
+  const navRef = useRef<HTMLElement>(null);
+
+  const handleKeyDown = (event: React.KeyboardEvent) => {
+    if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      navRef.current?.querySelector('li')?.focus();
+    }
+  };
+
+  const cssVariables = {
+    ...(linkColor && { '--hscl-navigationMenu-color': linkColor }),
+    ...(linkColorHover && {
+      '--hscl-navigationMenu-color-hover': linkColorHover,
+    }),
+    ...(backgroundColor && {
+      '--hscl-navigationMenu-backgroundColor': backgroundColor,
+    }),
+    ...(backgroundColorHover && {
+      '--hscl-navigationMenu-backgroundColor-hover': backgroundColorHover,
+    }),
+    ...(submenuLinkColor && {
+      '--hscl-navigationMenu-submenu-color': submenuLinkColor,
+    }),
+    ...(submenuLinkColorHover && {
+      '--hscl-navigationMenu-submenu-color-hover': submenuLinkColorHover,
+    }),
+    ...(submenuBackgroundColor && {
+      '--hscl-navigationMenu-submenu-backgroundColor': submenuBackgroundColor,
+    }),
+    ...(submenuBackgroundColorHover && {
+      '--hscl-navigationMenu-submenu-backgroundColor-hover':
+        submenuBackgroundColorHover,
+    }),
+  };
+
+  return (
+    <nav
+      ref={navRef}
+      className={cx(styles.navigationMenu, className)}
+      style={{ ...cssVariables, ...style }}
+      tabIndex={0}
+      onKeyDown={handleKeyDown}
+      aria-label={navAriaLabel}
+    >
+      <Flex
+        as="ul"
+        direction="row"
+        className={styles.navList}
+        justifyContent={justifyMenu}
+      >
+        {menuItems.map(item => (
+          <MenuItem
+            key={item._id}
+            item={item}
+            level={level}
+            addArrows
+            useNavigationControls
+          />
+        ))}
+      </Flex>
+    </nav>
+  );
+};
+
+export default NavigationMenuIsland;

package/components/componentLibrary/Menu/NavigationMenu/islands/index.module.scss

@@ -0,0 +1,100 @@
+.navigationMenu {
+  width: 100%;
+}
+
+.navList {
+  list-style: none;
+  gap: var(--hscl-navigationMenu-gap);
+  width: 100%;
+
+  // base styles for all list items
+  li {
+    position: relative;
+    max-width: 250px;
+
+    // base styles for all links and spans
+    a, span {
+      text-decoration: none;
+      padding-inline: 20px;
+      padding-block: 10px;
+      color: var(--hscl-navigationMenu-color, currentColor);
+      background-color: var(--hscl-navigationMenu-backgroundColor, transparent);
+
+      &:hover {
+        color: var(--hscl-navigationMenu-color-hover, var(--hscl-navigationMenu-color, currentColor));
+        background-color: var(--hscl-navigationMenu-backgroundColor-hover, var(--hscl-navigationMenu-backgroundColor, transparent));
+      }
+    }
+  }
+
+  // submenu-specific styles
+  ul {
+    li {
+      background-color: var(--hscl-navigationMenu-submenu-backgroundColor, var(--hscl-navigationMenu-backgroundColor, transparent));
+
+      a, span {
+        color: var(--hscl-navigationMenu-submenu-color, var(--hscl-navigationMenu-color, currentColor));
+        background-color: var(--hscl-navigationMenu-submenu-backgroundColor, var(--hscl-navigationMenu-backgroundColor, transparent));
+      }
+
+      &:hover {
+        color: var(--hscl-navigationMenu-submenu-color-hover, var(--hscl-navigationMenu-submenu-color, var(--hscl-navigationMenu-color-hover, var(--hscl-navigationMenu-color, currentColor))));
+        background-color: var(--hscl-navigationMenu-submenu-backgroundColor-hover, var(--hscl-navigationMenu-submenu-backgroundColor, var(--hscl-navigationMenu-backgroundColor-hover, var(--hscl-navigationMenu-backgroundColor, transparent))));
+
+        > a, > span {
+          color: var(--hscl-navigationMenu-submenu-color-hover, var(--hscl-navigationMenu-submenu-color, var(--hscl-navigationMenu-color-hover, var(--hscl-navigationMenu-color, currentColor))));
+          background-color: var(--hscl-navigationMenu-submenu-backgroundColor-hover, var(--hscl-navigationMenu-submenu-backgroundColor, var(--hscl-navigationMenu-backgroundColor-hover, var(--hscl-navigationMenu-backgroundColor, transparent))));
+        }
+      }
+    }
+  }
+
+  // Override padding for top level items
+  > li {
+    > a, > span {
+      padding-inline: 10px;
+    }
+  }
+
+  // base styles for all submenu lists
+  ul {
+    list-style: none;
+    display: none;
+    margin-inline: 0;
+    padding-inline: 0;
+  }
+
+  // Shared styles for all visible submenus
+  li:hover > ul,
+  li:not([data-submenu-open]):focus-within > ul,
+  li[data-submenu-open="true"] > ul,
+  ul:has(> li:focus) {
+    display: block;
+    position: absolute;
+    min-width: max-content;
+    background-color: #fff;
+    padding: 0;
+
+    svg {
+      transform: rotate(-90deg);
+    }
+  }
+
+  // Controlled mode: explicitly hide submenu when state is closed (but allow hover to override)
+  li[data-submenu-open="false"]:not(:hover) > ul {
+    display: none;
+  }
+
+  // Position top-level submenus below parent
+  > li > ul {
+    top: 100%;
+    left: 0;
+  }
+
+  // Position nested submenus (level 2+) to the right
+  ul ul {
+    top: 0;
+    left: 100%;
+  }
+}
+