@hubspot/cms-component-library 0.1.0-alpha.1

package/components/componentLibrary/utils/chainApi/index.ts

@@ -0,0 +1,115 @@
+import {
+  DimensionAPI,
+  OptionAPI,
+  DimensionConfiguration,
+} from '../../types/index.js';
+import { createStateManager } from './stateManager.js';
+import { createChoiceFieldGenerator } from './choiceFieldGenerator.js';
+
+const createDimensionAPI = (
+  stateManager: ReturnType<typeof createStateManager>,
+  currentDimension?: string
+): DimensionAPI => {
+  return {
+    setDimension: (dimensionKey: string): DimensionAPI => {
+      stateManager.setCurrentDimension(dimensionKey);
+      return createDimensionAPI(stateManager, dimensionKey);
+    },
+
+    label: (label: string): DimensionAPI => {
+      if (!currentDimension) {
+        throw new Error('Must call setDimension before setting a label');
+      }
+      stateManager.setDimensionLabel(currentDimension, label);
+      return createDimensionAPI(stateManager, currentDimension);
+    },
+
+    setOption: (optionKey: string): OptionAPI => {
+      if (!currentDimension) {
+        throw new Error('Must call setDimension before adding options');
+      }
+
+      stateManager.addOptionToCurrentDimension(optionKey);
+      return createOptionAPI(stateManager, currentDimension, optionKey);
+    },
+
+    createDimensionChoiceField: () => {
+      if (!stateManager.getCurrentDimension()) {
+        throw new Error(
+          'Must call setDimension before createDimensionChoiceField'
+        );
+      }
+
+      const dimensionKey = stateManager.getCurrentDimension();
+      const dimensionTree = stateManager.getActiveConfiguration()[dimensionKey];
+
+      if (!dimensionTree || !dimensionTree.options) {
+        throw new Error(`No options found for dimension: ${dimensionKey}`);
+      }
+
+      // Create choice field generator for single dimension
+      const singleDimensionConfig = { [dimensionKey]: dimensionTree };
+      const choiceFieldGenerator = createChoiceFieldGenerator(
+        singleDimensionConfig,
+        stateManager.getDimensionLabels(),
+        stateManager.getOptionLabels()
+      );
+
+      const builtChoiceField =
+        choiceFieldGenerator.createDimensionChoiceField();
+
+      stateManager.setDimensionChoiceField(
+        dimensionKey,
+        builtChoiceField[dimensionKey]
+      );
+
+      return createDimensionAPI(stateManager, dimensionKey);
+    },
+  };
+};
+
+const createOptionAPI = (
+  stateManager: ReturnType<typeof createStateManager>,
+  dimensionKey: string,
+  optionKey: string
+): OptionAPI => {
+  // Option API extends dimension API functionality
+  const dimensionAPI = createDimensionAPI(stateManager, dimensionKey);
+
+  return {
+    ...dimensionAPI,
+
+    setProps: (styleProps: Record<string, unknown>): OptionAPI => {
+      stateManager.setOptionProps(dimensionKey, optionKey, styleProps);
+      return createOptionAPI(stateManager, dimensionKey, optionKey);
+    },
+
+    label: (label: string): OptionAPI => {
+      stateManager.setOptionLabel(dimensionKey, optionKey, label);
+      return createOptionAPI(stateManager, dimensionKey, optionKey);
+    },
+
+    setOption: (newOptionKey: string): OptionAPI => {
+      stateManager.addOptionToCurrentDimension(newOptionKey);
+      return createOptionAPI(stateManager, dimensionKey, newOptionKey);
+    },
+  };
+};
+
+export const createChainApi = (
+  stateManager: ReturnType<typeof createStateManager>
+) => {
+  const baseDimensionAPI = createDimensionAPI(stateManager);
+
+  return {
+    setDimension: baseDimensionAPI.setDimension,
+    getActiveConfiguration: (): DimensionConfiguration => {
+      return stateManager.getActiveConfiguration();
+    },
+    getCurrentDimension: (): string | null => {
+      // Note: This assumes stateManager exposes getCurrentDimension
+      // If not available, this can be removed or stateManager can be enhanced
+      return null;
+    },
+  };
+};

package/components/componentLibrary/utils/chainApi/labelGenerator.ts

