@hubspot/cms-component-library 0.3.0 → 0.3.2

package/components/componentLibrary/Text/llm.txt

@@ -0,0 +1,170 @@
+# Text Component
+
+A component for rendering HubSpot CMS rich text field content.
+
+## Import path
+```tsx
+import Text from '@hubspot/cms-component-library/Text';
+```
+
+## Purpose
+
+The Text component wraps HubSpot's native `RichText` component to provide a consistent interface for rendering editable rich text content in HubSpot CMS modules. It handles the connection between a CMS field and the rendered output, while exposing a single CSS variable for text color theming. Use this component whenever a module needs a rich text area managed through the HubSpot page editor.
+
+## Component Structure
+
+```
+Text/
+├── index.tsx                     # Main component wrapping HubSpot RichText
+├── types.ts                      # TypeScript type definitions
+├── ContentFields.tsx             # HubSpot field definitions for rich text content
+└── index.module.scss             # CSS module with design tokens
+```
+
+## Components
+
+### Text (Main Component)
+
+**Purpose:** Renders a HubSpot CMS rich text field at the given `fieldPath`, applying CSS module class and CSS variable theming for text color.
+
+**Props:**
+```tsx
+{
+  fieldPath?: string;      // Path to the RichText field in HubSpot CMS (e.g., 'text', 'bodyContent')
+  className?: string;      // Additional CSS classes (default: '')
+  style?: CSSVariables;    // Inline styles, supports CSS custom properties (default: {})
+}
+```
+
+## Usage Examples
+
+### Basic Text
+
+```tsx
+import Text from '@hubspot/cms-component-library/Text';
+
+<Text fieldPath="text" />
+```
+
+## HubSpot CMS Integration
+
+### Field Definitions
+
+The Text component provides `ContentFields` for defining a `RichTextField` inside a HubSpot CMS module.
+
+#### ContentFields
+
+Configurable props for customizing the text field label, name, default value, and editor features:
+
+```tsx
+<Text.ContentFields
+  textLabel="Body text"
+  textName="bodyText"
+  textDefault="<p>Enter your content here.</p>"
+  textFeatureSet="bodyContent"
+/>
+```
+
+**Props:**
+- `textLabel` (default: `'Text'`): Label shown in the HubSpot editor
+- `textName` (default: `'text'`): Field name used as the `fieldPath` reference in the component
+- `textDefault` (default: `'<p>Text goes here.</p>'`): Default HTML content for the field
+- `textFeatureSet` (`'bodyContent' | 'heading'`, default: `'bodyContent'`): Controls the editor toolbar
+  - Use `'bodyContent'` for full-featured editing (includes image, emoji, table, embed, video, and more)
+  - Use `'heading'` for a reduced feature set suited to titles and captions (no rich media)
+
+**Fields:**
+- `text` (name set by `textName`): RichTextField for the rich text content
+
+#### Style Fields
+
+**Note:** There are no style fields included with this component. Do not try to import them.
+
+### Module Usage Example
+
+```tsx
+import Text from '@hubspot/cms-component-library/Text';
+
+export default function ArticleModule() {
+  return (
+    <Text fieldPath="bodyText" />
+  );
+}
+```
+
+### Module Fields Example
+
+```tsx
+import { ModuleFields } from '@hubspot/cms-components/fields';
+import Text from '@hubspot/cms-component-library/Text';
+
+export const fields = (
+  <ModuleFields>
+    <Text.ContentFields
+      textLabel="Body text"
+      textName="bodyText"
+      textDefault="<p>Enter your content here.</p>"
+      textFeatureSet="bodyContent"
+    />
+  </ModuleFields>
+);
+```
+
+### Multiple Text Fields in One Module
+
+```tsx
+import { ModuleFields } from '@hubspot/cms-components/fields';
+import Text from '@hubspot/cms-component-library/Text';
+
+export const fields = (
+  <ModuleFields>
+    <Text.ContentFields
+      textLabel="Heading text"
+      textName="headingText"
+      textDefault="<p>Enter your heading.</p>"
+      textFeatureSet="heading"
+    />
+    <Text.ContentFields
+      textLabel="Body text"
+      textName="bodyText"
+      textDefault="<p>Enter your body content.</p>"
+      textFeatureSet="bodyContent"
+    />
+  </ModuleFields>
+);
+
+export default function ArticleModule() {
+  return (
+    <div>
+      <Text fieldPath="headingText" />
+      <Text fieldPath="bodyText" />
+    </div>
+  );
+}
+```
+
+## Styling
+
+### CSS Variables
+
+**Base Styles:**
+- `--hscl-text-color`: Text color applied to the rendered rich text content (default: `currentColor`)
+
+## Accessibility
+
+- **Semantic HTML**: Content is rendered directly from the HubSpot CMS editor output, which produces standard HTML elements (`<p>`, `<h1>`–`<h6>`, `<ul>`, `<ol>`, etc.)
+- **Structured content**: Encourage editors to use proper heading hierarchy and list elements within the rich text editor for screen reader compatibility
+- **Link accessibility**: Links created in the rich text editor will render as native `<a>` elements
+
+## Best Practices
+
+- **Match `fieldPath` to `textName`**: The `fieldPath` prop on the component must match the `textName` prop on `ContentFields` — they reference the same CMS field
+- **Choose the right feature set**: Use `'heading'` for simpler text areas (titles, captions) to keep the editor toolbar uncluttered; use `'bodyContent'` for full article or section content
+- **Style fields**: There are no style fields for this component. Do not try to import them
+- **CSS Variables for theming**: Override `--hscl-text-color` via the `style` prop rather than using CSS selectors that target the component's internals
+- **Multiple fields per module**: You can render multiple `Text` components in one module by giving each a unique `textName` / `fieldPath` pair
+
+## Related Components
+
+- **Button**: Use for call-to-action elements within or adjacent to text content
+- **Link**: Use for standalone clickable text or wrapped content that requires a link without rich text editing

