@hubspot/cms-component-library 0.3.4 → 0.3.6

package/components/componentLibrary/Accordion/AccordionTitle/ContentFields.tsx

@@ -1,31 +1,13 @@
-import { TextField, ChoiceField } from '@hubspot/cms-components/fields';
+import { TextField } from '@hubspot/cms-components/fields';
 import type { ContentFieldsProps } from './types.js';
 
 const ContentFields = ({
   titleLabel = 'Title',
   titleName = 'title',
   titleDefault = 'Accordion Title',
-  iconLabel = 'Icon',
-  iconName = 'icon',
-  iconDefault = 'chevron',
 }: ContentFieldsProps) => {
   return (
-    <>
-      <ChoiceField
-        label={iconLabel}
-        name={iconName}
-        display="buttons"
-        choices={[
-          ['chevron', 'Chevron'],
-          ['plus', 'Plus'],
-          ['caret', 'Caret'],
-        ]}
-        preset="expand_icon"
-        required={false}
-        default={iconDefault}
-      />
-      <TextField label={titleLabel} name={titleName} default={titleDefault} />
-    </>
+    <TextField label={titleLabel} name={titleName} default={titleDefault} />
   );
 };
 

package/components/componentLibrary/Accordion/AccordionTitle/StyleFields.tsx

@@ -0,0 +1,26 @@
+import { ChoiceField } from '@hubspot/cms-components/fields';
+import type { StyleFieldsProps } from './types.js';
+
+const StyleFields = ({
+  iconLabel = 'Icon',
+  iconName = 'icon',
+  iconDefault = 'chevron',
+}: StyleFieldsProps) => {
+  return (
+    <ChoiceField
+      label={iconLabel}
+      name={iconName}
+      display="buttons"
+      choices={[
+        ['caret', 'Caret'],
+        ['chevron', 'Chevron'],
+        ['plus', 'Plus'],
+      ]}
+      preset="expand_icon"
+      required={false}
+      default={iconDefault}
+    />
+  );
+};
+
+export default StyleFields;

package/components/componentLibrary/Accordion/AccordionTitle/index.tsx

@@ -1,5 +1,6 @@
 import styles from './index.module.scss';
 import ContentFields from './ContentFields.js';
+import StyleFields from './StyleFields.js';
 import cx from '../../utils/classname.js';
 import { AccordionTitleProps } from './types.js';
 import { ChevronIcon, PlusIcon, MinusIcon, CaretIcon } from './icons.js';
