@hubspot/cms-component-library 0.3.8 → 0.3.10

package/components/componentLibrary/Link/llm.txt

@@ -58,9 +58,9 @@ Pass a `linkField` prop containing HubSpot link field data. The component automa
     open_in_new_tab?: boolean;                       // Open in new tab
     no_follow?: boolean;                             // Add nofollow rel
   };
-  variant?: 'primary' | 'secondary' | 'tertiary';    // Visual style variant (default: 'primary')
+  variant?: 'primaryLink' | 'secondaryLink';         // Visual style variant (default: 'primaryLink')
   className?: string;                                // Additional CSS classes
-  style?: React.CSSProperties;                       // Inline styles (including CSS variables)
+  style?: React.CSSProperties;                       // Inline styles
   children?: React.ReactNode;                        // Link text/content
 }
 ```
@@ -74,9 +74,9 @@ Pass individual `href`, `target`, and `rel` props directly.
   href: string;                                      // Link destination URL (required)
   target?: '_self' | '_blank' | '_parent' | '_top';  // Link target behavior
   rel?: string;                                      // Link relationship (e.g., 'noopener noreferrer')
-  variant?: 'primary' | 'secondary' | 'tertiary';    // Visual style variant (default: 'primary')
+  variant?: 'primaryLink' | 'secondaryLink';         // Visual style variant (default: 'primaryLink')
   className?: string;                                // Additional CSS classes
-  style?: React.CSSProperties;                       // Inline styles (including CSS variables)
+  style?: React.CSSProperties;                       // Inline styles
   children?: React.ReactNode;                        // Link text/content
 }
 ```
