@hubspot/cms-component-library 0.3.5 → 0.3.7

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/LanguageSwitcher/index.tsx

@@ -1,114 +1,23 @@
-import styles from './index.module.scss';
-import cx from '../utils/classname.js';
-import { getLanguageDisplayName } from './utils.js';
-import LanguageOptions from './LanguageOptions.js';
-import GlobeIcon from './assets/Globe.js';
+// @ts-expect-error -- ?island not typed
+import LanguageSwitcherIsland from './islands/LanguageSwitcherIsland.js?island';
 import type { LanguageSwitcherProps } from './types.js';
+import { Island, useLanguageVariants } from '@hubspot/cms-components';
 import ContentFields from './ContentFields.js';
 import StyleFields from './StyleFields.js';
-import Button from '../Button/index.js';
-import { useLanguageVariants } from '@hubspot/cms-components';
-import { createTranslationsArrayAsObject } from './utils.js';
-import Drawer, { useDrawer } from '../Drawer/index.js';
-import { dummyTranslationsAsObject, dummyTranslations } from './_dummyData.js';
-import Divider from '../Divider/index.js';
-import type { CSSVariables } from '../utils/types.js';
 
 const LanguageSwitcherComponent = ({
-  useDummyData = false, // !todo - remove this in PROD (NOTE: storybook still needs the _dummyData, so add the _dummyData file to storybook dir and refactor usage there)
-  menuBackgroundColor,
-  menuBackgroundColorHover,
-  color,
-  colorHover,
-  languageSwitcherSelectText = 'Select a language',
-  className = '',
-  style = {},
+  translations: translationsProp,
+  ...rest
 }: LanguageSwitcherProps) => {
-  const translations = useDummyData ? dummyTranslations : useLanguageVariants(); // !todo remove this in PROD
-  const translationsArrayAsObject = useDummyData
-    ? dummyTranslationsAsObject
-    : createTranslationsArrayAsObject(translations); // !todo remove this in PROD
-  const activeTranslation = translations?.find(item => item.isActive);
-  const currentPageLanguage = activeTranslation?.languageCode ?? '';
-  const currentPageLanguageDisplayName = getLanguageDisplayName({
-    currentPageLanguage,
-    translationsArrayAsObject,
-  });
-
-  const { isOpen, toggle, close } = useDrawer();
-
-  const isInEditor = false; // !todo - update this to use useEditorVariableChecks() hook (is_in_editor property) once it's working
-
-  const colorCss = color?.rgba;
-  const menuBackgroundColorCss = menuBackgroundColor?.rgba;
-
-  const cssVariables = {
-    ...(colorCss && { '--hscl-languageSwitcher-color': colorCss }),
-    ...(menuBackgroundColorCss && {
-      '--hscl-languageSwitcher-backgroundColor': menuBackgroundColorCss,
-    }),
-  };
-
-  const dividerCssVariables: CSSVariables = {
-    '--hscl-divider-borderColor': colorCss,
-  };
-
-  const combinedClasses = cx(styles.languageSwitcher, className);
+  const languageVariants = useLanguageVariants();
+  const translations = translationsProp ?? languageVariants;
 
   return (
-    <div style={{ ...cssVariables, ...style }} className={combinedClasses}>
-      <Button
-        buttonType="button"
-        aria-expanded={isOpen}
-        onClick={toggle}
-        className={styles.button}
-        style={{ color: colorCss }}
-      >
-        <GlobeIcon />
-        {currentPageLanguageDisplayName}
-      </Button>
-      {!isInEditor && (
-        <Drawer
-          open={isOpen}
-          direction="right"
-          onOverlayClick={close}
-          aria-label="Language selector"
-          className={styles.drawer}
-          style={{
-            ...cssVariables,
-            backgroundColor: menuBackgroundColorCss,
-          }}
-        >
-          <div className={styles.sidePanelHeader}>
-            <span className={styles.sidePanelTitle}>
-              {languageSwitcherSelectText}
-            </span>
-            <Button
-              buttonType="button"
-              onClick={close}
-              aria-label="Close language selector"
-              className={styles.sidePanelCloseButton}
-            >
-              ✕
-            </Button>
-          </div>
-
-          <Divider spacing="0px" style={dividerCssVariables} />
-
-          <div className={styles.sidePanelOptionsContainer}>
-            <LanguageOptions
-              {...{
-                translations,
-                menuBackgroundColor,
-                menuBackgroundColorHover,
-                color,
-                colorHover,
-              }}
-            />
-          </div>
-        </Drawer>
-      )}
-    </div>
+    <Island
+      module={LanguageSwitcherIsland}
+      translations={translations}
+      {...rest}
+    />
   );
 };
 

