@hubspot/cms-component-library 0.3.1 → 0.3.3

package/components/componentLibrary/Divider/stories/Divider.stories.tsx

@@ -13,7 +13,7 @@ const meta: Meta<DividerProps> = {
     layout: 'centered',
     docs: {
       description: {
-        component: `The Divider component provides a visual separator between content sections. It supports both horizontal and vertical orientations with customizable styling options including border style, thickness, length, and spacing.`,
+        component: `The Divider component provides a visual separator between content sections. It supports both horizontal and vertical orientations with customizable styling options including line type, thickness, length, alignment, color, and spacing.`,
       },
     },
   },
@@ -26,7 +26,6 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   args: {
     orientation: 'horizontal',
-    alignment: 'stretch',
     borderStyle: 'solid',
     length: 100,
     thickness: 1,
@@ -196,25 +195,37 @@ export const Alignment: Story = {
       <SBContainer addBackground flex>
         <h4>Stretch (Default)</h4>
         <p>Divider stretches to fill available space</p>
-        <Divider length={100} thickness={1} alignment="stretch" />
+        <Divider length={100} thickness={1} />
       </SBContainer>
 
       <SBContainer addBackground flex>
-        <h4>Start</h4>
-        <p>Divider aligns to the start (left for horizontal)</p>
-        <Divider length={50} thickness={1} alignment="start" />
+        <h4>Left</h4>
+        <p>Divider aligns to the left</p>
+        <Divider
+          length={50}
+          thickness={1}
+          alignment={{ horizontal_align: 'LEFT' }}
+        />
       </SBContainer>
 
       <SBContainer addBackground flex>
         <h4>Center</h4>
         <p>Divider aligns to the center</p>
-        <Divider length={50} thickness={1} alignment="center" />
+        <Divider
+          length={50}
+          thickness={1}
+          alignment={{ horizontal_align: 'CENTER' }}
+        />
       </SBContainer>
 
       <SBContainer addBackground flex>
-        <h4>End</h4>
-        <p>Divider aligns to the end (right for horizontal)</p>
-        <Divider length={50} thickness={1} alignment="end" />
+        <h4>Right</h4>
+        <p>Divider aligns to the right</p>
+        <Divider
+          length={50}
+          thickness={1}
+          alignment={{ horizontal_align: 'RIGHT' }}
+        />
       </SBContainer>
     </SBContainer>
   ),
@@ -323,8 +334,8 @@ export const VerticalAlignment: Story = {
   render: () => (
     <SBContainer flex direction="column" gap="large">
       <SBContainer addBackground>
-        <h4>Start</h4>
-        <p>Divider aligns to the start (top for vertical)</p>
+        <h4>Top</h4>
+        <p>Divider aligns to the top</p>
         <div
           style={{
             display: 'flex',
@@ -337,7 +348,7 @@ export const VerticalAlignment: Story = {
             orientation="vertical"
             length={50}
             thickness={1}
-            alignment="start"
+            alignment={{ vertical_align: 'TOP' }}
             spacing="16px"
           />
           <span>Right</span>
@@ -345,8 +356,8 @@ export const VerticalAlignment: Story = {
       </SBContainer>
 
       <SBContainer addBackground>
-        <h4>Center</h4>
-        <p>Divider aligns to the center</p>
+        <h4>Middle</h4>
+        <p>Divider aligns to the middle</p>
         <div
           style={{
             display: 'flex',
@@ -359,7 +370,7 @@ export const VerticalAlignment: Story = {
             orientation="vertical"
             length={50}
             thickness={1}
-            alignment="center"
+            alignment={{ vertical_align: 'MIDDLE' }}
             spacing="16px"
           />
           <span>Right</span>
@@ -367,8 +378,8 @@ export const VerticalAlignment: Story = {
       </SBContainer>
 
       <SBContainer addBackground>
-        <h4>End</h4>
-        <p>Divider aligns to the end (bottom for vertical)</p>
+        <h4>Bottom</h4>
+        <p>Divider aligns to the bottom</p>
         <div
           style={{
             display: 'flex',
@@ -381,7 +392,7 @@ export const VerticalAlignment: Story = {
             orientation="vertical"
             length={50}
             thickness={1}
-            alignment="end"
+            alignment={{ vertical_align: 'BOTTOM' }}
             spacing="16px"
           />
           <span>Right</span>

package/components/componentLibrary/Divider/types.ts

@@ -1,45 +1,56 @@
+import type {
+  AlignmentFieldDefaults,
+  ColorFieldDefaults,
+} from '@hubspot/cms-components/fields';
 import type { CSSVariables } from '../utils/types.js';
 
-export type DividerOrientation = 'horizontal' | 'vertical';
+type AlignmentValue = typeof AlignmentFieldDefaults;
+type ColorValue = typeof ColorFieldDefaults;
 
-export type DividerAlignment = 'stretch' | 'start' | 'center' | 'end';
+export type DividerOrientation = 'horizontal' | 'vertical';
 
 export type DividerBorderStyle = 'solid' | 'dotted' | 'dashed' | 'double';
 
+export type DividerAlignmentDirection = 'HORIZONTAL' | 'VERTICAL';
+
 type PixelValue = `${number}px`;
 
 export type DividerProps = {
   orientation?: DividerOrientation;
-  alignment?: DividerAlignment;
+  alignment?: AlignmentValue;
   spacing?: PixelValue;
   borderStyle?: DividerBorderStyle;
   length?: number;
   thickness?: number;
+  color?: ColorValue;
   variant?: 'primary' | 'secondary' | 'tertiary';
   className?: string;
   style?: CSSVariables;
 };
 
-export type ContentFieldsProps = {
-  orientationLabel?: string;
-  orientationName?: string;
-  orientationDefault?: string;
-  alignmentLabel?: string;
-  alignmentName?: string;
-  alignmentDefault?: string;
-  lengthLabel?: string;
-  lengthName?: string;
-  lengthDefault?: number;
-  thicknessLabel?: string;
-  thicknessName?: string;
-  thicknessDefault?: number;
-};
+export type StyleFieldName =
+  | 'borderStyle'
+  | 'color'
+  | 'thickness'
+  | 'length'
+  | 'alignment';
 
 export type StyleFieldsProps = {
-  spacingLabel?: string;
-  spacingName?: string;
-  spacingDefault?: string;
+  hideFields?: StyleFieldName[];
   borderStyleLabel?: string;
   borderStyleName?: string;
   borderStyleDefault?: string;
+  thicknessLabel?: string;
+  thicknessName?: string;
+  thicknessDefault?: number;
+  lengthLabel?: string;
+  lengthName?: string;
+  lengthDefault?: number;
+  alignmentLabel?: string;
+  alignmentName?: string;
+  alignmentDefault?: AlignmentValue;
+  alignmentDirection?: DividerAlignmentDirection;
+  colorLabel?: string;
+  colorName?: string;
+  colorDefault?: ColorValue;
 };

package/components/componentLibrary/Icon/StyleFields.tsx

@@ -0,0 +1,69 @@
+import { ColorField, ChoiceField } from '@hubspot/cms-components/fields';
+import type { StyleFieldsProps } from './types.js';
+
+const StyleFields = ({
+  hideFields = [],
+  iconColorLabel = 'Icon color',
+  iconColorName = 'iconColor',
+  iconColorDefault = { color: '#A8A8A8', opacity: 100 },
+  iconBackgroundColorLabel = 'Background color',
+  iconBackgroundColorName = 'iconBackgroundColor',
+  iconBackgroundColorDefault = { color: '#2C2C2C', opacity: 100 },
+  iconShapeLabel = 'Icon shape',
+  iconShapeName = 'iconShape',
+  iconShapeDefault = '0px',
+  iconSizeLabel = 'Icon size',
+  iconSizeName = 'iconSize',
+  iconSizeDefault = '16',
+}: StyleFieldsProps) => {
+  return (
+    <>
+      {!hideFields.includes('iconColor') && (
+        <ColorField
+          label={iconColorLabel}
+          name={iconColorName}
+          default={iconColorDefault}
+          showOpacity={false}
+        />
+      )}
+      {!hideFields.includes('iconBackgroundColor') && (
+        <ColorField
+          label={iconBackgroundColorLabel}
+          name={iconBackgroundColorName}
+          default={iconBackgroundColorDefault}
+          showOpacity={false}
+        />
+      )}
+      {!hideFields.includes('iconShape') && (
+        <ChoiceField
+          label={iconShapeLabel}
+          name={iconShapeName}
+          display="buttons"
+          preset="icon_shape"
+          choices={[
+            ['0px', 'Square'],
+            ['8px', 'Rounded'],
+            ['100%', 'Circle'],
+          ]}
+          default={iconShapeDefault}
+          required={true}
+        />
+      )}
+      {!hideFields.includes('iconSize') && (
+        <ChoiceField
+          label={iconSizeLabel}
+          name={iconSizeName}
+          choices={[
+            ['16', 'Small (16x16 px)'],
+            ['24', 'Medium (24x24 px)'],
+            ['32', 'Large (32x32 px)'],
+          ]}
+          default={iconSizeDefault}
+          required={true}
+        />
+      )}
+    </>
+  );
+};
+
+export default StyleFields;

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

@@ -7,3 +7,14 @@
   width: var(--hscl-icon-size);
   height: var(--hscl-icon-size);
 }
+
+.iconBackground {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  justify-self: flex-start;
+  align-self: flex-start;
+  background-color: var(--hscl-iconBackground-backgroundColor, transparent);
+  padding: var(--hscl-iconBackground-padding, 12px);
+  border-radius: var(--hscl-iconBackground-shape, 0px);
+}

package/components/componentLibrary/Icon/index.tsx

@@ -1,6 +1,7 @@
 import styles from './index.module.scss';
 import { Icon as CMSIcon } from '@hubspot/cms-components';
 import ContentFields from './ContentFields.js';
+import StyleFields from './StyleFields.js';
 import cx from '../utils/classname.js';
 import type { CSSVariables } from '../utils/types.js';
 import { IconProps } from './types.js';
@@ -14,18 +15,22 @@ const IconComponent = ({
   purpose = 'DECORATIVE',
   title = '',
   fill,
+  showIconBackground = false,
+  iconBackgroundColor,
+  iconBackgroundPadding,
+  iconBackgroundShape,
 }: IconProps) => {
   if (!showIcon) return null;
 
-  const defaultClasses = styles.icon;
-  const combinedClasses = cx(defaultClasses, className);
-
   const cssVariables: CSSVariables = {
     '--hscl-icon-size': `${size}px`,
     ...(fill && { '--hscl-icon-fill': fill }),
   };
 
-  return (
+  const defaultClasses = styles.icon;
+  const combinedClasses = cx(defaultClasses, className);
+
+  const icon = (
     <CMSIcon
       fieldPath={fieldPath}
       height={size}
@@ -35,13 +40,35 @@ const IconComponent = ({
       title={title}
     />
   );
+
+  if (!showIconBackground) return icon;
+
+  const backgroundCssVariables: CSSVariables = {
+    ...(iconBackgroundColor && {
+      '--hscl-iconBackground-backgroundColor': iconBackgroundColor,
+    }),
+    ...(iconBackgroundPadding && {
+      '--hscl-iconBackground-padding': `${iconBackgroundPadding}px`,
+    }),
+    ...(iconBackgroundShape && {
+      '--hscl-iconBackground-shape': iconBackgroundShape,
+    }),
+  };
+
+  return (
+    <div className={styles.iconBackground} style={backgroundCssVariables}>
+      {icon}
+    </div>
+  );
 };
 
 type IconComponentType = typeof IconComponent & {
   ContentFields: typeof ContentFields;
+  StyleFields: typeof StyleFields;
 };
 
 const Icon = IconComponent as IconComponentType;
 Icon.ContentFields = ContentFields;
+Icon.StyleFields = StyleFields;
 
 export default Icon;

package/components/componentLibrary/Icon/llm.txt

@@ -9,7 +9,7 @@ import Icon from '@hubspot/cms-component-library/Icon';
 
 ## Purpose
 
-The Icon component wraps the native HubSpot CMS Icon component to provide a consistent interface for rendering icons with customizable styling and accessibility options. It simplifies icon usage in HubSpot CMS projects by handling common configuration patterns like sizing, color theming through CSS variables, and proper accessibility attributes (SEMANTIC vs DECORATIVE purpose).
+The Icon component wraps the native HubSpot CMS Icon component to provide a consistent interface for rendering icons with customizable styling and accessibility options. It simplifies icon usage in HubSpot CMS projects by handling common configuration patterns like sizing, color theming through CSS variables, optional background containers, and proper accessibility attributes (SEMANTIC vs DECORATIVE purpose).
 
 ## Component Structure
 
@@ -18,6 +18,7 @@ Icon/
 ├── index.tsx                     # Main component with render logic
 ├── types.ts                      # TypeScript type definitions
 ├── ContentFields.tsx             # HubSpot field definitions for icon content
+├── StyleFields.tsx               # HubSpot field definitions for icon styles
 ├── index.module.scss             # CSS module with design tokens
 └── stories/
     ├── Icon.stories.tsx          # Component usage examples
@@ -29,7 +30,7 @@ Icon/
 
 ### Icon (Main Component)
 
-**Purpose:** Renders an icon with configurable size, color, and accessibility properties.
+**Purpose:** Renders an icon with configurable size, color, background, and accessibility properties.
 
 **Props:**
 ```tsx
@@ -42,6 +43,10 @@ Icon/
   showIcon?: boolean;                              // Toggle icon visibility (default: true)
   purpose?: 'SEMANTIC' | 'DECORATIVE';            // Icon accessibility role (default: 'DECORATIVE')
   title?: string;                                  // Icon title for screen readers (use with SEMANTIC)
+  showIconBackground?: boolean;                    // Renders a centered background div behind the icon (default: false)
+  iconBackgroundColor?: string;                    // Background div color (used when showIconBackground is true)
+  iconBackgroundPadding?: number;                  // Padding around the icon inside the background div in px (default: 12)
+  iconBackgroundShape?: string;                    // Border-radius of the background div, e.g. '0px', '8px', '100%' (default: 0px)
 }
 ```
 
@@ -89,6 +94,19 @@ import Icon from '@hubspot/cms-component-library/Icon';
 />
 ```
 
+### Icon with Background
+
+```tsx
+<Icon
+  fieldPath="icon"
+  size={24}
+  showIconBackground={true}
+  iconBackgroundColor="#2C2C2C"
+  iconBackgroundPadding={16}
+  iconBackgroundShape="100%"
+/>
+```
+
 ## HubSpot CMS Integration
 
 ### Field Definitions
@@ -115,9 +133,21 @@ Configurable props for icon selection and visibility:
 - `icon`: IconField for selecting the icon
 - `showIcon`: BooleanField toggle for icon visibility (optional, enabled with `addIconToggle={true}`)
 
-#### Style Fields
+#### StyleFields
 
-**Note:** There are no style fields included with this component. Do not try to import them.
+Configurable props for icon appearance:
+
+```tsx
+<Icon.StyleFields />
+```
+
+**Fields:**
+- `iconColor`: ColorField for the icon fill color
+- `iconBackgroundColor`: ColorField for the background div color
+- `iconShape`: ChoiceField for the background border-radius (`'0px'` Square, `'8px'` Rounded, `'100%'` Circle)
+- `iconSize`: ChoiceField for icon size (16px Small, 24px Medium, 32px Large)
+
+All fields support `label`, `name`, and `default` customization props, and can be hidden via `hideFields`.
 
 ### Module Usage Example
 
@@ -128,8 +158,12 @@ export default function IconModule({ fieldValues }) {
   return (
     <Icon
       fieldPath="icon"
-      size={fieldValues.iconSize || 24}
+      size={Number(fieldValues.style?.iconSize) || 24}
       showIcon={fieldValues.showIcon}
+      fill={fieldValues.style?.iconColor?.color}
+      showIconBackground={fieldValues.style?.showIconBackground}
+      iconBackgroundColor={fieldValues.style?.iconBackgroundColor?.color}
+      iconBackgroundShape={fieldValues.style?.iconShape}
       purpose="DECORATIVE"
     />
   );
@@ -139,14 +173,15 @@ export default function IconModule({ fieldValues }) {
 ### Module Fields Example
 
 ```tsx
-import { ModuleFields } from '@hubspot/cms-components/fields';
+import { ModuleFields, FieldGroup } from '@hubspot/cms-components/fields';
 import Icon from '@hubspot/cms-component-library/Icon';
 
 export const fields = (
   <ModuleFields>
-    <Icon.ContentFields
-      addIconToggle={true}
-    />
+    <Icon.ContentFields addIconToggle={true} />
+    <FieldGroup name="style" label="Style" tab="STYLE">
+      <Icon.StyleFields />
+    </FieldGroup>
   </ModuleFields>
 );
 ```
@@ -161,6 +196,11 @@ The Icon component uses CSS variables for theming and customization:
 - `--hscl-icon-fill`: Icon fill color (default: currentColor)
 - `--hscl-icon-size`: Icon width and height (set automatically from the `size` prop)
 
+**Background Styles (applied when `showIconBackground` is true):**
+- `--hscl-iconBackground-backgroundColor`: Background div color
+- `--hscl-iconBackground-padding`: Padding around the icon inside the background div (default: 12px)
+- `--hscl-iconBackground-shape`: Border-radius of the background div (default: 0px)
+
 
 ## Accessibility
 
@@ -179,4 +219,4 @@ The Icon component follows accessibility best practices:
 - **Use CSS variables for theming**: Override `--hscl-icon-fill` for consistent color theming across your application
 - **Size appropriately**: Common sizes are 12px (small), 16px (default inline), 24px (medium), 32px (large), 48px (extra large)
 - **Field path**: The `fieldPath` prop should match the field name defined in ContentFields
-- **Style fields**: There are no style fields in this component. Do not try to import them.
+- **Background shape**: The `iconShape` StyleField value maps directly to `iconBackgroundShape` on the component — pass it through as-is

package/components/componentLibrary/Icon/types.ts

@@ -1,8 +1,11 @@
 import {
   IconFieldDefaults,
   BooleanFieldDefaults,
+  ColorFieldDefaults,
 } from '@hubspot/cms-components/fields';
 
+type ColorFieldValue = typeof ColorFieldDefaults;
+
 export type IconPurpose = 'SEMANTIC' | 'DECORATIVE';
 
 export type IconProps = {
@@ -14,6 +17,10 @@ export type IconProps = {
   showIcon?: boolean;
   purpose?: IconPurpose;
   title?: string;
+  showIconBackground?: boolean;
+  iconBackgroundColor?: string;
+  iconBackgroundPadding?: number;
+  iconBackgroundShape?: string;
 };
 
 type IconToggleProps = {
@@ -36,3 +43,25 @@ export type IconContentFieldsWithToggleProps =
 export type ContentFieldsProps =
   | IconContentFieldsWithToggleProps
   | IconContentFieldsWithoutToggleProps;
+
+export type StyleFieldName =
+  | 'iconColor'
+  | 'iconBackgroundColor'
+  | 'iconShape'
+  | 'iconSize';
+
+export type StyleFieldsProps = {
+  hideFields?: StyleFieldName[];
+  iconColorLabel?: string;
+  iconColorName?: string;
+  iconColorDefault?: ColorFieldValue;
+  iconBackgroundColorLabel?: string;
+  iconBackgroundColorName?: string;
+  iconBackgroundColorDefault?: ColorFieldValue;
+  iconShapeLabel?: string;
+  iconShapeName?: string;
+  iconShapeDefault?: string;
+  iconSizeLabel?: string;
+  iconSizeName?: string;
+  iconSizeDefault?: string;
+};

package/components/componentLibrary/Text/ContentFields.tsx

@@ -0,0 +1,66 @@
+import {
+  RichTextField,
+  RichTextFieldType,
+} from '@hubspot/cms-components/fields';
+import type { ContentFieldsProps } from './types.js';
+
+// To do: These are placeholders - we can refine and add more after some UX feedback and further discussion
+
+const headingEnabledFeatures: RichTextFieldType['enabledFeatures'] = [
+  'block',
+  'alignment',
+  'indents',
+  'lists',
+  'standard_emphasis',
+  'advanced_emphasis',
+  'link',
+  'personalize',
+  'nonbreaking_space',
+  'source_code',
+  'visual_blocks',
+];
+
+const bodyContentEnabledFeatures: RichTextFieldType['enabledFeatures'] = [
+  'block',
+  'alignment',
+  'indents',
+  'lists',
+  'standard_emphasis',
+  'advanced_emphasis',
+  'link',
+  'image',
+  'emoji',
+  'table',
+  'personalize',
+  'cta',
+  'embed',
+  'video',
+  'charmap',
+  'anchor',
+  'nonbreaking_space',
+  'source_code',
+  'visual_blocks',
+];
+
+const featureSetMap = {
+  bodyContent: bodyContentEnabledFeatures,
+  heading: headingEnabledFeatures,
+};
+
+const ContentFields = ({
+  textLabel = 'Text',
+  textName = 'text',
+  textDefault = '<p>Text goes here.</p>',
+  textFeatureSet = 'bodyContent',
+}: ContentFieldsProps) => {
+  return (
+    <RichTextField
+      label={textLabel}
+      name={textName}
+      default={textDefault}
+      enabledFeatures={featureSetMap[textFeatureSet]}
+    />
+  );
+};
+
+export default ContentFields;

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

@@ -0,0 +1,3 @@
+.text {
+  color: var(--hscl-text-color, currentColor);
+}

package/components/componentLibrary/Text/index.tsx

@@ -0,0 +1,27 @@
+import { RichText } from '@hubspot/cms-components';
+import styles from './index.module.scss';
+import ContentFields from './ContentFields.js';
+import cx from '../utils/classname.js';
+import { TextProps } from './types.js';
+
+const TextComponent = ({
+  fieldPath,
+  className = '',
+  style = {},
+}: TextProps) => {
+  const defaultClasses = styles.text;
+  const combinedClasses = cx(defaultClasses, className);
+
+  return (
+    <RichText fieldPath={fieldPath} className={combinedClasses} style={style} />
+  );
+};
+
+type TextComponentType = typeof TextComponent & {
+  ContentFields: typeof ContentFields;
+};
+
+const Text = TextComponent as TextComponentType;
+Text.ContentFields = ContentFields;
+
+export default Text;