@hubspot/cms-component-library 0.3.5 → 0.3.6

package/components/componentLibrary/Accordion/llm.txt

@@ -439,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

@@ -10,7 +10,7 @@ const ContentFields = ({
     <FormField
       label={formIdLabel}
       name={formIdName}
-      embedVersions={['v4']}
+      embedVersions={['v4', 'v3', 'v2']}
       default={formIdDefault}
     />
   );

package/components/componentLibrary/Form/index.tsx

@@ -1,11 +1,21 @@
 // @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 = (props: FormProps) => {
-  return <Island module={FormIsland} {...props} />;
+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 & {

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

@@ -1,15 +1,15 @@
 import { useEffect } from 'react';
-import { FormProps, InternalFormProps } from '../types.js';
-import { getHubID } from '@hubspot/cms-components';
+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/${portalId}.js`;
+  return `https://${host}/forms/embed/developer/${portalId}.js`;
 };
 
-const FormIsland = ({ formId, env }: FormProps & InternalFormProps) => {
+const FormIsland = ({ formId }: FormProps) => {
   const portalId = getHubID();
-  const resolvedEnv = env === 'qa' ? env : 'prod';
+  const resolvedEnv = getHSEnv();
 
   useEffect(() => {
     if (!formId || !portalId) {

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/types.ts

@@ -1,9 +1,17 @@
 import { FormFieldDefaults } from '@hubspot/cms-components/fields';
-export type InternalFormProps = {
-  env?: 'qa' | 'prod';
-};
-export type FormProps = {
+
+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 = {

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.5",
+  "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": {