@@ -0,0 +1,76 @@
+/**
+ * Generates a default label from a key by converting:
+ * - camelCase: 'extraLarge' → 'Extra Large'
+ * - snake_case: 'primary_button' → 'Primary Button'
+ * - kebab-case: 'primary-button' → 'Primary Button'
+ */
+export const generateDefaultLabel = (key: string): string => {
+  return key
+    .replace(/([A-Z])/g, ' $1') // camelCase: 'extraLarge' → 'extra Large'
+    .replace(/[_-]/g, ' ') // snake_case/kebab: 'primary_button' → 'primary button'
+    .replace(/\b\w/g, letter => letter.toUpperCase()) // Title case: 'extra large' → 'Extra Large'
+    .trim();
+};
+
+/**
+ * Gets the label for a dimension, using stored label or auto-generating
+ */
+export const getDimensionLabel = (
+  dimensionKey: string,
+  dimensionLabels: Record<string, string>
+): string => {
+  return dimensionLabels[dimensionKey] || generateDefaultLabel(dimensionKey);
+};
+
+/**
+ * Gets the label for an option, using stored label or auto-generating
+ */
+export const getOptionLabel = (
+  dimensionKey: string,
+  optionKey: string,
+  optionLabels: Record<string, Record<string, string>>
+): string => {
+  return (
+    optionLabels[dimensionKey]?.[optionKey] || generateDefaultLabel(optionKey)
+  );
+};
+
+/**
+ * Generates choices array with labels for a dimension
+ */
+export const generateChoicesWithLabels = (
+  dimensionKey: string,
+  options: Record<string, unknown>,
+  optionLabels: Record<string, Record<string, string>>
+): [string, string][] => {
+  const choices: [string, string][] = [];
+
+  for (const optionKey in options) {
+    const optionLabel = getOptionLabel(dimensionKey, optionKey, optionLabels);
+    choices.push([optionKey, optionLabel]);
+  }
+
+  return choices;
+};
+
+/**
+ * Creates a label generator factory with predefined labels
+ * Returns functions that have access to the provided label stores
+ */
+export const createLabelGenerator = (
+  dimensionLabels: Record<string, string>,
+  optionLabels: Record<string, Record<string, string>>
+) => {
+  return {
+    getDimensionLabel: (dimensionKey: string) =>
+      getDimensionLabel(dimensionKey, dimensionLabels),
+
+    getOptionLabel: (dimensionKey: string, optionKey: string) =>
+      getOptionLabel(dimensionKey, optionKey, optionLabels),
+
+    generateChoicesWithLabels: (
+      dimensionKey: string,
+      options: Record<string, unknown>
+    ) => generateChoicesWithLabels(dimensionKey, options, optionLabels),
+  };
+};

package/components/componentLibrary/utils/chainApi/stateManager.ts