package/components/componentLibrary/LanguageSwitcher/islands/LanguageSwitcherIsland.tsx

@@ -0,0 +1,110 @@
+import styles from '../index.module.scss';
+import cx from '../../utils/classname.js';
+import { getLanguageDisplayName } from '../utils.js';
+import LanguageOptions from '../LanguageOptions.js';
+import GlobeIcon from '../assets/Globe.js';
+import type { LanguageSwitcherIslandProps } from '../types.js';
+import Button from '../../Button/index.js';
+import { createTranslationsArrayAsObject } from '../utils.js';
+import Drawer, { useDrawer } from '../../Drawer/index.js';
+import Divider from '../../Divider/index.js';
+import type { CSSVariables } from '../../utils/types.js';
+
+const LanguageSwitcherIsland = ({
+  translations,
+  menuBackgroundColor,
+  menuBackgroundColorHover,
+  color,
+  colorHover,
+  languageSwitcherSelectText = 'Select a language',
+  className = '',
+  style = {},
+}: LanguageSwitcherIslandProps) => {
+  const translationsArrayAsObject = createTranslationsArrayAsObject(
+    translations
+  );
+  const activeTranslation = translations?.find(item => item.isActive);
+  const currentPageLanguage = activeTranslation?.languageCode ?? '';
+  const currentPageLanguageDisplayName = getLanguageDisplayName({
+    currentPageLanguage,
+    translationsArrayAsObject,
+  });
+
+  const { isOpen, toggle, close } = useDrawer();
+
+  const isInEditor = false;
+
+  const colorCss = color?.rgba;
+  const menuBackgroundColorCss = menuBackgroundColor?.rgba;
+
+  const cssVariables = {
+    ...(colorCss && { '--hscl-languageSwitcher-color': colorCss }),
+    ...(menuBackgroundColorCss && {
+      '--hscl-languageSwitcher-backgroundColor': menuBackgroundColorCss,
+    }),
+  };
+
+  const dividerCssVariables: CSSVariables = {
+    '--hscl-divider-borderColor': colorCss,
+  };
+
+  const combinedClasses = cx(styles.languageSwitcher, className);
+
+  return (
+    <div style={{ ...cssVariables, ...style }} className={combinedClasses}>
+      <Button
+        buttonType="button"
+        aria-expanded={isOpen}
+        onClick={toggle}
+        className={styles.button}
+        style={{ color: colorCss }}
+      >
+        <GlobeIcon />
+        {currentPageLanguageDisplayName}
+      </Button>
+      {!isInEditor && (
+        <Drawer
+          open={isOpen}
+          direction="right"
+          onOverlayClick={close}
+          aria-label="Language selector"
+          className={styles.drawer}
+          style={{
+            ...cssVariables,
+            backgroundColor: menuBackgroundColorCss,
+          }}
+        >
+          <div className={styles.sidePanelHeader}>
+            <span className={styles.sidePanelTitle}>
+              {languageSwitcherSelectText}
+            </span>
+            <Button
+              buttonType="button"
+              onClick={close}
+              aria-label="Close language selector"
+              className={styles.sidePanelCloseButton}
+            >
+              ✕
+            </Button>
+          </div>
+
+          <Divider spacing="0px" style={dividerCssVariables} />
+
+          <div className={styles.sidePanelOptionsContainer}>
+            <LanguageOptions
+              {...{
+                translations,
+                menuBackgroundColor,
+                menuBackgroundColorHover,
+                color,
+                colorHover,
+              }}
+            />
+          </div>
+        </Drawer>
+      )}
+    </div>
+  );
+};
+
+export default LanguageSwitcherIsland;

package/components/componentLibrary/LanguageSwitcher/llm.txt

