@hubspot/cms-component-library 0.3.8 → 0.3.10

package/components/componentLibrary/_patterns/README.md

@@ -19,6 +19,9 @@ React-related code (components, JSX-returning functions, callbacks) uses arrow f
 ### 🏷️ [Prop Naming Patterns](./prop-naming-patterns.md)
 Standardized naming conventions for component props to ensure consistency across the library.
 
+### 🏝️ [Island Patterns](./island-patterns.md)
+When and how to use islands for client-side interactivity, file structure, wrapper/island split, and multiple islands.
+
 ### 📋 [Field Patterns](./field-patterns.md)
 Field components, property ordering, visibility rules, and nested patterns.
 
@@ -33,10 +36,11 @@ Comprehensive component creation checklist, complete reference examples, step-by
 Reference these pattern files in order when building a new component:
 
 1. **[Component Structure](./component-structure.md)** - Set up files and basic structure
-2. **[Function Declaration Patterns](./function-declaration-patterns.md)** - Use arrow functions for React code
-3. **[TypeScript Patterns](./typescript-patterns.md)** - Define types in `types.ts`
-4. **[Prop Naming Patterns](./prop-naming-patterns.md)** - Name props consistently
-5. **[CSS Patterns](./css-patterns.md)** - Create styles with proper variable naming
-6. **[Field Patterns](./field-patterns.md)** - Add ContentFields and StyleFields (if needed)
-7. **[Storybook Patterns](./storybook-patterns.md)** - Create stories for documentation (optional)
-8. **[LLM Documentation Template](./llm-txt.template.md)** - Create `llm.txt` for AI/LLM consumption
+2. **[Island Patterns](./island-patterns.md)** - If the component needs client-side interactivity, set up the island split
+3. **[Function Declaration Patterns](./function-declaration-patterns.md)** - Use arrow functions for React code
+4. **[TypeScript Patterns](./typescript-patterns.md)** - Define types in `types.ts`
+5. **[Prop Naming Patterns](./prop-naming-patterns.md)** - Name props consistently
+6. **[CSS Patterns](./css-patterns.md)** - Create styles with proper variable naming
+7. **[Field Patterns](./field-patterns.md)** - Add ContentFields and StyleFields (if needed)
+8. **[Storybook Patterns](./storybook-patterns.md)** - Create stories for documentation (optional)
+9. **[LLM Documentation Template](./llm-txt.template.md)** - Create `llm.txt` for AI/LLM consumption

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

@@ -79,6 +79,14 @@ When creating a new component in componentLibrary, ensure:
 - [ ] Additional mocks created in `.storybook/mocks/` if needed
 - [ ] Mock behavior documented in argTypes descriptions
 
+### Islands (if component needs client-side interactivity)
+- [ ] Interactive logic lives in `islands/ComponentNameIsland.tsx` with a default export
+- [ ] Wrapper `index.tsx` imports island with `?island` suffix and `@ts-expect-error` comment
+- [ ] Wrapper renders `<Island module={...} />` from `@hubspot/cms-components`
+- [ ] Server-side data (if any) fetched in the wrapper and passed as props through the Island component
+- [ ] Island styles live either in `../index.module.scss` (shared with wrapper) or a dedicated `islands/index.module.scss`
+- [ ] Field components (ContentFields, StyleFields) attached to the wrapper, not the island
+
 ### Accessibility
 - [ ] Semantic HTML elements used appropriately
 - [ ] ARIA roles added when needed (e.g., `role="separator"`)

package/components/componentLibrary/_patterns/component-structure.md

@@ -8,16 +8,20 @@ All components follow a consistent file structure:
 
 ```
 ComponentName/
-├── index.tsx              # Main component implementation
+├── index.tsx              # Main component implementation (or island wrapper — see below)
 ├── index.module.scss      # Component styles
 ├── ContentFields.tsx      # Content field definitions (optional)
 ├── StyleFields.tsx        # Style field definitions (optional)
 ├── types.ts              # TypeScript type definitions
+├── islands/              # Client-side interactive implementations (optional — see Island Patterns)
+│   └── ComponentNameIsland.tsx
 └── stories/              # Storybook stories (these can be created after the component is reviewed and merged)
     ├── ComponentName.stories.tsx
     └── ComponentNameDecorator.tsx
 ```
 
+**Note:** If a component requires client-side interactivity (state, event handlers, browser APIs), the interactive logic lives in an `islands/` subdirectory and the `index.tsx` becomes a wrapper that renders `<Island module={...} />`. See [Island Patterns](./island-patterns.md) for full details.
+
 **Note:** Complex components with multiple variants (like Button) should have separate story files per variant (e.g., `Button.AsButton.stories.tsx`, `Button.AsLink.stories.tsx`).
 
 ## Class Name Building Pattern