@@ -39,9 +40,11 @@ const AccordionTitleComponent = ({
 
 type AccordionTitleComponentType = typeof AccordionTitleComponent & {
   ContentFields: typeof ContentFields;
+  StyleFields: typeof StyleFields;
 };
 
 const AccordionTitle = AccordionTitleComponent as AccordionTitleComponentType;
 AccordionTitle.ContentFields = ContentFields;
+AccordionTitle.StyleFields = StyleFields;
 
 export default AccordionTitle;

package/components/componentLibrary/Accordion/AccordionTitle/types.ts

@@ -11,6 +11,9 @@ export type ContentFieldsProps = {
   titleLabel?: string;
   titleName?: string;
   titleDefault?: string;
+};
+
+export type StyleFieldsProps = {
   iconLabel?: string;
   iconName?: string;
   iconDefault?: AccordionIconType;

package/components/componentLibrary/Accordion/llm.txt

@@ -52,7 +52,8 @@ Accordion/
 ├── AccordionTitle/
 │   ├── index.tsx                 # AccordionTitle component
 │   ├── types.ts                  # AccordionTitle TypeScript types
-│   ├── ContentFields.tsx         # HubSpot field definitions for title/icon
+│   ├── ContentFields.tsx         # HubSpot field definitions for title text
+│   ├── StyleFields.tsx           # HubSpot field definitions for icon
 │   ├── icons.tsx                 # SVG icon components (Chevron, Plus, Minus)
 │   └── index.module.scss         # CSS module for title styling
 ├── AccordionContent/
@@ -228,13 +229,25 @@ Configurable props for variant selection:
 
 #### AccordionTitle.ContentFields
 
-Configurable props for title text and icon:
+Configurable props for title text:
 
 ```tsx
 <AccordionTitle.ContentFields
   titleName="title"
   titleLabel="Title"
   titleDefault="Accordion Title"
+/>
+```
+
+**Fields:**
+- `title`: TextField for accordion title text
+
+#### AccordionTitle.StyleFields
+
+Configurable props for icon style:
+
+```tsx
+<AccordionTitle.StyleFields
   iconName="icon"
   iconLabel="Icon"
   iconDefault="chevron"
@@ -242,7 +255,6 @@ Configurable props for title text and icon:
 ```
 
 **Fields:**
-- `title`: TextField for accordion title text
 - `icon`: ChoiceField for selecting icon type (caret, chevron, plus)
 
 #### AccordionContent.ContentFields
@@ -275,11 +287,11 @@ import { AccordionIconType } from '@hubspot/cms-component-library/Accordion/Acco
 type FAQModuleProps = {
   style?: {
     variant?: AccordionVariant;
+    icon?: AccordionIconType;
   };
   accordionItems?: Array<{
     title?: string;
     content?: string;
-    icon?: AccordionIconType;
   }>;
 };
 
@@ -288,10 +300,11 @@ export const Component = ({
   accordionItems = [],
 }: FAQModuleProps) => {
   const variant = style?.variant;
+  const icon = style?.icon;
 
   return (
     <Accordion>
-      {accordionItems.map(({ title, content, icon }, index) => (
+      {accordionItems.map(({ title, content }, index) => (
         <AccordionItem key={index} variant={variant}>
           <AccordionTitle icon={icon}>{title}</AccordionTitle>
           <AccordionContent>{content}</AccordionContent>
@@ -326,7 +339,6 @@ import {
 const defaultItem = {
   title: 'Accordion Title',
   content: '<p>Accordion content goes here. You can add multiple lines of text.</p>',
-  icon: 'chevron',
 };
 
 export const fields = (
@@ -342,6 +354,7 @@ export const fields = (
     </RepeatedFieldGroup>
     <FieldGroup label="Style" name="style" tab="STYLE">
       <AccordionItem.StyleFields />
+      <AccordionTitle.StyleFields />
     </FieldGroup>
   </ModuleFields>
 );
@@ -426,7 +439,7 @@ The Accordion component follows accessibility best practices:
 - **Gap selection**: Use any valid CSS length value (e.g., '8px', '16px', '24px', '48px') for spacing between items
 - **Dynamic rendering**: Always provide unique `key` props when mapping arrays to AccordionItems
 - **Rich content**: AccordionContent supports any HTML content including lists, paragraphs, images, and nested components
-- **Prefer library components**: When adding content inside AccordionContent, prefer using library components (e.g., `List`, `Heading`) over raw HTML elements for consistent theming and styling
+- **Prefer library components**: When adding content inside AccordionContent, prefer using library components (e.g., `List`, `Text` with `textFeatureSet="heading"` for headings) over raw HTML elements for consistent theming and styling
 - **CSS Variables**: Override design tokens using CSS variables rather than hardcoding values
 - **Single responsibility**: Keep each accordion item focused on one topic for better UX
 

package/components/componentLibrary/Card/llm.txt

@@ -182,4 +182,4 @@ The Card component follows accessibility best practices:
 
 - **Flex**: Use for arranging cards in flexible layouts
 - **Grid**: Use for creating responsive card grids
-- **Heading**: Commonly used for card titles
+- **Text**: Use with `textFeatureSet="heading"` for editable card titles

package/components/componentLibrary/Form/ContentFields.tsx

@@ -0,0 +1,19 @@
+import { FormField } from '@hubspot/cms-components/fields';
+import { ContentFieldsProps } from './types.js';
+
+const ContentFields = ({
+  formIdLabel = 'Form',
+  formIdName = 'form',
+  formIdDefault = {},
+}: ContentFieldsProps) => {
+  return (
+    <FormField
+      label={formIdLabel}
+      name={formIdName}
+      embedVersions={['v4', 'v3', 'v2']}
+      default={formIdDefault}
+    />
+  );
+};
+
+export default ContentFields;

package/components/componentLibrary/Form/index.tsx

@@ -0,0 +1,28 @@
+// @ts-expect-error -- ?island not typed
+import FormIsland from './islands/FormIsland.js?island';
+// @ts-expect-error -- ?island not typed
+import LegacyFormIsland from './islands/LegacyFormIsland.js?island';
+import { FormProps } from './types.js';
+import { Island } from '@hubspot/cms-components';
+import ContentFields from './ContentFields.js';
+
+const FormComponent = ({
+  formField,
+  formId,
+  formVersion,
+  ...rest
+}: FormProps) => {
+  const resolvedFormId = formField != null ? formField.form_id : formId;
+  const FormModule = formVersion === 'v4' ? FormIsland : LegacyFormIsland;
+
+  return <Island module={FormModule} formId={resolvedFormId} {...rest} />;
+};
+
+type FormComponentType = typeof FormComponent & {
+  ContentFields: typeof ContentFields;
+};
+
+const Form = FormComponent as FormComponentType;
+Form.ContentFields = ContentFields;
+
+export default Form;

package/components/componentLibrary/Form/islands/FormIsland.tsx

@@ -0,0 +1,54 @@
+import { useEffect } from 'react';
+import { FormProps } from '../types.js';
+import { getHubID, getHSEnv } from '@hubspot/cms-components';
+
+const getScriptSrc = (portalId: number, env: string) => {
+  const host = env === 'qa' ? 'js.hsformsqa.net' : 'js.hsforms.net';
+  return `https://${host}/forms/embed/developer/${portalId}.js`;
+};
+
+const FormIsland = ({ formId }: FormProps) => {
+  const portalId = getHubID();
+  const resolvedEnv = getHSEnv();
+
+  useEffect(() => {
+    if (!formId || !portalId) {
+      return;
+    }
+
+    const scriptSrc = getScriptSrc(portalId, resolvedEnv);
+    const existingScript = document.querySelector(`script[src="${scriptSrc}"]`);
+
+    if (existingScript) {
+      return;
+    }
+
+    const script = document.createElement('script');
+    script.src = scriptSrc;
+    document.head.appendChild(script);
+
+    return () => {
+      script.remove();
+    };
+  }, [formId, portalId, resolvedEnv]);
+
+  if (!formId || !portalId) {
+    return null;
+  }
+
+  /*
+<script src="https://js.hsformsqa.net/forms/embed/102771136.js" defer></script>
+<div class="hs-form-frame" data-env="qa" data-region="na1" data-form-id="53e5b258-4526-4012-9274-8bbe23ab2d09" data-portal-id="102771136"></div>
+*/
+
+  return (
+    <div
+      className="hs-form-frame"
+      data-form-id={formId}
+      data-portal-id={portalId}
+      data-env={resolvedEnv}
+    />
+  );
+};
+
+export default FormIsland;

package/components/componentLibrary/Form/islands/LegacyFormIsland.tsx

@@ -0,0 +1,77 @@
+import { useEffect, useId } from 'react';
+import { FormProps } from '../types.js';
+import { getHubID, getHSEnv } from '@hubspot/cms-components';
+
+declare global {
+  interface Window {
+    hbspt?: {
+      forms: {
+        create: (options: {
+          portalId: number;
+          formId: string;
+          env: 'qa' | 'prod';
+          target: string;
+        }) => void;
+      };
+    };
+  }
+}
+
+const getScriptSrc = (env: string) => {
+  const host = env === 'qa' ? 'js.hsformsqa.net' : 'js.hsforms.net';
+  return `//${host}/forms/embed/v2.js`;
+};
+
+const LegacyFormIsland = ({ formId }: FormProps) => {
+  const portalId = getHubID();
+  const resolvedEnv = getHSEnv();
+  const rawId = useId();
+  const containerId = `hs-legacy-form-${rawId.replace(/:/g, '')}`;
+
+  useEffect(() => {
+    if (!formId || !portalId) {
+      return;
+    }
+
+    const scriptSrc = getScriptSrc(resolvedEnv);
+
+    const createForm = () => {
+      window.hbspt?.forms.create({
+        portalId,
+        formId,
+        env: resolvedEnv,
+        target: `#${containerId}`,
+      });
+    };
+
+    const existingScript = document.querySelector(`script[src="${scriptSrc}"]`);
+
+    if (existingScript) {
+      if (window.hbspt) {
+        createForm();
+      } else {
+        existingScript.addEventListener('load', createForm);
+        return () => existingScript.removeEventListener('load', createForm);
+      }
+      return;
+    }
+
+    const script = document.createElement('script');
+    script.src = scriptSrc;
+    script.addEventListener('load', createForm);
+    document.head.appendChild(script);
+
+    return () => {
+      script.removeEventListener('load', createForm);
+      script.remove();
+    };
+  }, [formId, portalId, resolvedEnv, containerId]);
+
+  if (!formId || !portalId) {
+    return null;
+  }
+
+  return <div id={containerId} />;
+};
+
+export default LegacyFormIsland;

package/components/componentLibrary/Form/islands/index.module.scss

@@ -0,0 +1,3 @@
+.form {
+  width: var(--hscl-form-width, 100%);
+}

package/components/componentLibrary/Form/types.ts

@@ -0,0 +1,21 @@
+import { FormFieldDefaults } from '@hubspot/cms-components/fields';
+
+export type FormProps = FormPropsWithField | FormPropsWithoutField;
+
+export type FormPropsWithoutField = {
+  formField?: never;
+  formId: string;
+  formVersion: 'v4' | 'v3' | 'v2' | '';
+};
+
+export type FormPropsWithField = {
+  formField: typeof FormFieldDefaults;
+  formId?: never;
+  formVersion?: never;
+};
+
+export type ContentFieldsProps = {
+  formIdLabel?: string;
+  formIdName?: string;
+  formIdDefault?: typeof FormFieldDefaults;
+};

package/components/componentLibrary/Grid/llm.txt

@@ -109,13 +109,13 @@ Grid/
 
 **Purpose:** Wraps grid children to control their precise placement, spanning, and alignment within the Grid container. Can render as any HTML element or custom React component while maintaining grid positioning control.
 
-**Key Feature:** The `as` prop is polymorphic - it accepts both HTML element strings ('div', 'section', etc.) and React component references (Button, Heading, custom components). GridItem handles grid placement while passing through all other props to the underlying component.
+**Key Feature:** The `as` prop is polymorphic - it accepts both HTML element strings ('div', 'section', etc.) and React component references (Button, Text, custom components). GridItem handles grid placement while passing through all other props to the underlying component.
 
 **Props:**
 ```tsx
 {
   as?: React.ElementType;  // Any HTML element or React component (default: 'div')
-                            // Examples: 'div', 'article', Button, Heading, CustomComponent
+                            // Examples: 'div', 'article', Button, Text, CustomComponent
   gridColumn?: string;  // Grid column placement (e.g., '1 / 3', 'span 2', '2')
   gridColumnMd?: string;  // Grid column placement at tablet breakpoint (768px+)
   gridColumnLg?: string;  // Grid column placement at desktop breakpoint (1024px+)
@@ -148,7 +148,7 @@ GridItem's `as` prop provides flexibility in rendering while maintaining grid co
 2. **React Components**: Pass component references directly
    ```tsx
    <GridItem as={Button} buttonType="primary">Click me</GridItem>
-   <GridItem as={Heading} headingLevel="h2">Title</GridItem>
+   <GridItem as={Text} fieldPath="title" />
    ```
 
 3. **Prop Pass-Through**: All props beyond GridItem's own props are forwarded to the underlying component
@@ -158,10 +158,8 @@ GridItem's `as` prop provides flexibility in rendering while maintaining grid co
      Link Button
    </GridItem>
 
-   {/* Heading-specific props are passed through */}
-   <GridItem as={Heading} headingLevel="h2" displayAs="h1">
-     Styled Heading
-   </GridItem>
+   {/* Text-specific props are passed through */}
+   <GridItem as={Text} fieldPath="sectionTitle" className="custom-text" />
    ```
 
 4. **Grid Positioning**: GridItem handles all grid-specific positioning regardless of the underlying component
@@ -199,7 +197,7 @@ import Grid, { GridItem } from '@hubspot/cms-component-library/Grid';
 ```tsx
 import Grid, { GridItem } from '@hubspot/cms-component-library/Grid';
 import Button from '@hubspot/cms-component-library/Button';
-import Heading from '@hubspot/cms-component-library/Heading';
+import Text from '@hubspot/cms-component-library/Text';
 
 <Grid templateColumns="repeat(2, 1fr)" gap="16px">
   {/* GridItem rendering as Button */}
@@ -211,13 +209,9 @@ import Heading from '@hubspot/cms-component-library/Heading';
     Click Me
   </GridItem>
 
-  {/* GridItem rendering as Heading */}
-  <GridItem
-    as={Heading}
-    headingLevel="h2"
-    displayAs="h3"
-  >
-    Section Title
+  {/* GridItem rendering as Text (heading feature set) */}
+  <GridItem>
+    <Text fieldPath="sectionTitle" />
   </GridItem>
 
   {/* Regular content */}
@@ -255,6 +249,9 @@ import Heading from '@hubspot/cms-component-library/Heading';
 ### Complex Layout Using Props (NO custom CSS)
 
 ```tsx
+import Grid, { GridItem } from '@hubspot/cms-component-library/Grid';
+import Text from '@hubspot/cms-component-library/Text';
+
 {/* Dashboard layout - all positioning via props */}
 <Grid
   templateColumns="1fr"
@@ -267,7 +264,7 @@ import Heading from '@hubspot/cms-component-library/Heading';
     gridColumn="1"
     gridColumnMd="1 / -1"
   >
-    <Heading headingLevel="h1">Dashboard</Heading>
+    <Text fieldPath="dashboardTitle" />
   </GridItem>
 
   {/* Sidebar - hidden on mobile, shown on tablet+ */}

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

@@ -83,7 +83,7 @@ When creating a new component in componentLibrary, ensure:
 - [ ] Semantic HTML elements used appropriately
 - [ ] ARIA roles added when needed (e.g., `role="separator"`)
 - [ ] Icon purpose properly set (SEMANTIC vs DECORATIVE)
-- [ ] Heading level vs display separated for proper semantics
+- [ ] Use `Text` with `textFeatureSet="heading"` for editable heading fields rather than raw HTML heading elements
 
 ## Reference Examples
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubspot/cms-component-library",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "HubSpot CMS React component library for building CMS modules",
   "license": "Apache-2.0",
   "exports": {
@@ -21,7 +21,7 @@
   },
   "type": "module",
   "dependencies": {
-    "@hubspot/cms-components": "1.2.17",
+    "@hubspot/cms-components": "1.2.19",
     "sass-embedded": "^1.97.3"
   },
   "peerDependencies": {