@@ -0,0 +1,178 @@
+import {
+  ComponentState,
+  DimensionChoiceField,
+  DimensionConfiguration,
+} from '../../types/index.js';
+
+function isNotValidName(name: string): boolean {
+  return /[\s-]/.test(name);
+}
+
+/**
+ * Creates initial component state
+ */
+const createInitialState = (): ComponentState => ({
+  dimensionConfiguration: {},
+  userConfiguration: null,
+  dimensionLabels: {},
+  optionLabels: {},
+  currentDimension: null,
+  dimensionChoiceFields: {},
+});
+
+/**
+ * Creates a state manager instance with encapsulated state
+ */
+export const createStateManager = () => {
+  const state = createInitialState();
+
+  /**
+   * Updates the working configuration and syncs user configuration
+   */
+  const updateDimensionConfiguration = (
+    updater: (config: DimensionConfiguration) => DimensionConfiguration
+  ): void => {
+    state.dimensionConfiguration = updater(state.dimensionConfiguration);
+    state.userConfiguration = { ...state.dimensionConfiguration };
+  };
+
+  /**
+   * Sets the current dimension in the state
+   */
+  const setCurrentDimension = (dimensionKey: string): void => {
+    state.currentDimension = dimensionKey;
+
+    if (isNotValidName(dimensionKey)) {
+      throw new Error(
+        `\nDimension name cannot contain spaces or hyphens. Please use camelCase or snake_case.\nDimension: ${dimensionKey}`
+      );
+    }
+
+    // Initialize dimension if it doesn't exist
+    if (!state.dimensionConfiguration[dimensionKey]) {
+      updateDimensionConfiguration(config => ({
+        ...config,
+        [dimensionKey]: { options: {} },
+      }));
+    }
+
+    // Initialize option labels for this dimension
+    if (!state.optionLabels[dimensionKey]) {
+      state.optionLabels[dimensionKey] = {};
+    }
+  };
+
+  /**
+   * Sets a dimension label
+   */
+  const setDimensionLabel = (dimensionKey: string, label: string): void => {
+    state.dimensionLabels[dimensionKey] = label;
+  };
+
+  /**
+   * Sets an option label
+   */
+  const setOptionLabel = (
+    dimensionKey: string,
+    optionKey: string,
+    label: string
+  ): void => {
+    if (!state.optionLabels[dimensionKey]) {
+      state.optionLabels[dimensionKey] = {};
+    }
+    state.optionLabels[dimensionKey][optionKey] = label;
+  };
+
+  /**
+   * Adds an option to the current dimension
+   */
+  const addOptionToCurrentDimension = (optionKey: string): void => {
+    if (!state.currentDimension) {
+      throw new Error('Must call setDimension before adding options');
+    }
+
+    if (isNotValidName(optionKey)) {
+      throw new Error(
+        `\nOption name cannot contain spaces or hyphens. Please use camelCase or snake_case.\nOption: ${optionKey}`
+      );
+    }
+
+    updateDimensionConfiguration(config => ({
+      ...config,
+      [state.currentDimension!]: {
+        ...config[state.currentDimension!],
+        options: {
+          ...config[state.currentDimension!].options,
+          [optionKey]: { props: {} },
+        },
+      },
+    }));
+  };
+
+  /**
+   * Sets props for a specific option
+   */
+  const setOptionProps = (
+    dimensionKey: string,
+    optionKey: string,
+    props: Record<string, unknown>
+  ): void => {
+    updateDimensionConfiguration(config => ({
+      ...config,
+      [dimensionKey]: {
+        ...config[dimensionKey],
+        options: {
+          ...config[dimensionKey].options,
+          [optionKey]: {
+            ...config[dimensionKey].options[optionKey],
+            props,
+          },
+        },
+      },
+    }));
+  };
+
+  const setDimensionChoiceField = (
+    dimensionKey: string,
+    choiceField: DimensionChoiceField
+  ): void => {
+    state.dimensionChoiceFields[dimensionKey] = choiceField;
+  };
+
+  const getCurrentDimension = (): string => {
+    return state.currentDimension || '';
+  };
+
+  const getDimensionLabels = (): Record<string, string> => {
+    return state.dimensionLabels;
+  };
+
+  const getOptionLabels = (): Record<string, Record<string, string>> => {
+    return state.optionLabels;
+  };
+
+  const getDimensionChoiceFields = (): Record<string, DimensionChoiceField> => {
+    return state.dimensionChoiceFields;
+  };
+
+  /**
+   * Gets the active configuration (user config if available, otherwise empty)
+   */
+  const getActiveConfiguration = (): DimensionConfiguration => {
+    return state.userConfiguration || {};
+  };
+
+  return {
+    addOptionToCurrentDimension,
+    setCurrentDimension,
+    setDimensionLabel,
+    setOptionLabel,
+    setOptionProps,
+    setDimensionChoiceField,
+    getActiveConfiguration,
+    getCurrentDimension,
+    getDimensionLabels,
+    getOptionLabels,
+    getDimensionChoiceFields,
+  };
+};

package/components/componentLibrary/utils/classname.ts

@@ -0,0 +1,40 @@
+/**
+ * Combines multiple class name inputs into a single space-separated string.
+ * Supports strings, arrays, and objects where keys with truthy values are included.
+ * All whitespace is properly trimmed and empty values are excluded.
+ * Basically this is a replacement for the classnames library.
+ */
+export default function cx(...args: unknown[]): string {
+  const classes: string[] = [];
+
+  // Process all arguments
+  args.flat(Infinity).forEach(arg => {
+    // Skip falsy values early
+    if (!arg) return;
+
+    // Handle string arguments
+    if (typeof arg === 'string') {
+      const trimmed = arg.trim();
+      if (trimmed) {
+        classes.push(trimmed);
+      }
+      return;
+    }
+
+    // Handle object arguments (className: condition pairs)
+    if (typeof arg === 'object' && arg !== null && !Array.isArray(arg)) {
+      Object.entries(arg as Record<string, unknown>).forEach(([key, value]) => {
+        // Only include keys with truthy values
+        if (value) {
+          const trimmed = key.trim();
+          if (trimmed) {
+            classes.push(trimmed);
+          }
+        }
+      });
+    }
+  });
+
+  // Join all classes with a single space
+  return classes.join(' ');
+}

package/components/componentLibrary/utils/createConditionalClasses.ts

