@hubspot/cms-component-library 0.1.0 → 0.3.0

package/components/componentLibrary/Menu/VerticalMenu/islands/verticalMenuIsland.tsx

@@ -0,0 +1,78 @@
+import { useMemo } from 'react';
+import MenuItem from '../../MenuItem/index.js';
+import { VerticalMenuProps } from '../types.js';
+import { addIdsToMenuItems } from '../../utils/transformMenuData.js';
+import styles from './index.module.scss';
+import cx from '../../../utils/classname.js';
+const VerticalMenu = ({
+  maxDepth,
+  className = '',
+  style = {},
+  linkColor,
+  linkColorHover,
+  backgroundColor,
+  backgroundColorHover,
+  submenuLinkColor,
+  submenuLinkColorHover,
+  submenuBackgroundColor,
+  submenuBackgroundColorHover,
+  indentation,
+  menuData,
+}: VerticalMenuProps) => {
+  if (!menuData?.pagesTree?.children) return null;
+
+  const menuItems = useMemo(
+    () => addIdsToMenuItems(menuData.pagesTree.children),
+    [menuData]
+  );
+  const level = 1;
+
+  const cssVariables = {
+    ...(linkColor && { '--hscl-verticalMenu-color': linkColor }),
+    ...(linkColorHover && {
+      '--hscl-verticalMenu-color-hover': linkColorHover,
+    }),
+    ...(backgroundColor && {
+      '--hscl-verticalMenu-backgroundColor': backgroundColor,
+    }),
+    ...(backgroundColorHover && {
+      '--hscl-verticalMenu-backgroundColor-hover': backgroundColorHover,
+    }),
+    ...(submenuLinkColor && {
+      '--hscl-verticalMenu-submenu-color': submenuLinkColor,
+    }),
+    ...(submenuLinkColorHover && {
+      '--hscl-verticalMenu-submenu-color-hover': submenuLinkColorHover,
+    }),
+    ...(submenuBackgroundColor && {
+      '--hscl-verticalMenu-submenu-backgroundColor': submenuBackgroundColor,
+    }),
+    ...(submenuBackgroundColorHover && {
+      '--hscl-verticalMenu-submenu-backgroundColor-hover':
+        submenuBackgroundColorHover,
+    }),
+    ...(indentation && {
+      '--hscl-verticalMenu-paddingInlineStart': indentation,
+    }),
+  };
+
+  return (
+    <nav
+      className={cx(styles.verticalMenu, className)}
+      style={{ ...cssVariables, ...style }}
+    >
+      <ul className={styles.menuList}>
+        {menuItems.map(item => (
+          <MenuItem
+            key={item._id}
+            item={item}
+            level={level}
+            maxDepth={maxDepth}
+          />
+        ))}
+      </ul>
+    </nav>
+  );
+};
+
+export default VerticalMenu;

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