@@ -15,7 +15,7 @@ The LanguageSwitcher component provides an accessible interface for users to vie
 
 ```
 LanguageSwitcher/
-├── index.tsx                                 # Main component with render logic
+├── index.tsx                                 # Main component (wrapper that delegates to Island)
 ├── types.ts                                  # TypeScript type definitions
 ├── ContentFields.tsx                         # HubSpot field definitions for content
 ├── StyleFields.tsx                           # HubSpot field definitions for styling
@@ -26,6 +26,8 @@ LanguageSwitcher/
 ├── index.module.scss                         # CSS module with design tokens
 ├── assets/
 │   └── Globe.tsx                             # Globe SVG icon component
+├── islands/
+│   └── LanguageSwitcherIsland.tsx            # Client-side island with interactive UI
 └── stories/
     ├── LanguageSwitcher.stories.tsx          # Component usage examples
     ├── LanguageSwitcherDecorator.tsx         # Storybook decorator
@@ -41,82 +43,43 @@ LanguageSwitcher/
 **Props:**
 ```tsx
 {
+  translations?: LanguageVariant[];             // Language variants (if not provided, uses useLanguageVariants hook)
   className?: string;                           // Additional CSS classes
   style?: React.CSSProperties;                  // Inline styles
-  textColor?: ColorFieldValue;                  // Text color for button and menu items
-  textColorHover?: ColorFieldValue;             // Text color for menu items on hover
+  color?: ColorFieldValue;                      // Text color for button and menu items
+  colorHover?: ColorFieldValue;                 // Text color for menu items on hover
   menuBackgroundColor?: ColorFieldValue;        // Background color for the drawer
   menuBackgroundColorHover?: ColorFieldValue;   // Background color for menu items on hover
   languageSwitcherSelectText?: string;          // Header text in drawer (default: 'Select a language')
-  useDummyData?: boolean;                       // Use dummy data for testing (development only)
 }
 ```
 
 ## Usage Examples
 
-### Island Usage
+### Basic Usage
 
-The LanguageSwitcher component requires JavaScript for interactive state management and must be used within an Island component.
-
-#### Island Component
+The LanguageSwitcher component automatically handles Island-ification internally. Simply import and use it with optional props:
 
 ```tsx
-// islands/LanguageSwitcherIsland.tsx
 import LanguageSwitcher from '@hubspot/cms-component-library/LanguageSwitcher';
 
