@hubspot/cms-component-library 0.1.0 → 0.2.0

package/components/componentLibrary/Menu/NavigationMenu/islands/types.ts

@@ -0,0 +1,19 @@
+import { FlexJustifyContent } from '../../../Flex/types.js';
+import { CSSVariables } from '../../../utils/types.js';
+import { SiteMenu } from '@hubspot/cms-components';
+
+export type NavigationMenuProps = {
+  navAriaLabel?: string;
+  justifyMenu?: FlexJustifyContent;
+  className?: string;
+  style?: CSSVariables;
+  linkColor?: string;
+  linkColorHover?: string;
+  backgroundColor?: string;
+  backgroundColorHover?: string;
+  submenuLinkColor?: string;
+  submenuLinkColorHover?: string;
+  submenuBackgroundColor?: string;
+  submenuBackgroundColorHover?: string;
+  menuData: SiteMenu;
+};

package/components/componentLibrary/Menu/NavigationMenu/llm.txt

@@ -0,0 +1,197 @@
+# NavigationMenu Component
+
+A horizontal navigation menu component that renders a top-level menu bar with dropdown submenus, keyboard navigation support, and flexible styling options.
+
+## Import path
+```tsx
+import NavigationMenu from '@hubspot/cms-component-library/NavigationMenu';
+```
+
+## Purpose
+
+The NavigationMenu component provides a horizontal navigation menu for HubSpot CMS projects. It automatically integrates with HubSpot's site menu system, supporting multi-level dropdown menus with keyboard navigation, customizable colors for links and backgrounds, and flexible horizontal alignment options.
+
+## Component Structure
+
+```
+NavigationMenu/
+├── index.tsx                      # Main component wrapper (Island integration)
+├── ContentFields.tsx              # HubSpot field definitions for menu selection
+├── islands/
+│   ├── NavigationMenuIsland.tsx  # Island component with rendering logic
+│   ├── types.ts                  # TypeScript type definitions
+│   └── index.module.scss         # CSS module with design tokens
+└── stories/
+    ├── NavigationMenu.stories.tsx # Storybook examples
+    └── NavigationMenuDecorator.tsx # Storybook decorator
+```
+
+## Components
+
+### NavigationMenu (Main Component)
+
+**Purpose:** Renders a horizontal navigation menu from HubSpot site menu data with dropdown submenus.
+
+**Props:**
+```tsx
+{
+  menuData: SiteMenu;                    // Menu data from useMenu hook (required)
+  justifyMenu?: FlexJustifyContent;      // Horizontal alignment (default: 'flex-start')
+  navAriaLabel?: string;                 // ARIA label for navigation (default: 'Navigation')
+  linkColor?: string;                    // Top-level link text color
+  linkColorHover?: string;               // Top-level link hover text color
+  backgroundColor?: string;              // Top-level link background color
+  backgroundColorHover?: string;         // Top-level link hover background color
+  submenuLinkColor?: string;             // Submenu link text color
+  submenuLinkColorHover?: string;        // Submenu link hover text color
+  submenuBackgroundColor?: string;       // Submenu link background color
+  submenuBackgroundColorHover?: string;  // Submenu link hover background color
+  className?: string;                    // Additional CSS classes
+  style?: React.CSSProperties;           // Inline styles with CSS variables
+}
+```
+
+## Consuming the Component with useMenu Hook
+
+The NavigationMenu component requires menu data from HubSpot's `useMenu` hook. This hook fetches the site menu structure based on a menu ID defined in your module fields.
+
+### Basic Module Implementation
+
+```tsx
+import { ModuleMeta } from '../types/modules.js';
+import NavigationMenu from '@hubspot/cms-component-library/NavigationMenu';
+import { useMenu, fieldPath } from '@hubspot/cms-components';
+
+export const Component = () => {
+  // Fetch menu data using the useMenu hook
+  // fieldPath('menu') references the menu field defined in fields.tsx
+  const menuData = useMenu(fieldPath('menu'));
+
+  return (
+    <NavigationMenu
+      menuData={menuData}
+      justifyMenu="flex-start"
+      navAriaLabel="Main navigation"
+    />
+  );
+};
+
+export { fields } from './fields.js';
+
+export const meta: ModuleMeta = {
+  label: 'Main Navigation Menu',
+  content_types: [],
+  icon: '',
+  categories: ['navigation'],
+};
+```
+
+### Module Fields Definition
+
+```tsx
+import { ModuleFields } from '@hubspot/cms-components/fields';
+import NavigationMenu from '@hubspot/cms-component-library/NavigationMenu';
+
+export const fields = (
+  <ModuleFields>
+    <NavigationMenu.ContentFields />
+  </ModuleFields>
+);
+```
+
+**What this does:**
+1. `NavigationMenu.ContentFields` creates a HubSpot MenuField in your module
+2. This field allows content editors to select which site menu to display
+3. The `useMenu(fieldPath('menu'))` hook fetches the selected menu's data
+4. The menu data is passed to the NavigationMenu component via the `menuData` prop
+
+## Usage Examples
+
+### Basic Navigation Menu
+
+```tsx
+import NavigationMenu from '@hubspot/cms-component-library/NavigationMenu';
+import { useMenu, fieldPath } from '@hubspot/cms-components';
+
+export const Component = () => {
+  const menuData = useMenu(fieldPath('menu'));
+
+  return <NavigationMenu menuData={menuData} />;
+};
+```
+
+
+## HubSpot CMS Integration
+
+### Field Definitions
+
+The NavigationMenu component provides field definitions for menu selection in HubSpot CMS modules.
+
+#### ContentFields
+
+Configurable props for customizing field labels, names, and defaults:
+
+```tsx
+<NavigationMenu.ContentFields
+  menuLabel="Menu"
+  menuName="menu"
+  menuDefault="default"
+/>
+```
+
+**Fields:**
+- `menu`: MenuField for selecting which site menu to display (default: 'default')
+
+## Styling
+
+### CSS Variables
+
+The NavigationMenu component uses CSS variables for theming and customization:
+
+**Base Menu Styles:**
+- `--hscl-navigationMenu-gap`: Space between top-level menu items
+- `--hscl-navigationMenu-color`: Link text color (default: currentColor)
+- `--hscl-navigationMenu-backgroundColor`: Link background color (default: transparent)
+- `--hscl-navigationMenu-color-hover`: Link hover text color
+- `--hscl-navigationMenu-backgroundColor-hover`: Link hover background color
+
+**Submenu-Specific Styles:**
+- `--hscl-navigationMenu-submenu-color`: Submenu link text color
+- `--hscl-navigationMenu-submenu-backgroundColor`: Submenu link background color
+- `--hscl-navigationMenu-submenu-color-hover`: Submenu link hover text color
+- `--hscl-navigationMenu-submenu-backgroundColor-hover`: Submenu link hover background color
+
+
+## Accessibility
+
+The NavigationMenu component follows accessibility best practices:
+
+- **Semantic HTML**: Renders as a `<nav>` element with an unordered list (`<ul>`)
+- **ARIA Labels**: Customizable `aria-label` via the `navAriaLabel` prop
+- **ARIA Roles**: List items have `role="menuitem"` for proper screen reader support
+- **Keyboard Navigation**: Full keyboard support with arrow keys
+  - `ArrowDown`: Opens submenu or moves to next item
+  - `ArrowUp`: Closes submenu or moves to previous item
+  - `ArrowRight`: Moves to next top-level item or opens nested submenu
+  - `ArrowLeft`: Moves to previous top-level item or returns to parent
+  - `Enter`/`Space`: Activates link
+  - `Escape`: Closes submenu
+  - `Home`/`End`: Jump to first/last item
+- **Focus Management**: Keyboard focus properly managed across menu levels
+- **External Links**: Automatically adds `target="_blank"` and `rel="noopener noreferrer"` for external links
+
+## Best Practices
+
+- **Always use useMenu hook**: The NavigationMenu component requires menu data from the `useMenu` hook—never pass hardcoded menu structures
+- **Consistent alignment**: Use the same `justifyMenu` value across navigation instances for visual consistency
+- **ARIA labels**: Provide descriptive `navAriaLabel` values (e.g., "Main navigation", "Footer navigation")
+- **Color contrast**: Ensure sufficient contrast between link colors and backgrounds (WCAG AA minimum)
+- **Hover states**: Always define hover colors for better visual feedback
+- **Submenu styling**: Use distinct colors for dropdown menus to differentiate them from top-level items
+- **Override CSS variables**: Customize appearance using CSS variables rather than overriding class styles
+- **Null checking**: Always check if menuData exists before rendering, as useMenu can return null
+
+## Related Components
+
+- **VerticalMenu**: Vertical navigation menu component for sidebar navigation
+- **MenuItem**: Used internally to render individual menu items with support for nested children and keyboard navigation

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