@@ -0,0 +1,177 @@
+# VerticalMenu Component
+
+A vertical navigation menu component that renders a hierarchical list of links with support for nested submenus, customizable depth, and flexible styling options.
+
+## Import path
+```tsx
+import VerticalMenu from '@hubspot/cms-component-library/VerticalMenu';
+```
+
+## Purpose
+
+The VerticalMenu component provides a consistent way to render vertical navigation menus in HubSpot CMS projects. It automatically integrates with HubSpot's site menu system, supporting multi-level navigation with configurable maximum depth, customizable colors for links and backgrounds, and adjustable indentation for submenu items.
+
+## Component Structure
+
+```
+VerticalMenu/
+├── index.tsx                      # Main component wrapper (Island integration)
+├── types.ts                       # TypeScript type definitions
+├── ContentFields.tsx              # HubSpot field definitions for menu selection
+├── islands/
+│   ├── verticalMenuIsland.tsx    # Island component with rendering logic
+│   └── index.module.scss         # CSS module with design tokens
+└── stories/
+    ├── VerticalMenu.stories.tsx  # Storybook examples
+    └── VerticalMenuDecorator.tsx # Storybook decorator
+```
+
+## Components
+
+### VerticalMenu (Main Component)
+
+**Purpose:** Renders a vertical navigation menu from HubSpot site menu data with support for nested submenus.
+
+**Props:**
+```tsx
+{
+  menuData: SiteMenu;                    // Menu data from useMenu hook (required)
+  maxDepth?: number;                     // Maximum nesting depth (default: unlimited)
+  indentation?: string;                  // Submenu indentation (default: '0px')
+  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 VerticalMenu 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 VerticalMenu from '@hubspot/cms-component-library/VerticalMenu';
+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 (
+    <VerticalMenu
+      menuData={menuData}
+      maxDepth={2}
+      indentation="20px"
+    />
+  );
+};
+
+export { fields } from './fields.js';
+
+export const meta: ModuleMeta = {
+  label: 'Vertical Navigation Menu',
+  content_types: [],
+  icon: '',
+  categories: ['navigation'],
+};
+```
+
+### Module Fields Definition
+
+```tsx
+import { ModuleFields } from '@hubspot/cms-components/fields';
+import VerticalMenu from '@hubspot/cms-component-library/VerticalMenu';
+
+export const fields = (
+  <ModuleFields>
+    <VerticalMenu.ContentFields />
+  </ModuleFields>
+);
+```
+
+**What this does:**
+1. `VerticalMenu.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 VerticalMenu component via the `menuData` prop
+
+## HubSpot CMS Integration
+
+### Field Definitions
+
+The VerticalMenu component provides field definitions for menu selection in HubSpot CMS modules.
+
+#### ContentFields
+
+Configurable props for customizing field labels, names, and defaults:
+
+```tsx
+<VerticalMenu.ContentFields
+  menuLabel="Menu"
+  menuName="menu"
+  menuDefault="default"
+/>
+```
+
+**Fields:**
+- `menu`: MenuField for selecting which site menu to display (default: 'default')
+
+## Styling
+
+### CSS Variables
+
+The VerticalMenu component uses CSS variables for theming and customization:
+
+**Base Menu Styles:**
+- `--hscl-verticalMenu-width`: Menu container width (default: 100%)
+- `--hscl-verticalMenu-gap`: Space between menu items (default: 0)
+- `--hscl-verticalMenu-paddingInline`: Horizontal padding for links (default: 10px)
+- `--hscl-verticalMenu-paddingBlock`: Vertical padding for links (default: 8px)
+- `--hscl-verticalMenu-color`: Link text color (default: currentColor)
+- `--hscl-verticalMenu-backgroundColor`: Link background color (default: transparent)
+- `--hscl-verticalMenu-color-hover`: Link hover text color
+- `--hscl-verticalMenu-backgroundColor-hover`: Link hover background color
+
+**Submenu-Specific Styles:**
+- `--hscl-verticalMenu-paddingInlineStart`: Indentation for submenu items (default: 0px)
+- `--hscl-verticalMenu-submenu-color`: Submenu link text color
+- `--hscl-verticalMenu-submenu-backgroundColor`: Submenu link background color
+- `--hscl-verticalMenu-submenu-color-hover`: Submenu link hover text color
+- `--hscl-verticalMenu-submenu-backgroundColor-hover`: Submenu link hover background color
+
+
+## Accessibility
+
+The VerticalMenu component follows accessibility best practices:
+
+- **Semantic HTML**: Renders as a `<nav>` element with nested unordered lists (`<ul>`)
+- **ARIA Roles**: List items have `role="menuitem"` for proper screen reader support
+- **Keyboard Navigation**: Full keyboard support provided by the MenuItem component
+- **Link Semantics**: Uses proper `<a>` elements for links with `href` attributes
+- **External Links**: Automatically adds `target="_blank"` and `rel="noopener noreferrer"` for external links
+- **Focus Management**: Native focus styles preserved for keyboard users
+
+## Best Practices
+
+- **Always use useMenu hook**: The VerticalMenu component requires menu data from the `useMenu` hook—never pass hardcoded menu structures
+- **Control depth wisely**: Use `maxDepth` to limit nesting levels for better UX (1-3 levels recommended)
+- **Consistent indentation**: Use consistent indentation values across your site (typically 16px, 20px, or 24px)
+- **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 submenu items to create visual hierarchy
+
+
+## Related Components
+
+- **NavigationMenu**: Horizontal navigation menu component for top-level navigation bars
+- **MenuItem**: Used internally to render individual menu items with support for nested children

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

@@ -0,0 +1,242 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import VerticalMenu from '../index.js';
+import { VerticalMenuProps } from '../types.js';
+import { withVerticalMenuStyles } from './VerticalMenuDecorator.js';
+import { SBContainer, SBFocusWrapper } from '@sb-utils';
+import { dummyMenuData } from '../../_dummyMenuData.js';
+
+const meta: Meta<VerticalMenuProps> = {
+  title: 'Component Library/Menu/Vertical Menu',
+  component: VerticalMenu,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'The VerticalMenu component creates a vertical navigation menu with collapsible nested submenus. It supports depth control and custom indentation, making it ideal for sidebars and secondary navigation.',
+      },
+    },
+  },
+  decorators: [withVerticalMenuStyles],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <SBContainer addBackground width="300px">
+      <VerticalMenu menuData={dummyMenuData} />
+    </SBContainer>
+  ),
+};
+
+export const MaxDepthControl: Story = {
+  name: 'Max Depth Control',
+  render: () => (
+    <SBContainer flex direction="column" gap="extralarge">
+      <SBContainer addBackground width="300px">
+        <h4>No Depth Limit (Default)</h4>
+        <p>Shows all nested menu levels</p>
+        <VerticalMenu menuData={dummyMenuData} />
+      </SBContainer>
+
+      <SBContainer addBackground width="300px">
+        <h4>Max Depth: 1</h4>
+        <p>Only shows top-level items</p>
+        <VerticalMenu maxDepth={1} menuData={dummyMenuData} />
+      </SBContainer>
+
+      <SBContainer addBackground width="300px">
+        <h4>Max Depth: 2</h4>
+        <p>Shows up to 2 levels deep</p>
+        <VerticalMenu maxDepth={2} menuData={dummyMenuData} />
+      </SBContainer>
+
+      <SBContainer addBackground width="300px">
+        <h4>Max Depth: 3</h4>
+        <p>Shows up to 3 levels deep</p>
+        <VerticalMenu maxDepth={3} menuData={dummyMenuData} />
+      </SBContainer>
+    </SBContainer>
+  ),
+};
+
+export const IndentationOptions: Story = {
+  name: 'Indentation Options',
+  render: () => (
+    <SBContainer flex direction="column" gap="extralarge">
+      <SBContainer addBackground width="300px">
+        <h4>Default Indentation (20px)</h4>
+        <VerticalMenu menuData={dummyMenuData} />
+      </SBContainer>
+
+      <SBContainer addBackground width="300px">
+        <h4>No Indentation</h4>
+        <VerticalMenu indentation="0px" menuData={dummyMenuData} />
+      </SBContainer>
+
+      <SBContainer addBackground width="300px">
+        <h4>Small Indentation (10px)</h4>
+        <VerticalMenu indentation="10px" menuData={dummyMenuData} />
+      </SBContainer>
+
+      <SBContainer addBackground width="300px">
+        <h4>Large Indentation (40px)</h4>
+        <VerticalMenu indentation="40px" menuData={dummyMenuData} />
+      </SBContainer>
+    </SBContainer>
+  ),
+};
+
+export const ColorCustomization: Story = {
+  name: 'Color Customization',
+  render: () => (
+    <SBContainer flex direction="column" gap="extralarge">
+      <SBContainer addBackground width="300px">
+        <h4>Default Colors</h4>
+        <VerticalMenu menuData={dummyMenuData} />
+      </SBContainer>
+
+      <SBContainer addBackground width="300px">
+        <h4>Bold Link Colors</h4>
+        <VerticalMenu
+          linkColor="#1a1a1a"
+          linkColorHover="#ff5722"
+          backgroundColor="#fff3e0"
+          backgroundColorHover="#ffe0b2"
+          menuData={dummyMenuData}
+        />
+      </SBContainer>
+
+      <SBContainer addBackground width="300px">
+        <h4>Vibrant Theme</h4>
+        <VerticalMenu
+          linkColor="#ffffff"
+          linkColorHover="#ffeb3b"
+          backgroundColor="#1976d2"
+          backgroundColorHover="#1565c0"
+          submenuLinkColor="#e3f2fd"
+          submenuLinkColorHover="#ffeb3b"
+          submenuBackgroundColor="#0d47a1"
+          submenuBackgroundColorHover="#01579b"
+          indentation="30px"
+          menuData={dummyMenuData}
+        />
+      </SBContainer>
+
+      <SBContainer addBackground width="300px">
+        <h4>High Contrast</h4>
+        <VerticalMenu
+          linkColor="#000000"
+          linkColorHover="#d32f2f"
+          backgroundColor="#ffeb3b"
+          backgroundColorHover="#fdd835"
+          submenuLinkColor="#1a1a1a"
+          submenuLinkColorHover="#c62828"
+          submenuBackgroundColor="#fff59d"
+          submenuBackgroundColorHover="#fff176"
+          indentation="30px"
+          menuData={dummyMenuData}
+        />
+      </SBContainer>
+
+      <SBContainer
+        flex
+        justifyContent="center"
+        style={{
+          backgroundColor: '#0a0a0a',
+          padding: '20px',
+          minHeight: '400px',
+        }}
+      >
+        <SBContainer width="300px">
+          <h4 style={{ color: '#ffffff', marginTop: 0 }}>Dark Theme</h4>
+          <VerticalMenu
+            linkColor="#e0e0e0"
+            linkColorHover="#00e676"
+            backgroundColor="#212121"
+            backgroundColorHover="#424242"
+            submenuLinkColor="#9e9e9e"
+            submenuLinkColorHover="#69f0ae"
+            submenuBackgroundColor="#1a1a1a"
+            submenuBackgroundColorHover="#2c2c2c"
+            indentation="30px"
+            menuData={dummyMenuData}
+          />
+        </SBContainer>
+      </SBContainer>
+    </SBContainer>
+  ),
+};
+
+export const FocusState: Story = {
+  name: 'Focus State',
+  render: () => (
+    <SBContainer flex direction="column" gap="large">
+      <SBContainer addBackground width="300px">
+        <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>
+          <VerticalMenu menuData={dummyMenuData} />
+        </SBFocusWrapper>
+      </SBContainer>
+    </SBContainer>
+  ),
+};
+
+export const SidebarExample: Story = {
+  name: 'In Context',
+  render: () => (
+    <SBContainer
+      flex
+      direction="row"
+      style={{
+        minHeight: '600px',
+        border: '1px solid #cbd6e2',
+      }}
+    >
+      <SBContainer
+        width="280px"
+        style={{
+          backgroundColor: '#f5f8fa',
+          borderRight: '1px solid #cbd6e2',
+          padding: '20px 0',
+        }}
+      >
+        <VerticalMenu
+          linkColor="#33475b"
+          linkColorHover="#0066cc"
+          backgroundColor="transparent"
+          backgroundColorHover="#ffffff"
+          submenuLinkColor="#516f90"
+          submenuLinkColorHover="#0066cc"
+          submenuBackgroundColor="transparent"
+          submenuBackgroundColorHover="#eaf0f6"
+          indentation="24px"
+          menuData={dummyMenuData}
+        />
+      </SBContainer>
+      <SBContainer
+        style={{
+          flex: 1,
+          padding: '40px',
+          backgroundColor: '#ffffff',
+        }}
+      >
+        <h2>Main Content Area</h2>
+        <p>
+          This demonstrates how the vertical menu works in a sidebar layout.
+        </p>
+        <p>
+          The sidebar navigation provides easy access to different sections
+          while the main content area remains spacious.
+        </p>
+      </SBContainer>
+    </SBContainer>
+  ),
+};

package/components/componentLibrary/Menu/VerticalMenu/stories/VerticalMenuDecorator.module.scss

@@ -0,0 +1,19 @@
+.verticalMenuContainer {
+  --hscl-verticalMenu-width: 100%;
+  --hscl-verticalMenu-gap: 0px;
+  --hscl-verticalMenu-paddingInline: 10px;
+  --hscl-verticalMenu-paddingBlock: 8px;
+  --hscl-verticalMenu-color: #33475b;
+  --hscl-verticalMenu-color-hover: #0066cc;
+  --hscl-verticalMenu-backgroundColor: transparent;
+  --hscl-verticalMenu-backgroundColor-hover: #f5f8fa;
+  --hscl-verticalMenu-submenu-color: #516f90;
+  --hscl-verticalMenu-submenu-color-hover: #0066cc;
+  --hscl-verticalMenu-submenu-backgroundColor: transparent;
+  --hscl-verticalMenu-submenu-backgroundColor-hover: #eaf0f6;
+  --hscl-verticalMenu-paddingInlineStart: 20px;
+
+  nav li {
+    margin-bottom: 0;
+  }
+}

package/components/componentLibrary/Menu/VerticalMenu/stories/VerticalMenuDecorator.tsx

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

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

@@ -0,0 +1,21 @@
+import { CSSVariables } from '../../utils/types.js';
+import { ContentFieldsProps } from '../types.js';
+import { SiteMenu } from '@hubspot/cms-components';
+
+export type VerticalMenuProps = {
+  maxDepth?: number;
+  className?: string;
+  style?: CSSVariables;
+  linkColor?: string;
+  linkColorHover?: string;
+  backgroundColor?: string;
+  backgroundColorHover?: string;
+  submenuLinkColor?: string;
+  submenuLinkColorHover?: string;
+  submenuBackgroundColor?: string;
+  submenuBackgroundColorHover?: string;
+  indentation?: string;
+  menuData: SiteMenu;
+};
+
+export type VerticalMenuContentFieldProps = ContentFieldsProps;