package/components/componentLibrary/Text/types.ts

@@ -0,0 +1,16 @@
+import type { CSSVariables } from '../utils/types.js';
+
+export type TextProps = {
+  fieldPath?: string;
+  className?: string;
+  style?: CSSVariables;
+};
+
+export type TextFeatureSet = 'bodyContent' | 'heading';
+
+export type ContentFieldsProps = {
+  textLabel?: string;
+  textName?: string;
+  textDefault?: string;
+  textFeatureSet?: TextFeatureSet;
+};

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

@@ -7,7 +7,7 @@ This document outlines CSS variable naming conventions, styling patterns, and CS
 **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`, `accordion`)
+- **Component name:** Lowercase component name in camelCase, with name taken from the index.tsx file (e.g., `button`, `icon`, `divider`, `image`, `accordion`, `card`)
 - **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
@@ -19,8 +19,6 @@ This document outlines CSS variable naming conventions, styling patterns, and CS
 --hscl-button-backgroundColor
 --hscl-button-backgroundColor-hover
 --hscl-button-backgroundColor-focus
---hscl-heading-fontSize
---hscl-heading-textAlign
 --hscl-divider-borderColor
 --hscl-icon-fill
 --hscl-card-padding
@@ -47,12 +45,12 @@ This document outlines CSS variable naming conventions, styling patterns, and CS
 
 **Nested/Dynamic Variables:**
 ```typescript
-// Example from Heading component - uses template variables
-'--hscl-heading-font': `var(--hscl-heading-${displayAsValue}-font)`
-'--hscl-heading-fontSize': `var(--hscl-heading-${displayAsValue}-fontSize)`
+// Components can use template variables to dynamically reference nested variables
+'--hscl-component-font': `var(--hscl-component-${variantValue}-font)`
+'--hscl-component-fontSize': `var(--hscl-component-${variantValue}-fontSize)`
 ```
 
-**Note:** When using dynamic variants (like h1, h2, display1), use numbers without underscores (e.g., `display1` not `display_1`).
+**Note:** When using dynamic variants, use numbers without underscores (e.g., `variant1` not `variant_1`).
 
 ## CSS Variables Application
 
@@ -105,15 +103,6 @@ const elementStyle: CSSVariables = {
 ```typescript
 import type { CSSVariables } from '../utils/types.js';
 