package/components/componentLibrary/_patterns/field-patterns.md

@@ -222,6 +222,52 @@ Link component example:
 
 **Key Pattern:** Look up visibility by the configurable name prop: `visibility={fieldVisibility?.[linkName]}`
 
+#### Type-Safe fieldVisibility with Discriminated Unions
+
+Use a discriminated union to ensure `fieldVisibility` keys always match the runtime field name. When `linkName` is omitted, keys are locked to the default. When provided, keys must match it.
+
+**Single-field component:**
+```typescript
+// types.ts
+export type ContentFieldsProps<TLinkName extends string = 'link'> = {
+  linkLabel?: string;
+  linkDefault?: typeof LinkFieldDefaults;
+} & (
+  | { linkName?: never; fieldVisibility?: Partial<Record<'link', Visibility>> }
+  | { linkName: TLinkName; fieldVisibility?: Partial<Record<TLinkName, Visibility>> }
+);
+```
+
+This prevents TS from inferring `TLinkName` from `fieldVisibility` when `linkName` is omitted:
+```typescript
+// linkName omitted — fieldVisibility keys must be 'link'
+<Link.ContentFields
+  fieldVisibility={{ wrongKey: { ... } }}  // TS error: 'wrongKey' is not assignable to 'link'
+/>
+
+// linkName provided — fieldVisibility keys must match
+<Link.ContentFields
+  linkName="footerLink"
+  fieldVisibility={{ link: { ... } }}  // TS error: 'link' is not assignable to 'footerLink'
+/>
+```
+
+**Multi-field component (e.g. Button):**
+```typescript
+export type ContentFieldsProps<
+  TTextName extends string = 'buttonText',
+  TLinkName extends string = 'buttonLink',
+> = {
+  buttonTextLabel?: string;
+  buttonLinkLabel?: string;
+} & (
+  | { buttonTextName?: never; buttonLinkName?: never;
+      fieldVisibility?: Partial<Record<'buttonText' | 'buttonLink', Visibility>> }
+  | { buttonTextName: TTextName; buttonLinkName: TLinkName;
+      fieldVisibility?: Partial<Record<TTextName | TLinkName, Visibility>> }
+);
+```
+
 ## Nested Component Fields Pattern
 
 **Pattern for nested component fields:**

package/components/componentLibrary/_patterns/island-patterns.md