-export default function LanguageSwitcherIsland({
-  textColor,
-  textColorHover,
-  menuBackgroundColor,
-  menuBackgroundColorHover,
-  languageSwitcherSelectText,
-}) {
-  return (
-    <LanguageSwitcher
-      textColor={textColor}
-      textColorHover={textColorHover}
-      menuBackgroundColor={menuBackgroundColor}
-      menuBackgroundColorHover={menuBackgroundColorHover}
-      languageSwitcherSelectText={languageSwitcherSelectText}
-    />
-  );
+export default function MyComponent() {
+  return <LanguageSwitcher />;
 }
 ```
 
-#### Module File
-
-```tsx
-import { Island } from '@hubspot/cms-components';
-import LanguageSwitcherIsland from './islands/LanguageSwitcherIsland?island';
-
-export const Component = ({ fieldValues }) => {
-  return (
-    <Island
-      module={LanguageSwitcherIsland}
-      textColor={fieldValues.textColor}
-      textColorHover={fieldValues.textColorHover}
-      menuBackgroundColor={fieldValues.menuBackgroundColor}
-      menuBackgroundColorHover={fieldValues.menuBackgroundColorHover}
-      languageSwitcherSelectText={fieldValues.languageSwitcherSelectText}
-    />
-  );
-};
-```
+When used without a `translations` prop, it automatically calls `useLanguageVariants()` to fetch language data.
 
-### Basic Language Switcher
+### With Custom Header Text
 
 ```tsx
-import LanguageSwitcher from '@hubspot/cms-component-library/LanguageSwitcher';
-
-export default function LanguageSwitcherIsland() {
-  return <LanguageSwitcher />;
-}
+<LanguageSwitcher languageSwitcherSelectText="Choose your language" />
 ```
 
-### With Custom Header Text
+### With Custom Translations
 
 ```tsx
-<LanguageSwitcher languageSwitcherSelectText="Choose your language" />
+<LanguageSwitcher translations={customLanguageVariants} />
 ```
 
 ### With Custom Colors
@@ -125,8 +88,8 @@ If passing in colors directly (without using a ColorField), like the below examp
 
 ```tsx
 <LanguageSwitcher
-  textColor={{ rgba: 'rgba(51, 71, 91, 1)' }}
-  textColorHover={{ rgba: 'rgba(0, 102, 204, 1)' }}
+  color={{ rgba: 'rgba(51, 71, 91, 1)' }}
+  colorHover={{ rgba: 'rgba(0, 102, 204, 1)' }}
   menuBackgroundColor={{ rgba: 'rgba(255, 255, 255, 1)' }}
   menuBackgroundColorHover={{ rgba: 'rgba(245, 245, 245, 1)' }}
 />
@@ -197,21 +160,19 @@ Configurable props for color customization:
 
 ### Module Usage Example
 
-If passing in colors using a ColorField, like the below example, pass in the entire field value. HubSpot will transform the field value from a default of { color: hex, opacity: number } to { rbga, rgb, opacity, color, hex, css }. The LanguageSwitcher component will pull the rgba value from this final output.
+If passing in colors using a ColorField, like the below example, pass in the entire field value. HubSpot will transform the field value from a default of { color: hex, opacity: number } to { rgba, rgb, opacity, color, hex, css }. The LanguageSwitcher component will pull the rgba value from this final output.
 
 ```tsx
-import { Island } from '@hubspot/cms-components';
-import LanguageSwitcherIsland from './islands/LanguageSwitcherIsland?island';
+import LanguageSwitcher from '@hubspot/cms-component-library/LanguageSwitcher';
 
 export default function HeaderModule({ fieldValues }) {
   return (
     <header>
       <nav>
         {/* Other navigation items */}
-        <Island
-          module={LanguageSwitcherIsland}
-          textColor={fieldValues.textColor}
-          textColorHover={fieldValues.textColorHover}
+        <LanguageSwitcher
+          color={fieldValues.color}
+          colorHover={fieldValues.colorHover}
           menuBackgroundColor={fieldValues.menuBackgroundColor}
           menuBackgroundColorHover={fieldValues.menuBackgroundColorHover}
           languageSwitcherSelectText={fieldValues.languageSwitcherSelectText}
@@ -280,14 +241,14 @@ The LanguageSwitcher component follows accessibility best practices:
 
 ## Best Practices
 
-- **Use Islands for interactivity**: The LanguageSwitcher component is interactive and requires JavaScript, so it must be used within an Island component in modules
+- **Island-ification is handled internally**: The LanguageSwitcher component automatically handles Island-ification for interactive state, so you don't need to manually wrap it
 - **Position prominently**: Place in global navigation (header or footer) where users expect language controls
 - **Use native language names**: The component automatically displays language names in their native script (e.g., "Español" for Spanish, "Français" for French)
 - **Customize header text**: Set `languageSwitcherSelectText` to match your site's primary language for consistency
 - **Color coordination**: Match `textColor` and `menuBackgroundColor` to your site's theme
 - **Color setting**: If using ColorFields, pass in the entire field value, as HubSpot transforms the user's color choice into an object with an rgba key. Otherwise, ensure the color object has an rgba key and value. The component expects an object with an rgba key.
 - **Responsive design**: The drawer automatically adjusts to full width on mobile devices (≤400px)
-- **Test with real translations**: While `useDummyData` prop exists for development, always test with actual HubSpot language variants in production
+- **Test with real translations**: Pass real HubSpot language variants via the `translations` prop, or rely on the default `useLanguageVariants()` hook for production
 - **Provide clear visual feedback**: Use hover colors that provide sufficient contrast for user interaction
 - **Consider placement**: Position near other utility navigation items (search, account, etc.)
 - **Dark mode support**: Provide appropriate color values for dark backgrounds when needed
@@ -297,8 +258,7 @@ The LanguageSwitcher component follows accessibility best practices:
 ### Header Navigation Integration
 
 ```tsx
-import { Island } from '@hubspot/cms-components';
-import LanguageSwitcherIsland from './islands/LanguageSwitcherIsland?island';
+import LanguageSwitcher from '@hubspot/cms-component-library/LanguageSwitcher';
 
 export default function SiteHeader({ fieldValues }) {
   return (
@@ -315,9 +275,8 @@ export default function SiteHeader({ fieldValues }) {
         <a href="/about">About</a>
         <a href="/services">Services</a>
         <a href="/contact">Contact</a>
-        <Island
-          module={LanguageSwitcherIsland}
-          textColor={fieldValues.textColor}
+        <LanguageSwitcher
+          color={fieldValues.color}
           menuBackgroundColor={fieldValues.menuBackgroundColor}
           languageSwitcherSelectText={fieldValues.languageSwitcherSelectText}
         />
@@ -330,13 +289,14 @@ export default function SiteHeader({ fieldValues }) {
 ### Footer Placement
 
 ```tsx
+import LanguageSwitcher from '@hubspot/cms-component-library/LanguageSwitcher';
+
 export default function SiteFooter({ fieldValues }) {
   return (
     <footer style={{ padding: '48px 24px', textAlign: 'center' }}>
       <div style={{ marginBottom: '24px' }}>
-        <Island
-          module={LanguageSwitcherIsland}
-          textColor={fieldValues.footerTextColor}
+        <LanguageSwitcher
+          color={fieldValues.footerTextColor}
           menuBackgroundColor={fieldValues.menuBackgroundColor}
           languageSwitcherSelectText={fieldValues.languageSwitcherSelectText}
         />
@@ -350,6 +310,8 @@ export default function SiteFooter({ fieldValues }) {
 ### Mobile-First Navigation
 
 ```tsx
+import LanguageSwitcher from '@hubspot/cms-component-library/LanguageSwitcher';
+
 export default function MobileNav({ fieldValues }) {
   return (
     <nav style={{
@@ -362,9 +324,8 @@ export default function MobileNav({ fieldValues }) {
       <a href="/about">About</a>
       <a href="/contact">Contact</a>
       <div style={{ borderTop: '1px solid #eee', paddingTop: '16px' }}>
-        <Island
-          module={LanguageSwitcherIsland}
-          textColor={fieldValues.textColor}
+        <LanguageSwitcher
+          color={fieldValues.color}
           menuBackgroundColor={fieldValues.menuBackgroundColor}
         />
       </div>

package/components/componentLibrary/LanguageSwitcher/stories/LanguageSwitcher.stories.tsx

@@ -3,6 +3,7 @@ import LanguageSwitcher from '../index.js';
 import { LanguageSwitcherProps } from '../types.js';
 import { withLanguageSwitcherStyles } from './LanguageSwitcherDecorator.js';
 import { SBContainer, SBFocusWrapper } from '@sb-utils';
+import { dummyTranslations } from '../_dummyData.js';
 
 const meta: Meta<LanguageSwitcherProps> = {
   title: 'Component Library/LanguageSwitcher',
@@ -21,14 +22,6 @@ const meta: Meta<LanguageSwitcherProps> = {
   },
   decorators: [withLanguageSwitcherStyles],
   argTypes: {
-    useDummyData: {
-      control: 'boolean',
-      description: 'Use dummy translation data for testing',
-      table: {
-        category: 'Development',
-        defaultValue: { summary: 'false' },
-      },
-    },
     languageSwitcherSelectText: {
       control: 'text',
       description: 'Text displayed in the drawer header',
@@ -37,14 +30,14 @@ const meta: Meta<LanguageSwitcherProps> = {
         defaultValue: { summary: 'Select a language' },
       },
     },
-    textColor: {
+    color: {
       control: 'object',
       description: 'Text color for button and menu items',
       table: {
         category: 'Visual',
       },
     },
-    textColorHover: {
+    colorHover: {
       control: 'object',
       description: 'Text color for menu items on hover',
       table: {
@@ -90,7 +83,7 @@ export const Default: Story = {
     return (
       <SBContainer>
         <LanguageSwitcher
-          useDummyData={true}
+          translations={dummyTranslations}
           languageSwitcherSelectText="Select a language"
         />
       </SBContainer>
@@ -140,10 +133,10 @@ export const ColorThemes: Story = {
           <p>Custom color theming with purple tones.</p>
           <SBContainer>
             <LanguageSwitcher
-              useDummyData={true}
+              translations={dummyTranslations}
               languageSwitcherSelectText="Wählen Sie eine Sprache"
-              textColor={purpleTextColor}
-              textColorHover={purpleTextColorHover}
+              color={purpleTextColor}
+              colorHover={purpleTextColorHover}
               menuBackgroundColor={purpleMenuBgColor}
               menuBackgroundColorHover={purpleMenuBgColorHover}
             />
@@ -162,10 +155,10 @@ export const ColorThemes: Story = {
           </SBContainer>
           <SBContainer>
             <LanguageSwitcher
-              useDummyData={true}
+              translations={dummyTranslations}
               languageSwitcherSelectText="Select a language"
-              textColor={darkTextColor}
-              textColorHover={darkTextColorHover}
+              color={darkTextColor}
+              colorHover={darkTextColorHover}
               menuBackgroundColor={darkMenuBgColor}
               menuBackgroundColorHover={darkMenuBgColorHover}
             />
@@ -195,7 +188,7 @@ export const CustomText: Story = {
               <strong>🇬🇧 English:</strong>
             </p>
             <LanguageSwitcher
-              useDummyData={true}
+              translations={dummyTranslations}
               languageSwitcherSelectText="Select a language"
             />
           </SBContainer>
@@ -205,7 +198,7 @@ export const CustomText: Story = {
               <strong>🇩🇪 German:</strong>
             </p>
             <LanguageSwitcher
-              useDummyData={true}
+              translations={dummyTranslations}
               languageSwitcherSelectText="Sprache wählen"
             />
           </SBContainer>
@@ -215,7 +208,7 @@ export const CustomText: Story = {
               <strong>🇪🇸 Spanish:</strong>
             </p>
             <LanguageSwitcher
-              useDummyData={true}
+              translations={dummyTranslations}
               languageSwitcherSelectText="Seleccionar idioma"
             />
           </SBContainer>
@@ -225,7 +218,7 @@ export const CustomText: Story = {
               <strong>🇫🇷 French:</strong>
             </p>
             <LanguageSwitcher
-              useDummyData={true}
+              translations={dummyTranslations}
               languageSwitcherSelectText="Choisir une langue"
             />
           </SBContainer>
@@ -288,9 +281,9 @@ export const InContext: Story = {
 
             <div style={{ paddingTop: '6px' }}>
               <LanguageSwitcher
-                useDummyData={true}
-                textColor={{ rgba: 'rgb(55, 245, 255)' }}
-                textColorHover={{ rgba: 'rgb(255, 255, 255)' }}
+                translations={dummyTranslations}
+                color={{ rgba: 'rgb(55, 245, 255)' }}
+                colorHover={{ rgba: 'rgb(255, 255, 255)' }}
                 menuBackgroundColor={{ rgba: 'rgba(100, 181, 246, 1)' }}
                 menuBackgroundColorHover={{ rgba: 'rgba(0, 160, 240, 1)' }}
               />
@@ -325,7 +318,7 @@ export const InteractionStates: Story = {
         <h4>Hover State</h4>
         <p>Hover over the language switcher button to see the hover effect</p>
         <LanguageSwitcher
-          useDummyData={true}
+          translations={dummyTranslations}
           languageSwitcherSelectText="Select a language"
         />
       </SBContainer>
@@ -339,7 +332,7 @@ export const InteractionStates: Story = {
         </p>
         <SBFocusWrapper>
           <LanguageSwitcher
-            useDummyData={true}
+            translations={dummyTranslations}
             languageSwitcherSelectText="Select a language"
           />
         </SBFocusWrapper>

package/components/componentLibrary/LanguageSwitcher/types.ts

@@ -7,8 +7,19 @@ import type { CSSVariables } from '../utils/types.js';
 
 type ColorFieldValue = typeof ColorFieldDefaults;
 
+export type LanguageSwitcherIslandProps = {
+  translations: LanguageVariant[];
+  className?: string;
+  style?: CSSVariables;
+  color?: ColorFieldValue;
+  colorHover?: ColorFieldValue;
+  menuBackgroundColorHover?: ColorFieldValue;
+  menuBackgroundColor?: ColorFieldValue;
+  languageSwitcherSelectText?: string;
+};
+
 export type LanguageSwitcherProps = {
-  useDummyData?: boolean; // !todo - remove this in PROD
+  translations?: LanguageVariant[];
   className?: string;
   style?: CSSVariables;
   color?: ColorFieldValue;

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