@@ -0,0 +1,286 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import NavigationMenu from '../index.js';
+import { NavigationMenuProps } from '../islands/types.js';
+import { withNavigationMenuStyles } from './NavigationMenuDecorator.js';
+import { SBContainer, SBFocusWrapper } from '@sb-utils';
+import { dummyMenuData } from '../../_dummyMenuData.js';
+
+const meta: Meta<NavigationMenuProps> = {
+  title: 'Component Library/Menu/Navigation Menu',
+  component: NavigationMenu,
+  parameters: {
+    layout: 'fullwidth',
+    docs: {
+      description: {
+        component:
+          'The NavigationMenu component creates a horizontal navigation menu with dropdown submenus. It supports keyboard navigation and is typically used in website headers.',
+      },
+    },
+  },
+  decorators: [withNavigationMenuStyles],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <SBContainer
+      addBackground
+      style={{ overflow: 'visible', minHeight: '300px' }}
+    >
+      <NavigationMenu navAriaLabel="Main Navigation" menuData={dummyMenuData} />
+    </SBContainer>
+  ),
+};
+
+export const JustifyContent: Story = {
+  name: 'Justify Content Options',
+  render: () => (
+    <SBContainer flex direction="column" gap="extralarge">
+      <SBContainer
+        addBackground
+        style={{ overflow: 'visible', minHeight: '250px' }}
+      >
+        <h4>Left Aligned (Default)</h4>
+        <NavigationMenu justifyMenu="flex-start" menuData={dummyMenuData} />
+      </SBContainer>
+
+      <SBContainer
+        addBackground
+        style={{ overflow: 'visible', minHeight: '250px' }}
+      >
+        <h4>Center Aligned</h4>
+        <NavigationMenu justifyMenu="center" menuData={dummyMenuData} />
+      </SBContainer>
+
+      <SBContainer
+        addBackground
+        style={{ overflow: 'visible', minHeight: '250px' }}
+      >
+        <h4>Right Aligned</h4>
+        <NavigationMenu justifyMenu="flex-end" menuData={dummyMenuData} />
+      </SBContainer>
+
+      <SBContainer
+        addBackground
+        style={{ overflow: 'visible', minHeight: '250px' }}
+      >
+        <h4>Space Between</h4>
+        <NavigationMenu justifyMenu="space-between" menuData={dummyMenuData} />
+      </SBContainer>
+
+      <SBContainer
+        addBackground
+        style={{ overflow: 'visible', minHeight: '250px' }}
+      >
+        <h4>Space Around</h4>
+        <NavigationMenu justifyMenu="space-around" menuData={dummyMenuData} />
+      </SBContainer>
+    </SBContainer>
+  ),
+};
+
+export const ColorCustomization: Story = {
+  name: 'Color Customization',
+  render: () => (
+    <SBContainer flex direction="column" gap="extralarge">
+      <SBContainer
+        addBackground
+        style={{ overflow: 'visible', minHeight: '250px' }}
+      >
+        <h4>Default Colors</h4>
+        <NavigationMenu menuData={dummyMenuData} />
+      </SBContainer>
+
+      <SBContainer
+        addBackground
+        style={{ overflow: 'visible', minHeight: '250px' }}
+      >
+        <h4>Custom Link Colors</h4>
+        <NavigationMenu
+          linkColor="#2d3e50"
+          linkColorHover="#ff7a59"
+          menuData={dummyMenuData}
+        />
+      </SBContainer>
+
+      <SBContainer
+        addBackground
+        style={{ overflow: 'visible', minHeight: '250px' }}
+      >
+        <h4>With Background Colors</h4>
+        <NavigationMenu
+          linkColor="#ffffff"
+          linkColorHover="#ffffff"
+          backgroundColor="#0066cc"
+          backgroundColorHover="#0052a3"
+          menuData={dummyMenuData}
+        />
+      </SBContainer>
+
+      <SBContainer
+        addBackground
+        style={{ overflow: 'visible', minHeight: '250px' }}
+      >
+        <h4>Custom Submenu Colors</h4>
+        <NavigationMenu
+          linkColor="#1a1a1a"
+          linkColorHover="#e91e63"
+          backgroundColor="#fff3e0"
+          backgroundColorHover="#ffe0b2"
+          submenuLinkColor="#4a148c"
+          submenuLinkColorHover="#00e676"
+          submenuBackgroundColor="#f3e5f5"
+          submenuBackgroundColorHover="#e1bee7"
+          menuData={dummyMenuData}
+        />
+      </SBContainer>
+
+      <SBContainer
+        style={{
+          backgroundColor: '#1a1a1a',
+          padding: '20px',
+          minHeight: '300px',
+          overflow: 'visible',
+        }}
+      >
+        <h4 style={{ color: '#ffffff', marginTop: 0 }}>Dark Theme</h4>
+        <NavigationMenu
+          linkColor="#e0e0e0"
+          linkColorHover="#ffffff"
+          backgroundColor="#2d2d2d"
+          backgroundColorHover="#3d3d3d"
+          submenuLinkColor="#e0e0e0"
+          submenuLinkColorHover="#ffffff"
+          submenuBackgroundColor="#2d2d2d"
+          submenuBackgroundColorHover="#3d3d3d"
+          menuData={dummyMenuData}
+        />
+      </SBContainer>
+    </SBContainer>
+  ),
+};
+
+export const FocusState: Story = {
+  name: 'Focus State',
+  render: () => (
+    <SBContainer flex direction="column" gap="large">
+      <SBContainer
+        addBackground
+        style={{ overflow: 'visible', minHeight: '250px' }}
+      >
+        <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>
+          <NavigationMenu
+            navAriaLabel="Focused Navigation"
+            menuData={dummyMenuData}
+          />
+        </SBFocusWrapper>
+      </SBContainer>
+    </SBContainer>
+  ),
+};
+
+export const AccessibilityFeatures: Story = {
+  name: 'Accessibility Features',
+  render: () => (
+    <SBContainer flex direction="column" gap="large">
+      <SBContainer
+        addBackground
+        style={{ overflow: 'visible', minHeight: '250px' }}
+      >
+        <h4>ARIA Label</h4>
+        <p>
+          The navigation element includes an aria-label for screen readers
+          (inspect the element to see it).
+        </p>
+        <NavigationMenu
+          navAriaLabel="Main Site Navigation"
+          menuData={dummyMenuData}
+        />
+      </SBContainer>
+
+      <SBContainer
+        addBackground
+        style={{ overflow: 'visible', minHeight: '250px' }}
+      >
+        <h4>Custom ARIA Label</h4>
+        <p>
+          You can customize the ARIA label to describe the navigation purpose.
+        </p>
+        <NavigationMenu
+          navAriaLabel="Footer Navigation"
+          menuData={dummyMenuData}
+        />
+      </SBContainer>
+
+      <SBContainer
+        addBackground
+        style={{ overflow: 'visible', minHeight: '250px' }}
+      >
+        <h4>Keyboard Accessible</h4>
+        <p>
+          All menu items and submenus are fully keyboard accessible using Tab,
+          Enter, and Arrow keys.
+        </p>
+        <NavigationMenu
+          navAriaLabel="Accessible Navigation Demo"
+          menuData={dummyMenuData}
+        />
+      </SBContainer>
+    </SBContainer>
+  ),
+};
+
+export const RealWorldExample: Story = {
+  name: 'In Context',
+  render: () => (
+    <SBContainer
+      style={{
+        backgroundColor: '#ffffff',
+        borderBottom: '1px solid #cbd6e2',
+        padding: '0',
+        minHeight: '350px',
+        overflow: 'visible',
+      }}
+    >
+      <SBContainer
+        flex
+        direction="row"
+        alignItems="center"
+        justifyContent="space-between"
+        style={{
+          maxWidth: '1200px',
+          margin: '0 auto',
+          padding: '0 50px',
+        }}
+      >
+        <SBContainer
+          style={{
+            fontSize: '24px',
+            fontWeight: 'bold',
+            color: '#33475b',
+          }}
+        >
+          Acme Corp
+        </SBContainer>
+        <NavigationMenu
+          justifyMenu="flex-end"
+          linkColor="#33475b"
+          linkColorHover="#0066cc"
+          submenuLinkColor="#516f90"
+          submenuLinkColorHover="#0066cc"
+          submenuBackgroundColor="#ffffff"
+          submenuBackgroundColorHover="#f5f8fa"
+          menuData={dummyMenuData}
+        />
+      </SBContainer>
+    </SBContainer>
+  ),
+};

