@hubspot/cms-component-library 0.1.0 → 0.3.0

package/components/componentLibrary/_patterns/function-declaration-patterns.md

@@ -0,0 +1,281 @@
+# Function Declaration Patterns
+
+This document establishes the standard function declaration patterns for the Component Library.
+
+## The Rule
+
+**React-related code uses arrow functions. Everything else uses traditional functions (or arrow functions if preferred).**
+
+### What is "React-related"?
+
+- React components (function components)
+- Functions that return JSX
+- React callbacks and event handlers
+- Field components
+- Helper functions within React components that work with JSX or React concepts
+
+### What is "Everything else"?
+
+- Pure utility functions that don't involve React or JSX
+- Helper functions for data transformation, formatting, validation
+- Functions that operate on plain JavaScript data structures
+
+## ✅ Use Arrow Functions For
+
+### React Components
+
+```typescript
+// Main components
+const Button = ({
+  variant = 'primary',
+  children,
+  ...rest
+}: ButtonProps) => {
+  return <button {...rest}>{children}</button>;
+};
+
+export default Button;
+```
+
+```typescript
+// Field components
+const ContentFields = ({
+  fieldLabel = 'Field',
+  fieldName = 'field',
+  fieldDefault = 'Default',
+}: ContentFieldsProps) => {
+  return <TextField label={fieldLabel} name={fieldName} default={fieldDefault} />;
+};
+
+export default ContentFields;
+```
+
+```typescript
+// Island components
+const NavigationMenuIsland = ({
+  justifyMenu = 'flex-start',
+  ...rest
+}: NavigationMenuProps) => {
+  return <nav {...rest}>{/* JSX */}</nav>;
+};
+
+export default NavigationMenuIsland;
+```
+
+### Functions That Return JSX
+
+```typescript
+const ButtonComponent = ({ buttonType, ...rest }: ButtonProps) => {
+  // Helper functions that return JSX use arrow functions
+  const renderButton = ({ onClick, disabled, children }: ButtonAsButtonProps) => {
+    return (
+      <button onClick={onClick} disabled={disabled}>
+        {children}
+      </button>
+    );
+  };
+
+  const renderLink = ({ href, children }: ButtonAsLinkProps) => {
+    return <a href={href}>{children}</a>;
+  };
+
+  if (buttonType === 'button') return renderButton(rest);
+  return renderLink(rest);
+};
+```
+
+### React Callbacks and Event Handlers
+
+```typescript
+const Component = () => {
+  // Event handlers and callbacks use arrow functions
+  const handleClick = () => {
+    console.log('clicked');
+  };
+
+  const handleKeyDown = (event: React.KeyboardEvent) => {
+    if (event.key === 'Enter') {
+      // handle enter
+    }
+  };
+
+  const processData = (data: string) => {
+    // processing logic
+  };
+
+  return <div onClick={handleClick} onKeyDown={handleKeyDown} />;
+};
+```
+
+## ✅ Use Traditional Functions For (Optional)
+
+Pure utility functions that don't involve React or JSX can use traditional function declarations if preferred:
+
+```typescript
+// Pure utility - no React, no JSX
+function formatCurrency(amount: number): string {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+  }).format(amount);
+}
+
+// Data transformation - no React, no JSX
+function sortByDate(items: Item[]): Item[] {
+  return [...items].sort((a, b) => a.date.getTime() - b.date.getTime());
+}
+
+// Validation - no React, no JSX
+function isValidEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+```
+
+**Note:** Arrow functions are also fine for these cases - use whichever you prefer for non-React utilities.
+
+## Why This Pattern?
+
+### Arrow Functions for React Code
+
+1. **Avoids `this` issues**: Arrow functions don't bind their own `this`, preventing common React pitfalls
+2. **Consistency**: All React components use the same pattern
+3. **Modern convention**: Aligns with current React and TypeScript best practices
+4. **Lexical scoping**: Better behavior with closures and event handlers
+
+### Traditional Functions for Utilities
+
+1. **Flexibility**: Use either arrow or traditional - whatever fits the use case
+2. **Readability**: Traditional functions can be more readable for complex utility logic
+3. **Hoisting**: Traditional functions are hoisted, which can be useful for utility organization
+
+## Scope
+
+This pattern applies to:
+
+### Must Use Arrow Functions
+
+- All React components (`*/index.tsx`)
+- All Field components (`*Fields.tsx`)
+- All Island components (`*/islands/*.tsx`)
+- All helper functions within React components
+- All functions that return JSX
+- All React callbacks and event handlers
+
+### Can Use Either
+
+- Utility functions that don't involve React/JSX
+- Data transformation functions
+- Validation functions
+- Pure JavaScript helpers
+
+## Examples
+
+### React Component with Helper Functions
+
+```typescript
+// Button/index.tsx
+const ButtonComponent = ({
+  buttonType = 'link',
+  variant = 'primary',
+  className = '',
+  style = {},
+  ...rest
+}: ButtonProps) => {
+  // Arrow function - returns JSX
+  const renderButton = ({ onClick, disabled, children }: ButtonAsButtonProps) => {
+    return (
+      <button onClick={onClick} disabled={disabled}>
+        {children}
+      </button>
+    );
+  };
+
+  // Arrow function - returns JSX
+  const renderLink = ({ href, target, children }: ButtonAsLinkProps) => {
+    return <a href={href} target={target}>{children}</a>;
+  };
+
+  if (buttonType === 'button') return renderButton(rest);
+  return renderLink(rest);
+};
+
+export default ButtonComponent;
+```
+
+### Field Component
+
+```typescript
+// ContentFields.tsx
+const ContentFields = ({
+  fieldLabel = 'Field',
+  fieldName = 'field',
+  fieldDefault = 'Default',
+}: ContentFieldsProps) => {
+  return (
+    <TextField
+      label={fieldLabel}
+      name={fieldName}
+      default={fieldDefault}
+    />
+  );
+};
+
+export default ContentFields;
+```
+
+### Island Component
+
+```typescript
+// NavigationMenuIsland.tsx
+const NavigationMenuIsland = ({
+  justifyMenu = 'flex-start',
+  className = '',
+  ...rest
+}: NavigationMenuProps) => {
+  // Arrow function - React event handler
+  const handleKeyDown = (event: React.KeyboardEvent) => {
+    if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      // handle navigation
+    }
+  };
+
+  return (
+    <nav onKeyDown={handleKeyDown} className={className} {...rest}>
+      {/* JSX */}
+    </nav>
+  );
+};
+
+export default NavigationMenuIsland;
+```
+
+### Utility Functions (Non-React)
+
+```typescript
+// utils/transformMenuData.ts
+// Arrow function is fine for utilities
+export const addIdsToMenuItems = (items: MenuDataItem[]): EnrichedMenuDataItem[] => {
+  return items.map(item => ({
+    ...item,
+    _id: crypto.randomUUID(),
+  }));
+};
+
+// Traditional function is also fine
+export function formatDate(date: Date): string {
+  return date.toISOString().split('T')[0];
+}
+```
+
+## Summary
+
+- **React components, JSX-returning functions, React callbacks** → Always arrow functions
+- **Pure utilities (no React/JSX)** → Either arrow or traditional (your choice)
+- **When in doubt** → Use arrow functions
+
+## Related Patterns
+
+- [Component Structure](./component-structure.md) - General component patterns
+- [TypeScript Patterns](./typescript-patterns.md) - Type definitions and patterns
+- [Field Patterns](./field-patterns.md) - Field component patterns

