@hubspot/cms-component-library 0.1.0 → 0.2.0

package/components/componentLibrary/Menu/types.ts

@@ -0,0 +1,56 @@
+import {
+  AlignmentFieldType,
+  MenuFieldDefaults,
+} from '@hubspot/cms-components/fields';
+import { PageTreeNode } from '@hubspot/cms-components';
+import { CSSProperties, ReactNode } from 'react';
+
+export type MenuOrientation = 'horizontal' | 'vertical';
+
+export type MenuItem = MenuDataItem;
+
+export type MenuRenderProps = {
+  orientation?: MenuOrientation;
+  alignment?: AlignmentFieldType['default'];
+  maxDepth?: number;
+  ariaLabel?: string;
+  variant?: 'primary' | 'secondary';
+  className?: string;
+  style?: CSSProperties;
+};
+
+export type MenuProps = MenuRenderProps & {
+  menuId?: string;
+  items?: MenuItem[];
+  children?: MenuItem[];
+};
+
+export type ContentFieldsProps = {
+  menuLabel?: string;
+  menuName?: string;
+  menuDefault?: typeof MenuFieldDefaults;
+};
+
+export type StyleFieldsProps = {
+  orientationLabel?: string;
+  orientationName?: string;
+  orientationDefault?: MenuOrientation;
+};
+
+export interface MenuProviderProps {
+  maxDepth?: number;
+  children: ReactNode;
+  useDummyData?: boolean;
+}
+
+export type MenuDataItem = PageTreeNode;
+
+export type EnrichedMenuDataItem = MenuDataItem & {
+  _id: string;
+};
+
+export interface MenuContextValue {
+  maxDepth?: number;
+  orientation?: 'horizontal' | 'vertical';
+  children?: EnrichedMenuDataItem[];
+}

package/components/componentLibrary/Menu/utils/transformMenuData.ts

@@ -0,0 +1,11 @@
+import { EnrichedMenuDataItem, MenuDataItem } from '../types.js';
+
+export const addIdsToMenuItems = (
+  items: MenuDataItem[]
+): EnrichedMenuDataItem[] => {
+  return items.map(item => ({
+    ...item,
+    _id: crypto.randomUUID(),
+    children: item.children.length > 0 ? addIdsToMenuItems(item.children) : [],
+  }));
+};

package/components/componentLibrary/_patterns/README.md

@@ -13,6 +13,12 @@ CSS variable naming, styling conventions, modules, and state-based patterns.
 ### 📝 [TypeScript Patterns](./typescript-patterns.md)
 Type definitions, union types, discriminated unions, and conditional field props.
 
+### ⚡ [Function Declaration Patterns](./function-declaration-patterns.md)
+React-related code (components, JSX-returning functions, callbacks) uses arrow functions. Non-React utilities can use traditional functions.
+
+### 🏷️ [Prop Naming Patterns](./prop-naming-patterns.md)
+Standardized naming conventions for component props to ensure consistency across the library.
+
 ### 📋 [Field Patterns](./field-patterns.md)
 Field components, property ordering, visibility rules, and nested patterns.
 
@@ -22,23 +28,15 @@ Story structure, utilities, mocks, and essential story types.
 ### ✅ [Checklist and Examples](./checklist-and-examples.md)
 Comprehensive component creation checklist, complete reference examples, step-by-step validation guide, and full component implementation examples.
 
-## Quick Reference
-
-### Creating a New Component Checklist
+## Creating a New Component
 
-When creating a new component, reference these files in order:
+Reference these pattern files in order when building a new component:
 
 1. **[Component Structure](./component-structure.md)** - Set up files and basic structure