@@ -0,0 +1,136 @@
+# Island Patterns
+
+This document covers when and how to use islands within component directories. Islands enable client-side interactivity (state, event handlers, browser APIs) while keeping the component's public API identical to non-island components.
+
+## When to Use an Island
+
+Create an island when a component requires **client-side interactivity** — anything that needs JavaScript to run in the browser after the initial server render:
+
+- State management (`useState`, `useReducer`)
+- Event handlers (`onClick`, `onSubmit`, `onChange`)
+- Browser APIs (`window`, `document`, DOM measurements)
+- Effects (`useEffect`, `useLayoutEffect`)
+
+**Examples in this library:** LanguageSwitcher (drawer toggle), Form (form submission), NavigationMenu and VerticalMenu (menu interactions).
+
+If a component is purely presentational (no state, no handlers), it does **not** need an island.
+
+## File Structure
+
+```
+ComponentName/
+├── index.tsx                    # Wrapper — imports island, renders <Island module={...} />
+├── index.module.scss            # Styles (may be shared with island — see Key details below)
+├── ContentFields.tsx            # Content field definitions
+├── StyleFields.tsx              # Style field definitions
+├── types.ts                     # TypeScript type definitions
+├── islands/
+│   └── ComponentNameIsland.tsx  # Interactive implementation (default export)
+└── stories/
+    └── ComponentName.stories.tsx
+```
+
+The `islands/` subdirectory lives inside the component directory. The island file is named `ComponentNameIsland.tsx`.
+
+## The Wrapper (`index.tsx`)
+
+The wrapper is the component's public entry point. It imports the island, wraps it in the `<Island>` component from `@hubspot/cms-components`, and attaches field components via the standard compound component pattern.
+
+```typescript
+// @ts-expect-error -- ?island not typed
+import ComponentNameIsland from './islands/ComponentNameIsland.js?island';
+import { Island } from '@hubspot/cms-components';
+import ContentFields from './ContentFields.js';
+import StyleFields from './StyleFields.js';
+import type { ComponentNameProps } from './types.js';
+
+const ComponentNameComponent = (props: ComponentNameProps) => {
+  return <Island module={ComponentNameIsland} {...props} />;
+};
+
+type ComponentNameComponentType = typeof ComponentNameComponent & {
+  ContentFields: typeof ContentFields;
+  StyleFields: typeof StyleFields;
+};
+
+const ComponentName = ComponentNameComponent as ComponentNameComponentType;
+ComponentName.ContentFields = ContentFields;
+ComponentName.StyleFields = StyleFields;
+
+export default ComponentName;
+```
+
+**Key details:**
+
+- The `?island` query parameter on the import tells the CMS build system to treat this module as an island entry point.
+- `@ts-expect-error` is required because TypeScript doesn't understand the `?island` suffix.
+- The wrapper can perform **server-side work** before passing props to the island. For example, LanguageSwitcher calls `useLanguageVariants()` here and passes the result as a prop.
+- Field components (ContentFields, StyleFields) are attached to the **wrapper**, not the island.
+
+## The Island File (`islands/ComponentNameIsland.tsx`)
+
+The island file is a standard React component with a default export. It contains all the interactive logic.
+
+```typescript
+import styles from '../index.module.scss';
+import cx from '../../utils/classname.js';
+import type { ComponentNameIslandProps } from '../types.js';
+
+const ComponentNameIsland = ({
+  className = '',
+  style = {},
+  ...rest
+}: ComponentNameIslandProps) => {
+  // Client-side state, handlers, effects go here
+
+  const combinedClasses = cx(styles.componentName, className);
+
+  return (
+    <div className={combinedClasses} style={style}>
+      {/* Interactive UI */}
+    </div>
+  );
+};
+
+export default ComponentNameIsland;
+```
+
+**Key details:**
+
+- The island can either share the parent component's stylesheet (`../index.module.scss`) or have its own stylesheet (`./index.module.scss`) inside the `islands/` directory — pick whichever fits the component.
+- The island can import and compose other library components (Button, Drawer, Divider, etc.).
+- Island props may differ from the wrapper's props. Define separate types in `types.ts` (e.g., `ComponentNameProps` for the wrapper, `ComponentNameIslandProps` for the island).
+
+## Multiple Islands
+
+A component can contain multiple island files, selected at render time based on props. The Form component demonstrates this:
+
+```typescript
+// @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 { Island } from '@hubspot/cms-components';
+
+const FormComponent = ({ formVersion, ...rest }: FormProps) => {
+  const FormModule = formVersion === 'v4' ? FormIsland : LegacyFormIsland;
+  return <Island module={FormModule} {...rest} />;
+};
+```
+
+Each island file follows the same pattern — default export a React component.
+
+## Key Principle
+
+**Modules consuming an island component don't need to know it's an island.** The wrapper fully abstracts the island boundary. Modules use island components exactly like any other component:
+
+```tsx
+// Module usage — identical whether the component uses an island or not
+<ComponentName someProp="value" />
+
+// Fields usage — same compound component pattern
+<ComponentName.ContentFields />
+<ComponentName.StyleFields />
+```
+
+This means converting a presentational component to an island component (or vice versa) doesn't require changes to any consuming modules.

package/components/componentLibrary/utils/index.ts

@@ -0,0 +1 @@
+export { fetchHSVideoServerSide } from '../Video/serverUtils.js';

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@hubspot/cms-component-library",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "HubSpot CMS React component library for building CMS modules",
   "license": "Apache-2.0",
   "exports": {
     "./VerticalMenu": "./components/componentLibrary/Menu/VerticalMenu/index.tsx",
     "./NavigationMenu": "./components/componentLibrary/Menu/NavigationMenu/index.tsx",
+    "./utils": "./components/componentLibrary/utils/index.ts",
     "./*": "./components/componentLibrary/*/index.tsx"
   },
   "files": [
@@ -21,7 +22,8 @@
   },
   "type": "module",
   "dependencies": {
-    "@hubspot/cms-components": "1.2.19",
+    "@hubspot/cms-components": "1.2.23",
+    "@hubspot/video-player-core": "0.1.21",
     "sass-embedded": "^1.97.3"
   },
   "peerDependencies": {
@@ -30,7 +32,6 @@
   "devDependencies": {
     "@types/node": "^20.0.0",
     "@vitejs/plugin-react": "4.6.0",
-    "@hubspot/cms-dev-server": "^1.0.0",
     "typescript": "^5.0.0"
   },
   "author": "content-assets",