package/components/componentLibrary/_patterns/llm-txt.template.md

@@ -152,7 +152,7 @@ import [COMPONENT_NAME] from '@components/componentLibrary/[COMPONENT_NAME]';
 ```tsx
 import [COMPONENT_NAME] from '@hubspot/cms-component-library/[COMPONENT_NAME]';
 
-export default function [ModuleName]({ fieldValues }) {
+const [ModuleName] = ({ fieldValues }) => {
   return (
     <[COMPONENT_NAME]
       [prop1]={fieldValues.[fieldValue1]}
@@ -161,7 +161,9 @@ export default function [ModuleName]({ fieldValues }) {
       {fieldValues.[contentField]}
     </[COMPONENT_NAME]>
   );
-}
+};
+
+export default [ModuleName];
 ```
 
 ## Styling

package/components/componentLibrary/_patterns/prop-naming-patterns.md

@@ -0,0 +1,208 @@
+# Component Style Prop Naming Patterns
+
+**Default:** Use exact CSS property names for style props. Never abbreviate or modify them.
+
+**Exception:** Use semantic names when describing intrinsic component characteristics (e.g., Divider's `thickness` instead of `borderWidth`). Use sparingly.
+
+## Pattern Rules
+
+### Rule 1: Main Component Props
+
+For props that style the main component element, use the exact CSS property name with optional state suffix:
+
+**Pattern:** `propertyState`
+
+**Examples:**
+
+- ✅ `color`, `colorHover`, `colorFocus`
+- ✅ `backgroundColor`, `backgroundColorHover`, `backgroundColorFocus`
+- ✅ `borderColor`, `borderWidth`, `borderStyle`
+- ✅ `padding`, `paddingBlock`, `paddingInline`
+
+**Common Mistakes:**
+
+- ❌ `textColor` (wrong - use `color`)
+- ❌ `background` (wrong - use `backgroundColor`)
+- ❌ `bgColor` (wrong - use `backgroundColor`)
+
+### Rule 2: Subcomponent Props
+
+For props that style subcomponents or nested elements, prefix with the element name:
+
+**Pattern:** `elementPropertyState`
+
+**Examples:**
+
+- ✅ `menuBackgroundColor`, `menuBackgroundColorHover`
+- ✅ `linkColor`, `linkColorHover`
+- ✅ `iconFill`, `iconStroke`
+- ✅ `titleColor`, `contentPadding`
+
+**Common Mistakes:**
+
+- ❌ `menuTextColor` (wrong - use `menuColor`)
+- ❌ `menuBackground` (wrong - use `menuBackgroundColor`)
+
+### Rule 3: State Suffixes
+
+State suffixes must be capitalized and match CSS pseudo-classes:
+
+**Valid Suffixes:**
+
+- `Hover` - for `:hover` state
+- `Focus` - for `:focus` state
+- `Active` - for `:active` state
+- `Disabled` - for `:disabled` state
+- `Visited` - for `:visited` state (links)
+- `Checked` - for `:checked` state (inputs)
+
+**Examples:**
+
+- ✅ `colorHover`, `backgroundColorFocus`, `borderColorActive`
+- ❌ `colorHOVER`, `colorHovering`, `colorOnHover`
+
+## Field Props Pattern
+
+Field configuration props (for CMS) build on the style prop name by adding standard suffixes:
+
+**Pattern:** `{propName}Label`, `{propName}Name`, `{propName}Default`
+
+**Examples:**
+```typescript
+// Style prop (follows CSS naming)
+color?: ColorFieldValue;
+
+// Field configuration props (use the prop name + suffix)
+colorLabel?: string;
+colorName?: string;
+colorDefault?: ColorFieldValue;
+```
+
+**Important:** The field props inherit the correct naming from the style prop. If your style prop is `color`, your field props are `colorLabel`, `colorName`, `colorDefault` - not `textColorLabel`, `textColorName`, `textColorDefault`.
+
+## Complete Component Example
+
+### LanguageSwitcher (Reference Implementation)
+
+```typescript
+// types.ts
+export type LanguageSwitcherProps = {
+  // Main component styles
+  color?: ColorFieldValue;
+  colorHover?: ColorFieldValue;
+
+  // Subcomponent styles
+  menuBackgroundColor?: ColorFieldValue;
+  menuBackgroundColorHover?: ColorFieldValue;
+};
+
+export type StyleFieldsProps = {
+  // Field props for main component
+  colorLabel?: string;
+  colorName?: string;
+  colorDefault?: ColorFieldValue;
+  colorHoverLabel?: string;
+  colorHoverName?: string;
+  colorHoverDefault?: ColorFieldValue;
+
+  // Field props for subcomponent
+  menuBackgroundColorLabel?: string;
+  menuBackgroundColorName?: string;
+  menuBackgroundColorDefault?: ColorFieldValue;
+  menuBackgroundColorHoverLabel?: string;
+  menuBackgroundColorHoverName?: string;
+  menuBackgroundColorHoverDefault?: ColorFieldValue;
+};
+```
+
+```typescript
+// index.tsx
+const LanguageSwitcherComponent = ({
+  color,
+  colorHover,
+  menuBackgroundColor,
+  menuBackgroundColorHover,
+}: LanguageSwitcherProps) => {
+  const cssVariables = {
+    ...(color?.rgba && { '--hscl-languageSwitcher-color': color.rgba }),
+    ...(colorHover?.rgba && { '--hscl-languageSwitcher-color-hover': colorHover.rgba }),
+    ...(menuBackgroundColor?.rgba && {
+      '--hscl-languageSwitcher-backgroundColor': menuBackgroundColor.rgba
+    }),
+    ...(menuBackgroundColorHover?.rgba && {
+      '--hscl-languageSwitcher-backgroundColor-hover': menuBackgroundColorHover.rgba
+    }),
+  };
+
+  return <div style={cssVariables}>...</div>;
+};
+```
+
+## Edge Cases
+
+### 1. Multiple Background Properties
+
+When a component needs multiple background-related properties, use exact CSS names:
+
+- ✅ `backgroundColor`, `backgroundImage`, `backgroundSize`
+- ❌ `background`, `bgImage`, `bgSize`
+
+### 2. Logical Properties
+
+Prefer logical properties for better internationalization:
+
+- ✅ `paddingBlock`, `paddingInline`, `marginBlock`, `marginInline`
+- ⚠️ `padding`, `margin` (acceptable but less specific)
+
+### 3. Shorthand vs Longhand
+
+When both exist, prefer the specific property:
+
+- ✅ `borderColor`, `borderWidth`, `borderStyle` (specific)
+- ⚠️ `border` (acceptable for simple use cases)
+
+### 4. Prop Types
+
+- **Style Props:** Use CSS property names (`color`, `backgroundColor`, `padding`)
+- **Behavior Props:** Use descriptive names (`onClick`, `disabled`, `variant`)
+- **Semantic Props:** Use sparingly for intrinsic characteristics (`thickness`, `length` for Divider)
+
+### 5. Semantic Props Example
+
+Divider uses semantic props because they describe what a divider *is*:
+
+```typescript
+thickness?: number;  // Divider's thickness (not borderWidth)
+length?: number;     // Divider's length (abstracts width/height based on orientation)
+spacing?: string;    // Space around it (abstracts marginBlock/marginInline)
+```
+
+Use semantic props when the name matches users' mental model better than CSS properties. Otherwise, use CSS property names.
+
+### 6. HTML Attributes vs CSS Properties
+
+Some props map to HTML attributes rather than CSS properties (e.g., Image's `width`/`height`):
+
+```typescript
+// Image component - props map to HTML attributes
+width?: number;   // Sets <img width="..."> (intrinsic sizing)
+height?: number;  // Sets <img height="..."> (intrinsic sizing)
+```
+
+This is acceptable because these control intrinsic rendering, not just styling. For CSS-based sizing, use `style` prop or `className`. If CSS props are needed in the future, they can be added separately (e.g., `cssWidth`).
+
+### 7. Shared vs Subcomponent Styles
+
+- Use `property` (main) when value is inherited/reused: `color`
+- Use `elementProperty` (sub) when specific to a subcomponent: `menuBackgroundColor`
+- Prefer sharing colors for consistency
+
+## Validation
+
+- ✅ Style props match exact CSS property names (no abbreviations)
+- ✅ State suffixes are capitalized (`colorHover`)
+- ✅ Subcomponent props include element prefix (`menuBackgroundColor`)
+- ✅ Field props follow `{propName}Label/Name/Default` pattern
+- ✅ Semantic props are documented and used sparingly
+
+**When in doubt, use CSS property names.**

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

@@ -10,7 +10,8 @@ Each component with stories should have a `stories/` directory containing:
 ComponentName/
 └── stories/
     ├── ComponentName.stories.tsx        # Main story file
-    └── ComponentNameDecorator.tsx       # Decorators for CSS variables (optional)
+    ├── ComponentNameDecorator.tsx       # Decorators for CSS variables (optional)
+    └── ComponentNameDecorator.module.scss  # Decorator styles (optional)
 ```
 
 **For components with multiple variants** (like Button):
@@ -19,7 +20,8 @@ Button/
 └── stories/
     ├── Button.AsButton.stories.tsx      # Variant 1 stories
     ├── Button.AsLink.stories.tsx        # Variant 2 stories
-    └── ButtonDecorator.tsx              # Shared decorators
+    ├── ButtonDecorator.tsx              # Shared decorators
+    └── ButtonDecorator.module.scss      # Decorator styles
 ```
 
 ## Meta Configuration
@@ -156,10 +158,11 @@ Create decorators to apply default CSS variables for stories:
 
 ```typescript
 import type { Decorator } from '@storybook/react';
+import type { CSSVariables } from '../../utils/types.js';
 
-const defaultComponentStyles: React.CSSProperties = {
+const defaultComponentStyles: CSSVariables = {
   '--hscl-component-property': 'value',
-} as React.CSSProperties;
+};
 
 export const withComponentStyles: Decorator = (Story) => (
   <div style={defaultComponentStyles}>
@@ -178,12 +181,26 @@ Use `SBContainer` for consistent layout and spacing in stories:
 
 **Props:**
 - `children`: ReactNode - Content to render
+- `className?: string` - Additional CSS classes
 - `addBackground?: boolean` - Adds light gray background (default: false)
 - `flex?: boolean` - Enables flexbox layout (default: false)
 - `direction?: 'row' | 'column' | 'row-reverse' | 'column-reverse'` - Flex direction (default: 'column')
-- `gap?: string` - Gap between flex items (default: '16px')
+- `gap?: 'none' | 'small' | 'medium' | 'large' | 'extralarge'` - Gap between flex items (default: 'none')
+- `padding?: 'none' | 'small' | 'medium' | 'large' | 'extralarge'` - Padding inside container (default: 'medium')
 - `alignItems?: CSSProperties['alignItems']` - Flex align-items (default: 'stretch')
 - `justifyContent?: CSSProperties['justifyContent']` - Flex justify-content (default: 'flex-start')
+- `minWidth?: string` - Minimum width (default: 'auto')
+- `maxWidth?: string` - Maximum width (default: 'auto')
+- `width?: string` - Fixed width
+- `height?: string` - Fixed height
+- `style?: CSSProperties` - Additional inline styles
+
+**Size Values:**
+- `none`: 0
+- `small`: 8px
+- `medium`: 16px
+- `large`: 24px
+- `extralarge`: 32px
 
 **Example Usage:**
 ```typescript
@@ -191,13 +208,13 @@ import { SBContainer } from '@sb-utils/SBContainer.js';
 
 export const ExampleStory: Story = {
   render: () => (
-    <SBContainer flex direction="column" gap="16px">
-      <SBContainer addBackground>
+    <SBContainer flex direction="column" gap="large">
+      <SBContainer addBackground padding="large">
         <h4>Example Title</h4>
         <Component prop="value">Content</Component>
       </SBContainer>
 
-      <SBContainer addBackground>
+      <SBContainer addBackground padding="medium">
         <h4>Another Example</h4>
         <Component prop="different">More content</Component>
       </SBContainer>

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

@@ -2,6 +2,8 @@
 
 This document outlines TypeScript type definitions, patterns, and conventions for componentLibrary.
 
+> **Note:** For prop naming conventions, see [Prop Naming Patterns](./prop-naming-patterns.md)
+
 ## Type Definitions Structure
 
 All components maintain a separate `types.ts` file with:
@@ -85,9 +87,10 @@ export type ButtonProps = ButtonAsButtonProps | ButtonAsLinkProps;
 
 **Usage in component:**
 ```typescript
-const ButtonComponent = (props: ButtonProps) => {
-  const { buttonType, ...rest } = props;
-
+const ButtonComponent = ({
+  buttonType,
+  ...rest
+}: ButtonProps) => {
   // TypeScript knows which props are available based on buttonType
   if (buttonType === 'button') return renderButton(rest);
   return renderLink(rest);

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@hubspot/cms-component-library",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "HubSpot CMS React component library for building CMS modules",
   "license": "Apache-2.0",
   "exports": {
+    "./VerticalMenu": "./components/componentLibrary/Menu/VerticalMenu/index.tsx",
+    "./NavigationMenu": "./components/componentLibrary/Menu/NavigationMenu/index.tsx",
     "./*": "./components/componentLibrary/*/index.tsx"
   },
   "files": [
@@ -14,11 +16,12 @@
     "url": "git@git.hubteam.com:HubSpot/cms-component-library.git"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   },
   "type": "module",
   "dependencies": {
-    "@hubspot/cms-components": "^1.0.37",
+    "@hubspot/cms-components": "^1.2.13",
     "sass-embedded": "^1.90.0",
     "tsx": "^4.20.5"
   },