@@ -0,0 +1,44 @@
+import { convertToKebabCase } from './propResolution/createCssVariables.js';
+import { STYLE_COMPONENT_PROPS, BaseComponentProps } from '../types/index.js';
+
+/**
+ * Creates conditional CSS classes based on which props have values.
+ * Only generates classes for props that are defined and not null/undefined.
+ *
+ * @param props - Component props to analyze
+ * @param componentName - Name of the component for class naming
+ * @returns Array of conditional class names
+ *
+ * @example
+ * createConditionalClasses({ color: 'red', fontSize: '16px' }, 'heading')
+ * // Returns: ['color', 'font-size']
+ */
+export const createConditionalClasses = (
+  props: Partial<BaseComponentProps>,
+  componentName?: string | null
+): string[] => {
+  if (!componentName) return [];
+
+  const conditionalClasses: string[] = [];
+
+  // Iterate through passed props that have values
+  for (const propName of Object.keys(props)) {
+    const propValue = props[propName as keyof BaseComponentProps];
+
+    // Skip if prop has no value
+    if (propValue === undefined || propValue === null) continue;
+
+    // Only process props that are defined in STYLE_COMPONENT_PROPS
+    if (!(propName in STYLE_COMPONENT_PROPS)) continue;
+
+    // Skip non-primitive values (objects, arrays, functions)
+    if (typeof propValue !== 'string' && typeof propValue !== 'number')
+      continue;
+
+    // Generate the conditional class name using existing kebab case conversion
+    const kebabProp = convertToKebabCase(propName);
+    conditionalClasses.push(`hsclStyle-${kebabProp}`);
+  }
+
+  return conditionalClasses;
+};

package/components/componentLibrary/utils/createHsclComponent.tsx

@@ -0,0 +1,167 @@
+import React from 'react';
+import {
+  AnyReactComponent,
+  ComponentPropsType,
+  DimensionAPI,
+  DimensionChoiceField,
+  InferPublicProps,
+} from '../types/index.js';
+import { resolveAllProps } from './propResolution/propResolutionUtils.js';
+import { createCSSVariables } from './propResolution/createCssVariables.js';
+import { createConditionalClasses } from './createConditionalClasses.js';
+import cx from './classname.js';
+import { createStateManager } from './chainApi/stateManager.js';
+import { createChainApi } from './chainApi/index.js';
+
+// Helper function for creating typed instances with custom props
+export const createComponentInstance = <P,>(
+  instance: CreateHsclComponentType<AnyReactComponent>
+): CreateHsclComponentType<AnyReactComponent, P> => {
+  return instance.create() as CreateHsclComponentType<AnyReactComponent, P>;
+};
+
+type FieldsReturn<T> = (props: T) => React.ReactElement;
+
+type NullableFieldsReturn<T> = FieldsReturn<T> | null | undefined;
+
+type FieldsGetter<T> = T extends never ? undefined : NullableFieldsReturn<T>;
+
+export type CreateHsclComponentType<
+  T extends AnyReactComponent,
+  P = InferPublicProps<T>,
+  CFP = never,
+  SFP = never
+> = ((props: P) => React.ReactElement) & {
+  ContentFields: FieldsGetter<CFP>;
+  StyleFields: FieldsGetter<SFP>;
+
+  // Field methods return new instances (immutable)
+  withContentFields<CF>(
+    contentFieldsFunction: FieldsReturn<CF>
+  ): CreateHsclComponentType<T, P, CF, SFP>;
+  withStyleFields<SF>(
+    styleFieldsFunction: FieldsReturn<SF>
+  ): CreateHsclComponentType<T, P, CFP, SF>;
+  DimensionChoiceFields: Record<string, DimensionChoiceField>;
+  setDimension: (arg: string) => DimensionAPI;
+  create: () => CreateHsclComponentType<T, P, CFP, SFP>;
+};
+
+const createHsclComponent = <
+  T extends AnyReactComponent,
+  CFP = never,
+  SFP = never
+>(
+  component: T,
+  contentFields: NullableFieldsReturn<CFP> = null,
+  styleFields: NullableFieldsReturn<SFP> = null,
+  stateManager = createStateManager()
+): CreateHsclComponentType<T, InferPublicProps<T>, CFP, SFP> => {
+  const componentName: string | null = component.hsclComponentName;
+  const componentCssModuleStyles = component.cssModule[componentName];
+
+  const processedComponent = (props: InferPublicProps<T>) => {
+    // Resolve props with 3-way separation if component has propKeys defined
+    const resolvedProps = resolveAllProps(stateManager, props);
+
+    const cssVars = createCSSVariables(
+      resolvedProps.baseResolvedProps,
+      componentName
+    );
+
+    // Generate conditional classes based on which props have values
+    const conditionalClasses = createConditionalClasses(
+      resolvedProps.baseResolvedProps,
+      componentName
+    );
+
+    // process and standardize classnames
+    const processedClasses = cx(
+      'hscl-component',
+      `hscl-${componentName}`,
+      resolvedProps.baseResolvedProps.className,
+      componentCssModuleStyles,
+      ...conditionalClasses
+    );
+
+    // Build hsclInternal props for component (hidden from public)
+    const hsclInternal = {
+      hsclProcessedClasses: processedClasses,
+      hsclResolvedProps: resolvedProps.baseResolvedProps,
+      hsclCssVars: cssVars,
+      hsclProcessedStyles: {
+        ...resolvedProps.baseResolvedProps.style,
+        ...cssVars,
+      },
+    };
+
+    // combine with all other props
+    const propsToPassAlongToComponent = {
+      ...resolvedProps.remainingProps,
+      hsclInternal,
+    };
+
+    return React.createElement(
+      component,
+      propsToPassAlongToComponent as ComponentPropsType<T>
+    );
+  };
+
+  const chainableAPI = createChainApi(stateManager);
+
+  // Create the API methods object
+  const apiMethods = {
+    get ContentFields(): FieldsGetter<CFP> {
+      return contentFields as FieldsGetter<CFP>;
+    },
+
+    get StyleFields(): FieldsGetter<SFP> {
+      return styleFields as FieldsGetter<SFP>;
+    },
+
+    get DimensionChoiceFields() {
+      return stateManager.getDimensionChoiceFields() as Record<
+        string,
+        DimensionChoiceField
+      >;
+    },
+
+    // Field methods return NEW instances (immutable pattern)
+    withContentFields<CF>(contentFieldsFunction: FieldsReturn<CF>) {
+      return createHsclComponent<T, CF, SFP>(
+        component,
+        contentFieldsFunction,
+        styleFields,
+        stateManager
+      );
+    },
+
+    withStyleFields<SF>(styleFieldsFunction: FieldsReturn<SF>) {
+      return createHsclComponent<T, CFP, SF>(
+        component,
+        contentFields,
+        styleFieldsFunction,
+        stateManager
+      );
+    },
+
+    // Chain API methods keep mutable pattern (same stateManager)
+    setDimension: chainableAPI.setDimension,
+
+    create() {
+      return createHsclComponent<T, CFP, SFP>(
+        component,
+        contentFields,
+        styleFields,
+        createStateManager()
+      );
+    },
+  };
+
+  // Create a callable component function with attached properties
+  const callableComponent = Object.assign(processedComponent, apiMethods);
+
+  return callableComponent;
+};
+
+export default createHsclComponent;