-2. **[TypeScript Patterns](./typescript-patterns.md)** - Define types in `types.ts`
-3. **[CSS Patterns](./css-patterns.md)** - Create styles with proper variable naming
-4. **[Field Patterns](./field-patterns.md)** - Add ContentFields and StyleFields (if needed)
-5. **[Storybook Patterns](./storybook-patterns.md)** - Create stories for documentation (if needed)
-
-### Common Patterns Quick Links
-
-**CSS Variable Naming:** `--hscl-componentName-property-state` → [CSS Patterns](./css-patterns.md#css-variable-naming-convention)
-**Static Class Names:** `'hscl-componentName'` → [Component Structure](./component-structure.md#static-class-names)
-**Props Destructuring:** Standard pattern → [Component Structure](./component-structure.md#props-destructuring-pattern)
-**Field Props:** `{field}Label`, `{field}Name`, `{field}Default` → [TypeScript Patterns](./typescript-patterns.md#field-props-types)
-**Story Categories:** Basic, Content, Icon, etc. → [Storybook Patterns](./storybook-patterns.md#argtypes-organization)
-
+2. **[Function Declaration Patterns](./function-declaration-patterns.md)** - Use arrow functions for React code
+3. **[TypeScript Patterns](./typescript-patterns.md)** - Define types in `types.ts`
+4. **[Prop Naming Patterns](./prop-naming-patterns.md)** - Name props consistently
+5. **[CSS Patterns](./css-patterns.md)** - Create styles with proper variable naming
+6. **[Field Patterns](./field-patterns.md)** - Add ContentFields and StyleFields (if needed)
+7. **[Storybook Patterns](./storybook-patterns.md)** - Create stories for documentation (optional)
+8. **[LLM Documentation Template](./llm-txt.template.md)** - Create `llm.txt` for AI/LLM consumption

package/components/componentLibrary/_patterns/checklist-and-examples.md

@@ -31,13 +31,14 @@ When creating a new component in componentLibrary, ensure:
 
 ### Component Implementation
 - [ ] Component exports as compound component with field attachments
-- [ ] Props follow destructuring pattern with defaults
+- [ ] Props destructured inline in function signature with defaults
 - [ ] Helper functions defined outside component (when reusable or for readability)
 - [ ] Proper use of early returns for conditional rendering
 - [ ] `{...rest}` spread to underlying HTML element
 
 ### Field Components
 - [ ] ContentFields and StyleFields export as default functions
+- [ ] Field props destructured inline in function signature with defaults
 - [ ] Field props support label, name, and default customization
 - [ ] ChoiceField choices use `[value, displayLabel]` format
 - [ ] NumberFields include appropriate `suffix`, `min`, `max` props
@@ -96,14 +97,13 @@ import StyleFields from './StyleFields.js';
 import cx from '../utils/classname.js';
 import { ComponentProps } from './types.js';
 
-const ComponentNameComponent = (props: ComponentProps) => {
-  const {
-    variant = 'primary',
-    className = '',
-    style = {},
-    children,
-    ...rest
-  } = props;
+const ComponentNameComponent = ({
+  variant = 'primary',
+  className = '',
+  style = {},
+  children,
+  ...rest
+}: ComponentProps) => {
 
   const cssVariables: React.CSSProperties & {
     [key: `--${string}`]: string | undefined;
@@ -184,13 +184,11 @@ export type StyleFieldsProps = {
 import { TextField } from '@hubspot/cms-components/fields';
 import { ContentFieldsProps } from './types.js';
 
-export default function ContentFields(props: ContentFieldsProps) {
-  const {
-    fieldLabel = 'Field',
-    fieldName = 'field',
-    fieldDefault = 'Default',
-  } = props;
-
+const ContentFields = ({
+  fieldLabel = 'Field',
+  fieldName = 'field',
+  fieldDefault = 'Default',
+}: ContentFieldsProps) => {
   return (
     <TextField
       label={fieldLabel}
@@ -198,5 +196,7 @@ export default function ContentFields(props: ContentFieldsProps) {
       default={fieldDefault}
     />
   );
-}
+};
+
+export default ContentFields;
 ```

package/components/componentLibrary/_patterns/component-structure.md

@@ -80,23 +80,22 @@ const sharedProps = {
 
 ## Props Destructuring Pattern
 
-Components follow a consistent prop destructuring pattern:
+Components destructure props inline in the function signature with defaults:
 
 ```typescript
-const ComponentName = (props: ComponentProps) => {
-  const {
-    // Required props first (no defaults)
-    requiredProp,
-
-    // Optional props with defaults
-    variant = 'primary',
-    className = '',
-    style = {},
-    children = 'Default content',
-
-    // Spread remaining props
-    ...rest
-  } = props;
+const ComponentName = ({
+  // Required props first (no defaults)
+  requiredProp,
+
+  // Optional props with defaults
+  variant = 'primary',
+  className = '',
+  style = {},
+  children = 'Default content',
+
+  // Spread remaining props
+  ...rest
+}: ComponentProps) => {
 ```
 
 **Standard props every component should accept:**
@@ -232,14 +231,13 @@ import StyleFields from './StyleFields.js';
 import cx from '../utils/classname.js';
 import { ComponentProps } from './types.js';
 
-const ComponentNameComponent = (props: ComponentProps) => {
-  const {
-    variant = 'primary',
-    className = '',
-    style = {},
-    children,
-    ...rest
-  } = props;
+const ComponentNameComponent = ({
+  variant = 'primary',
+  className = '',
+  style = {},
+  children,
+  ...rest
+}: ComponentProps) => {
 
   const cssVariables: React.CSSProperties & {
     [key: `--${string}`]: string | undefined;

package/components/componentLibrary/_patterns/css-patterns.md

@@ -4,14 +4,17 @@ This document outlines CSS variable naming conventions, styling patterns, and CS
 
 ## CSS Variable Naming Convention
 
-**Pattern:** `--hscl-componentName-property-state`
+**Pattern:** `--hscl-componentName-[elementName]-cssProperty-[state]`
 
 - **Prefix:** Always start with `--hscl-` (HubSpot Component Library)
-- **Component name:** Lowercase component name in camelCase, with name taken from the index.tsx file (e.g., `button`, `heading`, `icon`, `divider`, `image`, `listIcon`)
-- **Property:** CSS property name in camelCase (e.g., `backgroundColor`, `fontSize`, `borderColor`)
-- **State (optional):** State suffix for interactive states (e.g., `-hover`, `-focus`, `-disabled`)
-
-**Examples:**
+- **Component name:** Lowercase component name in camelCase, with name taken from the index.tsx file (e.g., `button`, `heading`, `icon`, `divider`, `image`, `accordion`)
+- **Element name (optional):** For sub-elements within a component, specify the element name in camelCase (e.g., `icon`, `body`, `title`, `header`, `overlay`, `submenu`)
+  - Omit for properties that apply to the main component element itself
+  - Include for properties that apply to specific sub-elements
+- **CSS Property:** CSS property name in camelCase (e.g., `backgroundColor`, `fontSize`, `borderColor`, `paddingBlock`)
+- **State (optional):** State suffix for interactive states (e.g., `-hover`, `-focus`, `-disabled`, `-active`)
+
+**Examples for main component element:**
 ```css
 --hscl-button-backgroundColor
 --hscl-button-backgroundColor-hover
@@ -19,11 +22,29 @@ This document outlines CSS variable naming conventions, styling patterns, and CS
 --hscl-heading-fontSize
 --hscl-heading-textAlign
 --hscl-divider-borderColor
---hscl-divider-borderStyle
 --hscl-icon-fill
---hscl-image-borderRadius
+--hscl-card-padding
+```
+
+**Examples for sub-elements:**
+```css
+--hscl-button-icon-fill
+--hscl-accordion-body-color
+--hscl-accordion-body-paddingBlock
+--hscl-accordion-title-backgroundColor
+--hscl-accordion-title-fontSize
+--hscl-drawer-overlay-backgroundColor
+--hscl-navigationMenu-submenu-linkColor
+--hscl-navigationMenu-submenu-backgroundColor-hover
 ```
 
+**Naming Best Practices:**
+- Use camelCase throughout (never use underscores or hyphens within segments)
+- Property names should match CSS property names when possible (e.g., `backgroundColor` not `bgColor`, `fill` not `fillColor`)
+- Element names should be descriptive and singular (e.g., `icon`, `body`, `header`)
+- State suffixes should match CSS pseudo-classes (e.g., `hover`, `focus`, `active`, `disabled`)
+- Avoid redundant words (e.g., use `--hscl-list-item-color` not `--hscl-list-item-text-color`)
+
 **Nested/Dynamic Variables:**
 ```typescript
 // Example from Heading component - uses template variables
@@ -31,44 +52,86 @@ This document outlines CSS variable naming conventions, styling patterns, and CS
 '--hscl-heading-fontSize': `var(--hscl-heading-${displayAsValue}-fontSize)`
 ```
 
+**Note:** When using dynamic variants (like h1, h2, display1), use numbers without underscores (e.g., `display1` not `display_1`).
+
 ## CSS Variables Application
 
-Components apply CSS variables through the `style` prop:
+Components apply CSS variables through the `style` prop using the `CSSVariables` type:
 
 ```typescript
-// 1. Define CSS variables object with proper typing
-const cssVariables: React.CSSProperties & {
-  [key: `--${string}`]: string | undefined;
-} = {
+// Import the CSSVariables type
+import type { CSSVariables } from '../utils/types.js';
+
+// ALWAYS define CSS variables as typed constants
+const cssVariables: CSSVariables = {
   '--hscl-component-property': value,
   '--hscl-component-property2': `${numericValue}px`, // Include units when needed
 };
 
-// 2. Merge with user's style prop (treat as override)
+// Then use in JSX
 <Element style={{ ...cssVariables, ...style }} />
+<Element style={cssVariables} />
+```
+
+**The CSSVariables Type:**
+
+The `CSSVariables` type extends `React.CSSProperties` to support CSS custom properties:
+
+```typescript
+export type CSSVariables = React.CSSProperties & {
+  [key: `--${string}`]: string | undefined;
+};
+```
+
+**Important: Always Define Variables, Never Inline**
+
+❌ **Don't** inline CSS variable objects directly in JSX (causes TypeScript errors):
+```typescript
+// This will cause TypeScript errors
+<Element style={{ '--hscl-property': value }} />
+```
+
+✅ **Do** define them as typed constants:
+```typescript
+// This works correctly
+const elementStyle: CSSVariables = {
+  '--hscl-property': value,
+};
+<Element style={elementStyle} />
 ```
 
 **Examples:**
 
 ```typescript
+import type { CSSVariables } from '../utils/types.js';
+
 // Heading - dynamic variable references
-const cssVariables: React.CSSProperties = {
+const cssVariables: CSSVariables = {
   '--hscl-heading-font': `var(--hscl-heading-${displayAsValue}-font)`,
   '--hscl-heading-fontSize': `var(--hscl-heading-${displayAsValue}-fontSize)`,
   ...(alignment && {
     '--hscl-heading-textAlign': alignment.toLowerCase(),
   }),
-} as React.CSSProperties;
+};
 
 // Divider - direct values with units
-const cssVariables: React.CSSProperties = {
+const cssVariables: CSSVariables = {
   '--hscl-divider-alignment': getAlignmentCSSVar(alignment),
   '--hscl-divider-spacing': spacing,
   '--hscl-divider-borderStyle': borderStyle,
   '--hscl-divider-length': `${length}%`,
   '--hscl-divider-thickness': `${thickness}px`,
   ...style,
-} as React.CSSProperties;
+};
+
+// In stories - define within render function
+render: () => {
+  const blueColor: CSSVariables = {
+    '--hscl-divider-borderColor': '#3b82f6',
+  };
+
+  return <Divider thickness={2} style={blueColor} />;
+}
 ```
 
 ## CSS Module Patterns
@@ -208,6 +271,95 @@ Use `&` for pseudo-classes and nested selectors:
 }
 ```
 
+## Accessibility Patterns for Interactive Components
+
+Interactive components (Button, Link, etc.) should implement all relevant accessibility states following HubSpot's CSS guidelines.
+
+### Required Interactive States
+
+All interactive components should style **hover, focus, active** states:
+
+```scss
+.button {
+  // Base styles
+  background-color: var(--hscl-button-backgroundColor);
+  color: var(--hscl-button-color);
+  transition: all 0.2s ease;
+
+  // Respect user's motion preferences
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+
+  // Hover - visual feedback on mouse over
+  &:hover {
+    background-color: var(--hscl-button-backgroundColor-hover, var(--hscl-button-backgroundColor));
+    color: var(--hscl-button-color-hover, var(--hscl-button-color));
+  }
+
+  // Focus-visible - keyboard navigation only (not mouse clicks)
+  &:focus-visible {
+    outline: var(--hscl-button-outlineWidth-focus, 2px) solid var(--hscl-button-outlineColor-focus, currentColor);
+    outline-offset: var(--hscl-button-outlineOffset-focus, 2px);
+  }
+
+  // Active - pressed/clicked state
+  &:active {
+    background-color: var(--hscl-button-backgroundColor-active, var(--hscl-button-backgroundColor));
+    color: var(--hscl-button-color-active, var(--hscl-button-color));
+  }
+
+  // Disabled - non-interactive state
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+```
+
+### Key Accessibility Principles
+
+1. **Use `:focus-visible` instead of `:focus`**
+   - Shows focus outline only for keyboard navigation
+   - Better UX - no outline when clicking with mouse
+   - Follows modern accessibility best practices
+
+2. **Provide fallback values that inherit from base state**
+   ```scss
+   // Good - inherits from base if not customized
+   background-color: var(--hscl-button-backgroundColor-hover, var(--hscl-button-backgroundColor));
+
+   // Avoid - no fallback to base state
+   background-color: var(--hscl-button-backgroundColor-hover);
+   ```
+
+3. **Use `currentColor` for focus outlines**
+   - Adapts to component's text color automatically
+   - Ensures sufficient contrast in most cases
+   ```scss
+   outline: var(--hscl-button-outlineColor-focus, currentColor);
+   ```
+
+4. **Respect reduced motion preferences**
+   ```scss
+   transition: all 0.2s ease;
+
+   @media (prefers-reduced-motion: reduce) {
+     transition: none;
+   }
+   ```
+
+5. **All states should be customizable via CSS variables**
+   - Enables theme customization
+   - Maintains consistent API across components
+
+### Pattern Reference
+
+See these components for implementation examples:
+- **Button** (`devWorkspace/src/components/componentLibrary/Button/index.module.scss`) - Full implementation with all states and reduced motion support
+- **Link** (`devWorkspace/src/components/componentLibrary/Link/index.module.scss`) - Minimal interactive component with hover, focus, and active states
+- **Logo** (`devWorkspace/src/components/componentLibrary/Logo/index.tsx`) - Composition example: inherits focus styles from Link component when wrapped
+
 ## Complete CSS Module Example
 
 ```scss

package/components/componentLibrary/_patterns/field-patterns.md

@@ -4,17 +4,15 @@ This document outlines patterns for creating and configuring field components in
 
 ## Field Components Pattern
 
-Field components accept configuration props for customization:
+Field components destructure props inline with defaults for customization:
 
 ```typescript
-export default function ContentFields(props: ContentFieldsProps) {
-  const {
-    // Each field gets label, name, and default props
-    fieldLabel = 'Default label',
-    fieldName = 'defaultName',
-    fieldDefault = 'Default value',
-  } = props;
-
+const ContentFields = ({
+  // Each field gets label, name, and default props
+  fieldLabel = 'Default label',
+  fieldName = 'defaultName',
+  fieldDefault = 'Default value',
+}: ContentFieldsProps) => {
   return (
     <>
       <TextField
@@ -25,7 +23,79 @@ export default function ContentFields(props: ContentFieldsProps) {
       {/* Additional fields */}
     </>
   );
-}
+};
+
+export default ContentFields;
+```
+
+## Subcomponent Field Placement
+
+**Rule:** Define fields on the subcomponent that consumes them.
+
+**Anti-pattern:** Rolling fields up to a parent component for "convenience" or centralization.
+
+### Reference Example: Accordion
+
+| Component | Fields | Reason |
+|-----------|--------|--------|
+| `Accordion` | `StyleFields` (gap) | Parent layout concern |
+| `AccordionItem` | `StyleFields` (variant) | Item-level styling |
+| `AccordionTitle` | `ContentFields` (title, icon) | Title-specific content |
+| `AccordionContent` | `ContentFields` (content) | Content-specific field |
+
+**File Structure:**
+```
+Accordion/
+├── index.tsx
+├── types.ts              # Accordion StyleFieldsProps (gap)
+├── AccordionItem/
+│   ├── StyleFields.tsx   # variant field
+│   └── types.ts
+├── AccordionTitle/
+│   ├── ContentFields.tsx # title, icon fields
+│   └── types.ts
+└── AccordionContent/
+    ├── ContentFields.tsx # content field
+    └── types.ts
+```
+
+### Field Ordering with Multiple Subcomponents
+
+When a module uses multiple subcomponents, order fields as follows:
+1. Parent component fields first
+2. Child component fields in DOM/render order
+3. Group fields by subcomponent for clarity
+
+**Code Example (module fields.tsx):**
+```typescript
+import {
+  FieldGroup,
+  ModuleFields,
+  RepeatedFieldGroup,
+} from '@hubspot/cms-components/fields';
+import {
+  AccordionContent,
+  AccordionItem,
+  AccordionTitle,
+} from '../../componentLibrary/Accordion/index.js';
+
+export const fields = (
+  <ModuleFields>
+    {/* Content fields in DOM/render order */}
+    <RepeatedFieldGroup
+      label="Accordion items"
+      name="accordionItems"
+      occurrence={{ min: 1, max: 20, default: 3 }}
+    >
+      <AccordionTitle.ContentFields />
+      <AccordionContent.ContentFields />
+    </RepeatedFieldGroup>
+    {/* Style fields grouped in STYLE tab */}
+    <FieldGroup label="Style" name="style" tab="STYLE">
+      <AccordionItem.StyleFields />
+    </FieldGroup>
+  </ModuleFields>
+);
 ```
 
 ## Field Label Casing
@@ -58,18 +128,18 @@ Field properties should be ordered in the following order:
 
 ## Field Component Props Destructuring
 
-Like components, all field components should follow a consistent destructuring pattern with label, name, and default props:
+All field components destructure props inline in the function signature with defaults:
 
 ```typescript
-export default function ContentFields(props: ContentFieldsProps) {
-  const {
-    fieldLabel = 'Default label',
-    fieldName = 'defaultName',
-    fieldDefault = 'default value',
-  } = props;
-
+const ContentFields = ({
+  fieldLabel = 'Default label',
+  fieldName = 'defaultName',
+  fieldDefault = 'default value',
+}: ContentFieldsProps) => {
   return <Field label={fieldLabel} name={fieldName} default={fieldDefault} />;
-}
+};
+
+export default ContentFields;
 ```
 
 ## Common Field Patterns
@@ -151,13 +221,11 @@ const SHOW_ICON_VISIBILITY_RULES: Visibility = {
 import { TextField } from '@hubspot/cms-components/fields';
 import { ContentFieldsProps } from './types.js';
 
-export default function ContentFields(props: ContentFieldsProps) {
-  const {
-    fieldLabel = 'Field',
-    fieldName = 'field',
-    fieldDefault = 'Default',
-  } = props;
-
+const ContentFields = ({
+  fieldLabel = 'Field',
+  fieldName = 'field',
+  fieldDefault = 'Default',
+}: ContentFieldsProps) => {
   return (
     <TextField
       label={fieldLabel}
@@ -165,5 +233,7 @@ export default function ContentFields(props: ContentFieldsProps) {
       default={fieldDefault}
     />
   );
-}
+};
+
+export default ContentFields;
 ```