@@ -107,21 +107,7 @@ export default function MyModule({ fieldValues }) {
 ```tsx
 <Link
   linkField={fieldValues.link}
-  variant="secondary"
->
-  Visit HubSpot
-</Link>
-```
-
-#### Field-based Link with Style Override
-
-```tsx
-<Link
-  linkField={fieldValues.link}
-  style={{
-    '--hscl-link-textDecoration': 'none',
-    '--hscl-link-textDecoration-hover': 'underline',
-  }}
+  variant="secondaryLink"
 >
   Visit HubSpot
 </Link>
@@ -163,17 +149,13 @@ import Link from '@hubspot/cms-component-library/Link';
 ### Using Variants
 
 ```tsx
-<Link href="https://www.hubspot.com" variant="primary">
+<Link href="https://www.hubspot.com" variant="primaryLink">
   Primary Link
 </Link>
 
-<Link href="https://www.hubspot.com" variant="secondary">
+<Link href="https://www.hubspot.com" variant="secondaryLink">
   Secondary Link
 </Link>
-
-<Link href="https://www.hubspot.com" variant="tertiary">
-  Tertiary Link
-</Link>
 ```
 
 ## HubSpot CMS Integration
@@ -220,12 +202,12 @@ The Link component provides field definitions for easy integration with HubSpot
 <Link.StyleFields
   variantLabel="Link style"
   variantName="linkVariant"
-  variantDefault="primary"
+  variantDefault={{ variant_name: 'primaryLink' }}
 />
 ```
 
 **Fields:**
-- `linkVariant`: Choice field for variant selection (primary, secondary, tertiary)
+- `linkVariant`: VariantSelectionField for theme variant selection (primaryLink, secondaryLink)
 
 ### Module Usage Example
 
@@ -238,7 +220,7 @@ export default function NavigationModule({ fieldValues }) {
   return (
     <Link
       linkField={fieldValues.link}
-      variant={fieldValues.linkVariant}
+      variant={fieldValues.style.linkVariant?.variantName}
     >
       {fieldValues.linkText}
     </Link>
@@ -255,7 +237,7 @@ export default function NavigationModule({ fieldValues }) {
       href="https://www.hubspot.com"
       target="_blank"
       rel="nofollow"
-      variant="primary"
+      variant="primaryLink"
     >
       Go to HubSpot
     </Link>
@@ -269,69 +251,32 @@ Note: The field-based approach is simpler and less error-prone.
 
 ### Variants
 
-The Link component supports three visual style variants through the `variant` prop:
+The Link component supports two visual style variants through the `variant` prop:
 
-- **primary** (default): Default link styling using `--hscl-link-color-primary` and `--hscl-link-color-hover-primary`
-- **secondary**: Alternative styling using `--hscl-link-color-secondary` and `--hscl-link-color-hover-secondary`
-- **tertiary**: Third alternative using `--hscl-link-color-tertiary` and `--hscl-link-color-hover-tertiary`
+- **primaryLink** (default): Default link styling
+- **secondaryLink**: Alternative link styling
 
-The component internally sets:
-```tsx
-style={{
-  '--hscl-link-color': `var(--hscl-link-color-${variant})`,
-  '--hscl-link-color-hover': `var(--hscl-link-color-hover-${variant})`,
-}}
-```
+The component renders a `data-link-variant` attribute on the `<a>` element. The theme provides CSS variables scoped to `[data-link-variant]` selectors.
 
-### CSS Variables
+### CSS Variables (Theme-provided)
 
-The Link component uses CSS variables for theming and customization:
+The theme provides these CSS variables via `[data-link-variant]` selectors:
 
 **Base Styles:**
-- `--hscl-link-display`: Display property (default: inline-block)
-- `--hscl-link-color`: Text color (set by variant, no fallback)
-- `--hscl-link-textDecoration`: Text decoration (default: underline)
+- `--hs-link-color`: Text color
+- `--hs-link-textDecoration`: Text decoration
 
 **Hover States:**
-- `--hscl-link-color-hover`: Hover text color (set by variant, no fallback)
-- `--hscl-link-textDecoration-hover`: Hover text decoration (default: underline)
-
-**Variant-specific Variables (must be defined globally):**
-- `--hscl-link-color-primary`: Primary variant text color
-- `--hscl-link-color-hover-primary`: Primary variant hover text color
-- `--hscl-link-color-secondary`: Secondary variant text color
-- `--hscl-link-color-hover-secondary`: Secondary variant hover text color
-- `--hscl-link-color-tertiary`: Tertiary variant text color
-- `--hscl-link-color-hover-tertiary`: Tertiary variant hover text color
-
-### Custom Styling Examples
+- `--hs-link-color-hover`: Hover text color
+- `--hs-link-textDecoration-hover`: Hover text decoration
 
-#### Override Text Decoration
+**Active States:**
+- `--hs-link-color-active`: Active text color (falls back to `--hs-link-color`)
+- `--hs-link-textDecoration-active`: Active text decoration (falls back to `--hs-link-textDecoration`)
 
-```tsx
-<Link
-  href="https://www.hubspot.com"
-  style={{
-    '--hscl-link-textDecoration': 'none',
-    '--hscl-link-textDecoration-hover': 'underline',
-  }}
->
-  Hover for underline
-</Link>
-```
-
-#### Override Display
-
-```tsx
-<Link
-  href="https://www.hubspot.com"
-  style={{
-    '--hscl-link-display': 'block',
-  }}
->
-  Block-level Link
-</Link>
-```
+**Hardcoded Styles (not theme-configurable):**
+- `display: inline-block`
+- Focus outline: `2px solid currentColor` with `2px` offset
 
 ## Accessibility
 
@@ -349,9 +294,8 @@ The Link component follows accessibility best practices:
 
 - **Use linkField prop when available**: If you have HubSpot field data, use the `linkField` prop instead of manually extracting href/target/rel
 - **Do NOT mix approaches**: TypeScript will prevent you from using both `linkField` and `href` props together
-- **Use variants for consistency**: Choose the appropriate variant (primary/secondary/tertiary) rather than overriding colors directly
+- **Use variants for consistency**: Choose the appropriate variant (primaryLink/secondaryLink) rather than overriding colors directly
 - **Security**: The component automatically adds `rel="noopener noreferrer"` when target is `_blank`
-- **CSS Variables**: Override design tokens using CSS variables for advanced customization
 - **Minimal styling**: Keep link styling simple; use Button component for prominent CTAs
 
 ## Common Patterns
@@ -359,7 +303,7 @@ The Link component follows accessibility best practices:
 ### Navigation Menu Item
 
 ```tsx
-<Link href="/dashboard" variant="secondary">
+<Link href="/dashboard" variant="secondaryLink">
   Dashboard
 </Link>
 ```

package/components/componentLibrary/Link/stories/Link.stories.tsx

@@ -4,12 +4,6 @@ import { LinkProps } from '../types.js';
 import { withLinkStyles } from './LinkDecorator.js';
 import { SBContainer, SBFocusWrapper } from '@sb-utils';
 import { SBCard } from '@sb-utils/SBCard.js';
-import type { CSSVariables } from '../../utils/types.js';
-
-const removeUnderlineStyle: CSSVariables = {
-  '--hscl-link-textDecoration': 'none',
-  '--hscl-link-textDecoration-hover': 'none',
-};
 
 const meta: Meta<LinkProps> = {
   title: 'Component Library/Link',
@@ -34,7 +28,7 @@ export const Default: Story = {
     href: 'https://www.hubspot.com',
     target: '_blank',
     rel: 'noopener noreferrer',
-    variant: 'primary',
+    variant: 'primaryLink',
     className: 'test-class',
   },
 };
@@ -90,7 +84,7 @@ export const InContext: Story = {
           gap="medium"
           style={{ flexWrap: 'wrap' }}
         >
-          <Link href="https://www.hubspot.com" style={removeUnderlineStyle}>
+          <Link href="https://www.hubspot.com">
             <SBCard
               title="Clickable Card"
               description="The entire card is wrapped in a link, making it clickable."
@@ -143,7 +137,6 @@ export const InContext: Story = {
               <Link
                 key={key}
                 href={`/image/${key}`}
-                style={removeUnderlineStyle}
               >
                 <div
                   style={{
@@ -179,7 +172,7 @@ export const InteractionStates: Story = {
       <SBContainer addBackground>
         <h4>Hover State</h4>
         <p>Hover over the link to see the hover effect</p>
-        <Link href="https://www.hubspot.com" variant="primary">
+        <Link href="https://www.hubspot.com" variant="primaryLink">
           Hover me
         </Link>
       </SBContainer>
@@ -192,7 +185,7 @@ export const InteractionStates: Story = {
           to show how it looks.
         </p>
         <SBFocusWrapper>
-          <Link href="https://www.hubspot.com" variant="primary">
+          <Link href="https://www.hubspot.com" variant="primaryLink">
             Focused link
           </Link>
         </SBFocusWrapper>

package/components/componentLibrary/Link/stories/LinkDecorator.module.scss

@@ -0,0 +1,15 @@
+.linkContainer {
+  [data-link-variant='primaryLink'] {
+    --hs-link-color: #0066cc;
+    --hs-link-textDecoration: none;
+    --hs-link-color-hover: #0052a3;
+    --hs-link-textDecoration-hover: underline;
+  }
+
+  [data-link-variant='secondaryLink'] {
+    --hs-link-color: #516f90;
+    --hs-link-textDecoration: none;
+    --hs-link-color-hover: #33475b;
+    --hs-link-textDecoration-hover: underline;
+  }
+}

package/components/componentLibrary/Link/stories/LinkDecorator.tsx

@@ -1,17 +1,8 @@
 import type { Decorator } from '@storybook/react';
-import type { CSSVariables } from '../../utils/types.js';
-
-const defaultLinkStyles: CSSVariables = {
-  '--hscl-link-color-primary': '#0066cc',
-  '--hscl-link-color-secondary': '#516f90',
-  '--hscl-link-color-tertiary': '#7c98b6',
-  '--hscl-link-color-hover-primary': '#0052a3',
-  '--hscl-link-color-hover-secondary': '#33475b',
-  '--hscl-link-color-hover-tertiary': '#516f90',
-};
+import styles from './LinkDecorator.module.scss';
 
 export const withLinkStyles: Decorator = Story => (
-  <div style={defaultLinkStyles}>
+  <div className={styles.linkContainer}>
     <Story />
   </div>
 );

package/components/componentLibrary/Link/types.ts

@@ -1,8 +1,10 @@
 import { LinkFieldDefaults, Visibility } from '@hubspot/cms-components/fields';
 import { LinkFieldValue } from '../utils/linkField.js';
 
+export type LinkVariant = 'primaryLink' | 'secondaryLink';
+
 export type BaseLinkProps = {
-  variant?: 'primary' | 'secondary' | 'tertiary';
+  variant?: LinkVariant;
   className?: string;
   style?: React.CSSProperties;
   children?: React.ReactNode;
@@ -33,15 +35,16 @@ type LinkWithoutField = BaseLinkProps &
 
 export type LinkProps = LinkWithField | LinkWithoutField;
 
-export type ContentFieldsProps = {
+export type ContentFieldsProps<TLinkName extends string = 'link'> = {
   linkLabel?: string;
-  linkName?: string;
   linkDefault?: typeof LinkFieldDefaults;
-  fieldVisibility?: Partial<Record<string, Visibility>>;
-};
+} & (
+  | { linkName?: never; fieldVisibility?: Partial<Record<'link', Visibility>> }
+  | { linkName: TLinkName; fieldVisibility?: Partial<Record<TLinkName, Visibility>> }
+);
 
 export type StyleFieldsProps = {
-  linkVariantLabel?: string;
-  linkVariantName?: string;
-  linkVariantDefault?: string;
+  variantLabel?: string;
+  variantName?: string;
+  variantDefault?: { variant_name: LinkVariant };
 };

package/components/componentLibrary/Video/ContentFields.tsx

@@ -0,0 +1,112 @@
+import {
+  ChoiceField,
+  EmbedField,
+  ImageField,
+  VideoField,
+} from '@hubspot/cms-components/fields';
+import { ContentFieldsProps } from './types.js';
+
+const ContentFields = ({
+  videoTypeLabel = 'Video type',
+  videoTypeName = 'videoType',
+  hsVideoLabel = 'HubSpot video',
+  hsVideoName = 'hubspotVideo',
+  hsVideoDefault,
+  embedVideoLabel = 'Embed video',
+  embedVideoName = 'embedVideo',
+  embedVideoDefault,
+  oembedThumbnailLabel = 'Custom thumbnail',
+  oembedThumbnailName = 'oembedThumbnail',
+  oembedThumbnailDefault,
+}: ContentFieldsProps) => {
+  return (
+    <>
+      <ChoiceField
+        name={videoTypeName}
+        label={videoTypeLabel}
+        id="videoType"
+        display="radio"
+        choices={[
+          ['embed', 'Embed'],
+          ['hubspot_video', 'HubSpot video'],
+        ]}
+        default="embed"
+        visibilityRules="ADVANCED"
+        advancedVisibility={{
+          boolean_operator: 'OR',
+          criteria: [
+            {
+              access: {
+                operator: 'HAS_ALL',
+                scopes: ['marketing-video'],
+              },
+            },
+            {
+              controlling_field: 'videoType',
+              operator: 'EQUAL',
+              controlling_value_regex: 'hubspot_video',
+            },
+          ],
+        }}
+      />
+
+      <VideoField
+        name={hsVideoName}
+        label={hsVideoLabel}
+        showAdvancedOptions={true}
+        default={hsVideoDefault}
+        visibility={{
+          controlling_field: 'videoType',
+          operator: 'EQUAL',
+          controlling_value_regex: 'hubspot_video',
+        }}
+      />
+
+      <EmbedField
+        name={embedVideoName}
+        label={embedVideoLabel}
+        id="embedVideo"
+        supportedSourceTypes={['oembed', 'html']}
+        supportedOembedTypes={['video']}
+        supportedMediaBridgeProviders={[]}
+        default={embedVideoDefault}
+        visibility={{
+          controlling_field: 'videoType',
+          operator: 'EQUAL',
+          controlling_value_regex: 'embed',
+        }}
+      />
+
+      <ImageField
+        name={oembedThumbnailName}
+        label={oembedThumbnailLabel}
+        default={oembedThumbnailDefault}
+        responsive={true}
+        resizable={false}
+        visibilityRules="ADVANCED"
+        advancedVisibility={{
+          boolean_operator: 'AND',
+          criteria: [
+            {
+              controlling_field: 'videoType',
+              operator: 'EQUAL',
+              controlling_value_regex: 'embed',
+            },
+            {
+              controlling_field: 'embedVideo',
+              operator: 'MATCHES_REGEX',
+              controlling_value_regex: '(?=.*"source_type":"oembed")',
+            },
+            {
+              controlling_field: 'embedVideo',
+              operator: 'MATCHES_REGEX',
+              controlling_value_regex: '(?=.*"oembed_url":"(?!")+)',
+            },
+          ],
+        }}
+      />
+    </>
+  );
+};
+
+export default ContentFields;

package/components/componentLibrary/Video/StyleFields.tsx

@@ -0,0 +1,19 @@
+import { ColorField } from '@hubspot/cms-components/fields';
+import { StyleFieldsProps } from './types.js';
+
+const StyleFields = ({
+  playButtonColorLabel = 'Play button color',
+  playButtonColorName = 'playButtonColor',
+  playButtonColorDefault = { color: '#F7761F', opacity: 100 },
+}: StyleFieldsProps) => {
+  return (
+    <ColorField
+      label={playButtonColorLabel}
+      name={playButtonColorName}
+      default={playButtonColorDefault}
+      showOpacity={false}
+    />
+  );
+};
+
+export default StyleFields;

package/components/componentLibrary/Video/index.tsx

@@ -0,0 +1,47 @@
+import { Island } from '@hubspot/cms-components';
+import ContentFields from './ContentFields.js';
+import StyleFields from './StyleFields.js';
+// @ts-expect-error -- ?island not typed
+import HSVideoIsland from './islands/HSVideoIsland.js?island';
+import { VideoProps } from './types.js';
+
+const VideoComponent = ({
+  videoType,
+  hubspotVideoParams,
+  embedVideoParams,
+  playButtonColor,
+  video,
+}: VideoProps) => {
+  if (videoType === 'hubspot_video' && hubspotVideoParams?.player_id) {
+    return (
+      <Island
+        module={HSVideoIsland}
+        hydrateOn="visible"
+        hubspotVideoParams={hubspotVideoParams}
+        playButtonColor={playButtonColor}
+        video={video}
+      />
+    );
+  }
+
+  if (
+    videoType === 'embed' &&
+    Boolean(embedVideoParams?.oembed_url || embedVideoParams?.embed_html)
+  ) {
+    // TODO: implement embed video
+    return <div />;
+  }
+
+  return null;
+};
+
+type VideoComponentType = typeof VideoComponent & {
+  ContentFields: typeof ContentFields;
+  StyleFields: typeof StyleFields;
+};
+
+const Video = VideoComponent as VideoComponentType;
+Video.ContentFields = ContentFields;
+Video.StyleFields = StyleFields;
+
+export default Video;

package/components/componentLibrary/Video/islands/HSVideoIsland.tsx

@@ -0,0 +1,53 @@
+import { getHSEnv, getHubID, getHublet } from '@hubspot/cms-components';
+import {
+  // @ts-expect-error -- provider type not flowing through properly
+  TranslationsProvider,
+  useVideo,
+  VideoFetchProvider,
+  VideoPlayer,
+  // @ts-expect-error -- provider type not flowing through properly
+  VideoPlayerProvider,
+} from '@hubspot/video-player-core';
+
+import { HSVideoIslandProps } from '../types.js';
+
+const HSVideoIsland = ({
+  video,
+  hubspotVideoParams,
+  playButtonColor,
+}: HSVideoIslandProps) => {
+  const portalId = getHubID();
+  const hsEnv = getHSEnv();
+  const hublet = getHublet();
+  const { video: clientFetchedVideo, error: videoFetchError } = useVideo(
+    hubspotVideoParams.player_id,
+    portalId,
+    hsEnv,
+    hublet,
+    Boolean(video)
+  );
+  const resolvedVideo = video || clientFetchedVideo;
+
+  return (
+    <VideoFetchProvider
+      env={hsEnv}
+      hublet={hublet}
+      videoId={hubspotVideoParams.player_id}
+      video={resolvedVideo}
+      videoFetchError={videoFetchError}
+      hubspotVideoParams={hubspotVideoParams}
+    >
+      <VideoPlayerProvider video={resolvedVideo}>
+        <TranslationsProvider translations={{}} language="en">
+          <VideoPlayer
+            portalId={portalId}
+            playButtonColor={playButtonColor}
+            theme="DARK"
+          />
+        </TranslationsProvider>
+      </VideoPlayerProvider>
+    </VideoFetchProvider>
+  );
+};
+
+export default HSVideoIsland;

package/components/componentLibrary/Video/serverUtils.ts

@@ -0,0 +1,41 @@
+import {
+  getHubID,
+  getHublet,
+  useServerRenderContext,
+} from '@hubspot/cms-components';
+import {
+  // @ts-expect-error -- types not flowing through properly
+  fetchVideo,
+  // @ts-expect-error -- types not flowing through properly
+  HubSpotVideoParams,
+  // @ts-expect-error -- types not flowing through properly
+  VideoCrmObject,
+} from '@hubspot/video-player-core';
+
+type FetchHSVideoResult = VideoCrmObject | undefined;
+
+export async function fetchHSVideoServerSide(
+  videoType: 'hubspot_video' | 'embed',
+  hubspotVideoParams?: HubSpotVideoParams
+): Promise<FetchHSVideoResult> {
+  if (videoType !== 'hubspot_video' || !hubspotVideoParams?.player_id) {
+    return undefined;
+  }
+
+  const portalId = getHubID();
+  const { environmentConfig } = useServerRenderContext();
+  const env = environmentConfig.getInternalHSEnv();
+
+  try {
+    const response = await fetchVideo(
+      hubspotVideoParams.player_id,
+      portalId,
+      env,
+      getHublet()
+    );
+    return response.video;
+  } catch (err) {
+    console.error(err);
+    return undefined;
+  }
+}

package/components/componentLibrary/Video/types.ts

@@ -0,0 +1,74 @@
+import {
+  ColorFieldDefaults,
+  EmbedFieldDefaults,
+  ImageFieldDefaults,
+  VideoFieldDefaults,
+} from '@hubspot/cms-components/fields';
+// @ts-expect-error -- types not flowing through properly
+import { VideoCrmObject, HubSpotVideoParams } from '@hubspot/video-player-core';
+
+type ColorFieldValue = typeof ColorFieldDefaults;
+
+export type ContentFieldsProps = {
+  videoTypeLabel?: string;
+  videoTypeName?: string;
+  hsVideoLabel?: string;
+  hsVideoName?: string;
+  hsVideoDefault?: typeof VideoFieldDefaults;
+  embedVideoLabel?: string;
+  embedVideoName?: string;
+  embedVideoDefault?: typeof EmbedFieldDefaults;
+  oembedThumbnailLabel?: string;
+  oembedThumbnailName?: string;
+  oembedThumbnailDefault?: typeof ImageFieldDefaults;
+};
+
+export type StyleFieldsProps = {
+  playButtonColorLabel?: string;
+  playButtonColorName?: string;
+  playButtonColorDefault?: ColorFieldValue;
+};
+
+export type VideoProps = {
+  videoType: 'embed' | 'hubspot_video';
+  video?: VideoCrmObject;
+  hubspotVideoParams?: HubSpotVideoParams;
+  embedVideoParams?: EmbedVideoParams;
+  oembedThumbnail?: { src: string; alt?: string };
+  playButtonColor?: ColorFieldValue;
+};
+
+export type HSVideoIslandProps = {
+  video?: VideoCrmObject;
+  hubspotVideoParams: HubSpotVideoParams;
+  playButtonColor?: ColorFieldValue;
+};
+
+export type EmbedVideoIslandProps = {
+  embedVideoParams: EmbedVideoParams;
+  oembedThumbnail?: { src: string; alt?: string };
+  playButtonColor?: ColorFieldValue;
+};
+
+export type EmbedVideoParams = {
+  source_type: 'oembed' | 'html';
+  supported_oembed_types: string[];
+  // fields for 'oembed' source_type
+  size_type?: 'auto' | 'auto_custom_max' | 'auto_full_width' | 'exact';
+  width?: number;
+  height?: number;
+  max_width?: number;
+  max_height?: number;
+  oembed_url?: string;
+  oembed_response?: {
+    type: string;
+    html: string;
+    width: string;
+    height: string;
+    title?: string;
+    provider_name?: string;
+    provider_url?: string;
+  };
+  // fields for 'html' source_type
+  embed_html?: string;
+};