package/components/componentLibrary/utils/propResolution/createCssVariables.ts

@@ -0,0 +1,58 @@
+import {
+  BaseComponentProps,
+  STYLE_COMPONENT_PROPS,
+  CSSVariableMap,
+} from '../../types/index.js';
+
+const shouldConvertToString = (value: string | number): boolean =>
+  typeof value === 'number' ||
+  (typeof value === 'string' && /^\d+$/.test(value));
+
+export const convertToKebabCase = (camelCaseString: string): string =>
+  camelCaseString.replace(
+    /[A-Z]/g,
+    capitalLetter => `-${capitalLetter.toLowerCase()}`
+  );
+
+export const convertValueToString = (value: string | number): string => {
+  if (typeof value === 'number') {
+    return `${value}`;
+  }
+  return value;
+};
+
+export const createCSSVariables = (
+  props: Partial<BaseComponentProps>,
+  componentName?: string
+): CSSVariableMap => {
+  const cssVariables: CSSVariableMap = {};
+
+  // Determine the prefix for CSS variable names
+  const variablePrefix = componentName
+    ? `--hscl-${componentName}`
+    : '--hscl-component';
+
+  // Process only style-related props using for...of for better readability
+  for (const propName of Object.keys(STYLE_COMPONENT_PROPS)) {
+    const propValue = props[propName as keyof BaseComponentProps];
+
+    // Skip undefined values
+    if (propValue === undefined) continue;
+
+    // Skip non-primitive values (like CSSProperties objects)
+    if (typeof propValue !== 'string' && typeof propValue !== 'number')
+      continue;
+
+    // Generate CSS variable name with component-specific or generic prefix
+    const variableName = `${variablePrefix}-${convertToKebabCase(propName)}`;
+
+    // Convert value to appropriate format
+    const finalValue = shouldConvertToString(propValue)
+      ? convertValueToString(propValue)
+      : propValue;
+
+    cssVariables[variableName] = finalValue;
+  }
+
+  return cssVariables;
+};