package/components/componentLibrary/Menu/NavigationMenu/stories/NavigationMenuDecorator.module.scss

@@ -0,0 +1,15 @@
+.navigationMenuContainer {
+  --hscl-navigationMenu-gap: 0px;
+  --hscl-navigationMenu-color: #33475b;
+  --hscl-navigationMenu-color-hover: #0066cc;
+  --hscl-navigationMenu-backgroundColor: transparent;
+  --hscl-navigationMenu-backgroundColor-hover: #f5f8fa;
+  --hscl-navigationMenu-submenu-color: #33475b;
+  --hscl-navigationMenu-submenu-color-hover: #0066cc;
+  --hscl-navigationMenu-submenu-backgroundColor: #ffffff;
+  --hscl-navigationMenu-submenu-backgroundColor-hover: #f5f8fa;
+
+  nav li {
+    margin-bottom: 0;
+  }
+}

package/components/componentLibrary/Menu/NavigationMenu/stories/NavigationMenuDecorator.tsx

@@ -0,0 +1,12 @@
+import type { Decorator } from '@storybook/react';
+import styles from './NavigationMenuDecorator.module.scss';
+
+/**
+ * Shared decorator for NavigationMenu stories that applies default CSS variables
+ * and scoped styles to prevent pollution across other Storybook stories.
+ */
+export const withNavigationMenuStyles: Decorator = Story => (
+  <div className={styles.navigationMenuContainer}>
+    <Story />
+  </div>
+);

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