-// Heading - dynamic variable references
-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(),
-  }),
-};
-
 // Divider - direct values with units
 const cssVariables: CSSVariables = {
   '--hscl-divider-alignment': getAlignmentCSSVar(alignment),
@@ -235,8 +224,8 @@ Variables can reference other variables for dynamic behavior:
 
 ```typescript
 const cssVariables = {
-  '--hscl-heading-font': `var(--hscl-heading-${displayAsValue}-font)`,
-  '--hscl-heading-fontSize': `var(--hscl-heading-${displayAsValue}-fontSize)`,
+  '--hscl-component-font': `var(--hscl-component-${variantValue}-font)`,
+  '--hscl-component-fontSize': `var(--hscl-component-${variantValue}-fontSize)`,
 };
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubspot/cms-component-library",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "HubSpot CMS React component library for building CMS modules",
   "license": "Apache-2.0",
   "exports": {
@@ -21,9 +21,8 @@
   },
   "type": "module",
   "dependencies": {
-    "@hubspot/cms-components": "^1.2.13",
-    "sass-embedded": "^1.90.0",
-    "tsx": "^4.20.5"
+    "@hubspot/cms-components": "1.2.17",
+    "sass-embedded": "^1.97.3"
   },
   "peerDependencies": {
     "react": "^18.3.1"
@@ -31,6 +30,7 @@
   "devDependencies": {
     "@types/node": "^20.0.0",
     "@vitejs/plugin-react": "4.6.0",
+    "@hubspot/cms-dev-server": "^1.0.0",
     "typescript": "^5.0.0"
   },
   "author": "content-assets",

package/components/componentLibrary/Divider/ContentFields.tsx

@@ -1,63 +0,0 @@
-import { ChoiceField, NumberField } from '@hubspot/cms-components/fields';
-import { ContentFieldsProps } from './types.js';
-
-const ContentFields = ({
-  orientationLabel = 'Orientation',
-  orientationName = 'orientation',
-  orientationDefault = 'horizontal',
-  alignmentLabel = 'Alignment',
-  alignmentName = 'alignment',
-  alignmentDefault = 'stretch',
-  lengthLabel = 'Length',
-  lengthName = 'length',
-  lengthDefault = 100,
-  thicknessLabel = 'Thickness',
-  thicknessName = 'thickness',
-  thicknessDefault = 1,
-}: ContentFieldsProps) => {
-  return (
-    <>
-      <ChoiceField
-        label={orientationLabel}
-        name={orientationName}
-        required={true}
-        choices={[
-          ['horizontal', 'Horizontal'],
-          ['vertical', 'Vertical'],
-        ]}
-        default={orientationDefault}
-      />
-      <ChoiceField
-        label={alignmentLabel}
-        name={alignmentName}
-        required={true}
-        choices={[
-          ['stretch', 'Stretch'],
-          ['start', 'Start'],
-          ['center', 'Center'],
-          ['end', 'End'],
-        ]}
-        default={alignmentDefault}
-      />
-      <NumberField
-        label={lengthLabel}
-        name={lengthName}
-        required={true}
-        suffix="%"
-        min={1}
-        max={100}
-        default={lengthDefault}
-      />
-      <NumberField
-        label={thicknessLabel}
-        name={thicknessName}
-        required={true}
-        suffix="px"
-        min={1}
-        default={thicknessDefault}
-      />
-    </>
-  );
-};
-
-export default ContentFields;

package/components/componentLibrary/Heading/ContentFields.tsx

@@ -1,37 +0,0 @@
-import { ChoiceField, TextField } from '@hubspot/cms-components/fields';
-import type { ContentFieldsProps } from './types.js';
-
-const ContentFields = ({
-  headingTextLabel = 'Heading text',
-  headingTextName = 'headingText',
-  headingTextDefault = 'Heading Text',
-  headingLevelLabel = 'Heading level',
-  headingLevelName = 'headingLevel',
-  headingLevelDefault = 'h1',
-}: ContentFieldsProps) => {
-  return (
-    <>
-      <TextField
-        label={headingTextLabel}
-        name={headingTextName}
-        default={headingTextDefault}
-      />
-      <ChoiceField
-        label={headingLevelLabel}
-        name={headingLevelName}
-        choices={[
-          ['h1', 'h1'],
-          ['h2', 'h2'],
-          ['h3', 'h3'],
-          ['h4', 'h4'],
-          ['h5', 'h5'],
-          ['h6', 'h6'],
-        ]}
-        required={true}
-        default={headingLevelDefault}
-      />
-    </>
-  );
-};
-
-export default ContentFields;

package/components/componentLibrary/Heading/StyleFields.tsx

@@ -1,40 +0,0 @@
-import { AlignmentField, ChoiceField } from '@hubspot/cms-components/fields';
-import type { StyleFieldsProps } from './types.js';
-
-const StyleFields = ({
-  textAlignLabel = 'Heading alignment',
-  textAlignName = 'headingTextAlign',
-  textAlignDefault = 'LEFT',
-  displayAsLabel = 'Display as',
-  displayAsName = 'headingDisplayAs',
-  displayAsDefault = 'h1',
-}: StyleFieldsProps) => {
-  return (
-    <>
-      <AlignmentField
-        label={textAlignLabel}
-        name={textAlignName}
-        alignmentDirection="HORIZONTAL"
-        default={{ horizontal_align: textAlignDefault }}
-      />
-      <ChoiceField
-        label={displayAsLabel}
-        name={displayAsName}
-        choices={[
-          ['h1', 'h1'],
-          ['h2', 'h2'],
-          ['h3', 'h3'],
-          ['h4', 'h4'],
-          ['h5', 'h5'],
-          ['h6', 'h6'],
-          ['display_1', 'Display 1'],
-          ['display_2', 'Display 2'],
-        ]}
-        required={true}
-        default={displayAsDefault}
-      />
-    </>
-  );
-};
-
-export default StyleFields;

package/components/componentLibrary/Heading/index.module.scss

@@ -1,11 +0,0 @@
-.heading {
-  font-family: var(--hscl-heading-font);
-  font-size: var(--hscl-heading-fontSize);
-  font-style: var(--hscl-heading-fontStyle);
-  font-weight: var(--hscl-heading-fontWeight);
-  line-height: var(--hscl-heading-lineHeight);
-  margin-block: var(--hscl-heading-margin);
-  color: var(--hscl-heading-color);
-  text-align: var(--hscl-heading-textAlign);
-}
-

package/components/componentLibrary/Heading/index.tsx

@@ -1,52 +0,0 @@
-import styles from './index.module.scss';
-import ContentFields from './ContentFields.js';
-import StyleFields from './StyleFields.js';
-import cx from '../utils/classname.js';
-import type { CSSVariables } from '../utils/types.js';
-import { HeadingProps } from './types.js';
-
-const HeadingComponent = ({
-  headingLevel,
-  displayAs,
-  textAlign,
-  className = '',
-  style = {},
-  children = 'A clear and bold heading',
-  ...rest
-}: HeadingProps) => {
-  const HeadingLevel = headingLevel;
-  const displayAsValue = displayAs || headingLevel;
-
-  const cssVariables: CSSVariables = {
-    '--hscl-heading-font': `var(--hscl-heading-${displayAsValue}-font)`,
-    '--hscl-heading-fontSize': `var(--hscl-heading-${displayAsValue}-fontSize)`,
-    '--hscl-heading-fontStyle': `var(--hscl-heading-${displayAsValue}-fontStyle)`,
-    '--hscl-heading-fontWeight': `var(--hscl-heading-${displayAsValue}-fontWeight)`,
-    ...(textAlign && {
-      '--hscl-heading-textAlign': textAlign.toLowerCase(),
-    }),
-  };
-
-  const defaultClasses = cx(styles.heading, className);
-
-  return (
-    <HeadingLevel
-      className={defaultClasses}
-      style={{ ...cssVariables, ...style }}
-      {...rest}
-    >
-      {children}
-    </HeadingLevel>
-  );
-};
-
-type HeadingComponentType = typeof HeadingComponent & {
-  ContentFields: typeof ContentFields;
-  StyleFields: typeof StyleFields;
-};
-
-const Heading = HeadingComponent as HeadingComponentType;
-Heading.ContentFields = ContentFields;
-Heading.StyleFields = StyleFields;
-
-export default Heading;

package/components/componentLibrary/Heading/llm.txt

@@ -1,175 +0,0 @@
-# Heading Component
-
-A semantic heading component that renders HTML heading elements (h1-h6) with flexible visual styling and alignment controls, allowing the semantic level to differ from the visual appearance.
-
-## Import path
-```tsx
-import Heading from '@hubspot/cms-component-library/Heading';
-```
-
-## Purpose
-
-The Heading component provides proper semantic structure while maintaining visual design flexibility. It solves the common challenge where semantic HTML hierarchy (h1-h6) needs to differ from visual styling - for example, an h3 element styled to look like an h1. This separation of semantic meaning from visual presentation ensures both accessibility and design consistency.
-
-## Component Structure
-
-```
-Heading/
-├── index.tsx                      # Main component with render logic
-├── types.ts                       # TypeScript type definitions
-├── ContentFields.tsx              # HubSpot field definitions for content
-├── StyleFields.tsx                # HubSpot field definitions for styling
-├── index.module.scss              # CSS module with design tokens
-└── stories/
-    ├── Heading.stories.tsx        # Component usage examples
-    ├── HeadingDecorator.tsx       # Storybook decorator
-    └── HeadingDecorator.module.css # Decorator styles
-```
-
-## Props
-
-```tsx
-{
-  headingLevel: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';  // Semantic HTML level (required)
-  displayAs?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'display_1' | 'display_2';  // Visual style (defaults to headingLevel)
-  textAlign?: 'LEFT' | 'CENTER' | 'RIGHT';  // Text alignment
-  className?: string;  // Additional CSS classes
-  style?: React.CSSProperties;  // Inline styles (including CSS variables)
-  children?: React.ReactNode;  // Heading text content
-}
-```
-
-## Usage Examples
-
-### Basic Heading
-
-```tsx
-import Heading from '@hubspot/cms-component-library/Heading';
-
-<Heading headingLevel="h1">
-  Welcome to Our Site
-</Heading>
-```
-
-### Semantic vs Visual Styling
-
-When you need a lower-level heading to look like a higher-level one:
-
-```tsx
-<Heading
-  headingLevel="h3"  // Semantic: third-level heading
-  displayAs="h1"     // Visual: styled like an h1
->
-  Section Title
-</Heading>
-```
-
-### With Text Alignment
-
-```tsx
-<Heading
-  headingLevel="h2"
-  textAlign="CENTER"
->
-  Centered Heading
-</Heading>
-```
-
-
-## HubSpot CMS Integration
-
-### Field Definitions
-
-#### ContentFields.tsx
-
-```tsx
-<Heading.ContentFields
-  headingTextLabel="Heading text"
-  headingTextName="headingText"
-  headingTextDefault="Heading Text"
-  headingLevelLabel="Heading Level"
-  headingLevelName="headingLevel"
-  headingLevelDefault="h1"
-/>
-```
-
-**Fields:**
-- `headingText`: TextField for heading content
-- `headingLevel`: ChoiceField for semantic level (h1-h6)
-
-#### StyleFields.tsx
-
-```tsx
-<Heading.StyleFields
-  textAlignLabel="Heading text align"
-  textAlignName="headingTextAlign"
-  textAlignDefault="LEFT"
-  displayAsLabel="Display as"
-  displayAsName="headingDisplayAs"
-  displayAsDefault="h1"
-/>
-```
-
-**Fields:**
-- `headingTextAlign`: AlignmentField for text alignment
-- `headingDisplayAs`: ChoiceField for visual style (h1-h6, display_1, display_2)
-
-### Module Usage Example
-
-```tsx
-import Heading from '@hubspot/cms-component-library/Heading';
-
-export default function HeroModule({ fieldValues }) {
-  return (
-    <Heading
-      headingLevel={fieldValues.headingLevel}
-      displayAs={fieldValues.headingDisplayAs}
-      textAlign={fieldValues.headingTextAlign?.horizontal_align}
-    >
-      {fieldValues.headingText}
-    </Heading>
-  );
-}
-```
-
-## Styling
-
-### CSS Variables
-
-The Heading component uses CSS variables for theming and customization:
-
-**Base Styles:**
-- `--hscl-heading-font`: Font family
-- `--hscl-heading-fontSize`: Font size (set by displayAs level)
-- `--hscl-heading-fontStyle`: Font style (set by displayAs level)
-- `--hscl-heading-fontWeight`: Font weight (set by displayAs level)
-- `--hscl-heading-lineHeight`: Line height
-- `--hscl-heading-margin`: Vertical margin (margin-block)
-- `--hscl-heading-color`: Text color
-- `--hscl-heading-textAlign`: Text alignment
-
-**Level-specific Variables:**
-Each heading level has its own design tokens:
-- `--hscl-heading-h1-font`, `--hscl-heading-h1-fontSize`, etc.
-- `--hscl-heading-h2-font`, `--hscl-heading-h2-fontSize`, etc.
-- Through `--hscl-heading-h6-font`, `--hscl-heading-h6-fontSize`, etc.
-- `--hscl-heading-display_1-font`, `--hscl-heading-display_1-fontSize`, etc.
-- `--hscl-heading-display_2-font`, `--hscl-heading-display_2-fontSize`, etc.
-
-## Accessibility
-
-The Heading component follows accessibility best practices:
-
-- **Semantic HTML**: Always renders the appropriate heading element (h1-h6) based on `headingLevel` for proper document structure
-- **Visual Hierarchy Independence**: The `displayAs` prop allows visual styling to differ from semantic structure, ensuring flexibility without breaking accessibility
-- **Proper Nesting**: Ensure headings follow logical order in your document (h1 → h2 → h3, etc.) regardless of visual styling
-- **Screen Readers**: Screen readers announce the semantic level (`headingLevel`), not the visual style
-- **Keyboard Navigation**: Native heading element support for keyboard navigation and focus management
-
-## Best Practices
-
-- **Follow semantic order**: Use headings in logical order (h1 for main title, h2 for sections, h3 for subsections, etc.)
-- **One h1 per page**: Each page should have exactly one h1 element representing the main topic
-- **Use displayAs for visual flexibility**: When you need a different visual style than the semantic level requires, use the `displayAs` prop
-- **Don't skip levels**: Don't jump from h2 to h4; maintain proper hierarchy
-