@@ -0,0 +1,3 @@
+import { ContentFieldsProps } from '../types.js';
+
+export type NavigationMenuContentFieldProps = ContentFieldsProps;

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

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

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

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

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

@@ -0,0 +1,53 @@
+.verticalMenu {
+  width: var(--hscl-verticalMenu-width, 100%);
+}
+
+.menuList {
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: var(--hscl-verticalMenu-gap, 0);
+  width: 100%;
+  margin: 0;
+  padding: 0;
+
+  // base styles for all list items
+  li {
+    position: relative;
+
+    // base styles for all links and spans
+    a, span {
+      display: block;
+      text-decoration: none;
+      padding-inline: var(--hscl-verticalMenu-paddingInline, 10px);
+      padding-block: var(--hscl-verticalMenu-paddingBlock, 8px);
+      color: var(--hscl-verticalMenu-color, currentColor);
+      background-color: var(--hscl-verticalMenu-backgroundColor, transparent);
+
+      &:hover {
+        color: var(--hscl-verticalMenu-color-hover, var(--hscl-verticalMenu-color, currentColor));
+        background-color: var(--hscl-verticalMenu-backgroundColor-hover, var(--hscl-verticalMenu-backgroundColor, transparent));
+      }
+    }
+  }
+
+  // base styles for all submenu lists
+  ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+
+    li {
+      a, span {
+        color: var(--hscl-verticalMenu-submenu-color, var(--hscl-verticalMenu-color, currentColor));
+        background-color: var(--hscl-verticalMenu-submenu-backgroundColor, var(--hscl-verticalMenu-backgroundColor, transparent));
+        padding-inline-start: calc(var(--hscl-verticalMenu-paddingInline, 10px) + (var(--hscl-menuItem-level, 1) - 1) * var(--hscl-verticalMenu-paddingInlineStart, 0px));
+
+        &:hover {
+          color: var(--hscl-verticalMenu-submenu-color-hover, var(--hscl-verticalMenu-submenu-color, var(--hscl-verticalMenu-color-hover, var(--hscl-verticalMenu-color, currentColor))));
+          background-color: var(--hscl-verticalMenu-submenu-backgroundColor-hover, var(--hscl-verticalMenu-submenu-backgroundColor, var(--hscl-verticalMenu-backgroundColor-hover, var(--hscl-verticalMenu-backgroundColor, transparent))));
+        }
+      }
+    }
+  }
+}