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

package/components/componentLibrary/index.ts

@@ -0,0 +1 @@
+export { createComponentInstance } from './utils/createHsclComponent.js';

package/components/componentLibrary/styles/_component-base.scss

@@ -0,0 +1,246 @@
+// Auto-generated conditional styles
+// DO NOT EDIT MANUALLY - Generated from STYLE_COMPONENT_PROPS
+// Run: npm run generate-conditional-styles to regenerate
+
+@mixin hscl-component-conditional($component-name) {
+  &:global(.hsclStyle-color) {
+    color: var(--hscl-#{$component-name}-color, revert-layer);
+  }
+  &:global(.hsclStyle-background) {
+    background: var(--hscl-#{$component-name}-background, revert-layer);
+  }
+  &:global(.hsclStyle-background-color) {
+    background-color: var(--hscl-#{$component-name}-background-color, revert-layer);
+  }
+  &:global(.hsclStyle-font-size) {
+    font-size: var(--hscl-#{$component-name}-font-size, revert-layer);
+  }
+  &:global(.hsclStyle-font-style) {
+    font-style: var(--hscl-#{$component-name}-font-style, revert-layer);
+  }
+  &:global(.hsclStyle-font-weight) {
+    font-weight: var(--hscl-#{$component-name}-font-weight, revert-layer);
+  }
+  &:global(.hsclStyle-font-family) {
+    font-family: var(--hscl-#{$component-name}-font-family, revert-layer);
+  }
+  &:global(.hsclStyle-line-height) {
+    line-height: var(--hscl-#{$component-name}-line-height, revert-layer);
+  }
+  &:global(.hsclStyle-letter-spacing) {
+    letter-spacing: var(--hscl-#{$component-name}-letter-spacing, revert-layer);
+  }
+  &:global(.hsclStyle-text-align) {
+    text-align: var(--hscl-#{$component-name}-text-align, revert-layer);
+  }
+  &:global(.hsclStyle-text-transform) {
+    text-transform: var(--hscl-#{$component-name}-text-transform, revert-layer);
+  }
+  &:global(.hsclStyle-text-decoration) {
+    text-decoration: var(--hscl-#{$component-name}-text-decoration, revert-layer);
+  }
+  &:global(.hsclStyle-cursor) {
+    cursor: var(--hscl-#{$component-name}-cursor, revert-layer);
+  }
+  &:global(.hsclStyle-opacity) {
+    opacity: var(--hscl-#{$component-name}-opacity, revert-layer);
+  }
+  &:global(.hsclStyle-box-shadow) {
+    box-shadow: var(--hscl-#{$component-name}-box-shadow, revert-layer);
+  }
+  &:global(.hsclStyle-transition) {
+    transition: var(--hscl-#{$component-name}-transition, revert-layer);
+  }
+  &:global(.hsclStyle-transition-property) {
+    transition-property: var(--hscl-#{$component-name}-transition-property, revert-layer);
+  }
+  &:global(.hsclStyle-transition-duration) {
+    transition-duration: var(--hscl-#{$component-name}-transition-duration, revert-layer);
+  }
+  &:global(.hsclStyle-transition-timing-function) {
+    transition-timing-function: var(--hscl-#{$component-name}-transition-timing-function, revert-layer);
+  }
+  &:global(.hsclStyle-transition-delay) {
+    transition-delay: var(--hscl-#{$component-name}-transition-delay, revert-layer);
+  }
+  &:global(.hsclStyle-transform) {
+    transform: var(--hscl-#{$component-name}-transform, revert-layer);
+  }
+  &:global(.hsclStyle-transform-origin) {
+    transform-origin: var(--hscl-#{$component-name}-transform-origin, revert-layer);
+  }
+  &:global(.hsclStyle-border-block-start) {
+    border-block-start: var(--hscl-#{$component-name}-border-block-start, revert-layer);
+  }
+  &:global(.hsclStyle-border-block-end) {
+    border-block-end: var(--hscl-#{$component-name}-border-block-end, revert-layer);
+  }
+  &:global(.hsclStyle-border-inline-start) {
+    border-inline-start: var(--hscl-#{$component-name}-border-inline-start, revert-layer);
+  }
+  &:global(.hsclStyle-border-inline-end) {
+    border-inline-end: var(--hscl-#{$component-name}-border-inline-end, revert-layer);
+  }
+  &:global(.hsclStyle-border) {
+    border: var(--hscl-#{$component-name}-border, revert-layer);
+  }
+  &:global(.hsclStyle-border-radius) {
+    border-radius: var(--hscl-#{$component-name}-border-radius, revert-layer);
+  }
+  &:global(.hsclStyle-outline) {
+    outline: var(--hscl-#{$component-name}-outline, revert-layer);
+  }
+  &:global(.hsclStyle-margin-inline) {
+    margin-inline: var(--hscl-#{$component-name}-margin-inline, revert-layer);
+  }
+  &:global(.hsclStyle-margin-block) {
+    margin-block: var(--hscl-#{$component-name}-margin-block, revert-layer);
+  }
+  &:global(.hsclStyle-margin) {
+    margin: var(--hscl-#{$component-name}-margin, revert-layer);
+  }
+  &:global(.hsclStyle-padding-inline) {
+    padding-inline: var(--hscl-#{$component-name}-padding-inline, revert-layer);
+  }
+  &:global(.hsclStyle-padding-block) {
+    padding-block: var(--hscl-#{$component-name}-padding-block, revert-layer);
+  }
+  &:global(.hsclStyle-padding) {
+    padding: var(--hscl-#{$component-name}-padding, revert-layer);
+  }
+  &:global(.hsclStyle-position) {
+    position: var(--hscl-#{$component-name}-position, revert-layer);
+  }
+  &:global(.hsclStyle-top) {
+    top: var(--hscl-#{$component-name}-top, revert-layer);
+  }
+  &:global(.hsclStyle-right) {
+    right: var(--hscl-#{$component-name}-right, revert-layer);
+  }
+  &:global(.hsclStyle-bottom) {
+    bottom: var(--hscl-#{$component-name}-bottom, revert-layer);
+  }
+  &:global(.hsclStyle-left) {
+    left: var(--hscl-#{$component-name}-left, revert-layer);
+  }
+  &:global(.hsclStyle-z-index) {
+    z-index: var(--hscl-#{$component-name}-z-index, revert-layer);
+  }
+  &:global(.hsclStyle-width) {
+    width: var(--hscl-#{$component-name}-width, revert-layer);
+  }
+  &:global(.hsclStyle-height) {
+    height: var(--hscl-#{$component-name}-height, revert-layer);
+  }
+  &:global(.hsclStyle-min-width) {
+    min-width: var(--hscl-#{$component-name}-min-width, revert-layer);
+  }
+  &:global(.hsclStyle-min-height) {
+    min-height: var(--hscl-#{$component-name}-min-height, revert-layer);
+  }
+  &:global(.hsclStyle-max-width) {
+    max-width: var(--hscl-#{$component-name}-max-width, revert-layer);
+  }
+  &:global(.hsclStyle-max-height) {
+    max-height: var(--hscl-#{$component-name}-max-height, revert-layer);
+  }
+  &:global(.hsclStyle-display) {
+    display: var(--hscl-#{$component-name}-display, revert-layer);
+  }
+  &:global(.hsclStyle-overflow) {
+    overflow: var(--hscl-#{$component-name}-overflow, revert-layer);
+  }
+  &:global(.hsclStyle-visibility) {
+    visibility: var(--hscl-#{$component-name}-visibility, revert-layer);
+  }
+  &:global(.hsclStyle-justify-content) {
+    justify-content: var(--hscl-#{$component-name}-justify-content, revert-layer);
+  }
+  &:global(.hsclStyle-align-items) {
+    align-items: var(--hscl-#{$component-name}-align-items, revert-layer);
+  }
+  &:global(.hsclStyle-flex-direction) {
+    flex-direction: var(--hscl-#{$component-name}-flex-direction, revert-layer);
+  }
+  &:global(.hsclStyle-gap) {
+    gap: var(--hscl-#{$component-name}-gap, revert-layer);
+  }
+  &:global(.hsclStyle-align-self) {
+    align-self: var(--hscl-#{$component-name}-align-self, revert-layer);
+  }
+  &:global(.hsclStyle-flex) {
+    flex: var(--hscl-#{$component-name}-flex, revert-layer);
+  }
+  &:global(.hsclStyle-flex-grow) {
+    flex-grow: var(--hscl-#{$component-name}-flex-grow, revert-layer);
+  }
+  &:global(.hsclStyle-flex-shrink) {
+    flex-shrink: var(--hscl-#{$component-name}-flex-shrink, revert-layer);
+  }
+  &:global(.hsclStyle-flex-basis) {
+    flex-basis: var(--hscl-#{$component-name}-flex-basis, revert-layer);
+  }
+  &:global(.hsclStyle-order) {
+    order: var(--hscl-#{$component-name}-order, revert-layer);
+  }
+  &:global(.hsclStyle-white-space) {
+    white-space: var(--hscl-#{$component-name}-white-space, revert-layer);
+  }
+  &:global(.hsclStyle-word-break) {
+    word-break: var(--hscl-#{$component-name}-word-break, revert-layer);
+  }
+  &:global(.hsclStyle-text-wrap) {
+    text-wrap: var(--hscl-#{$component-name}-text-wrap, revert-layer);
+  }
+  &:global(.hsclStyle-overflow-wrap) {
+    overflow-wrap: var(--hscl-#{$component-name}-overflow-wrap, revert-layer);
+  }
+  &:global(.hsclStyle-text-overflow) {
+    text-overflow: var(--hscl-#{$component-name}-text-overflow, revert-layer);
+  }
+  &:global(.hsclStyle-word-wrap) {
+    word-wrap: var(--hscl-#{$component-name}-word-wrap, revert-layer);
+  }
+  &:global(.hsclStyle-pointer-events) {
+    pointer-events: var(--hscl-#{$component-name}-pointer-events, revert-layer);
+  }
+  &:global(.hsclStyle-object-fit) {
+    object-fit: var(--hscl-#{$component-name}-object-fit, revert-layer);
+  }
+  &:global(.hsclStyle-aspect-ratio) {
+    aspect-ratio: var(--hscl-#{$component-name}-aspect-ratio, revert-layer);
+  }
+}
+
+@mixin hscl-component-hover-conditional($component-name) {
+  &:global(.hsclStyle-hover-color):hover {
+    color: var(--hscl-#{$component-name}-hover-color, revert-layer);
+  }
+  &:global(.hsclStyle-hover-background):hover {
+    background: var(--hscl-#{$component-name}-hover-background, revert-layer);
+  }
+  &:global(.hsclStyle-hover-background-color):hover {
+    background-color: var(--hscl-#{$component-name}-hover-background-color, revert-layer);
+  }
+  &:global(.hsclStyle-hover-border-block-start):hover {
+    border-block-start: var(--hscl-#{$component-name}-hover-border-block-start, revert-layer);
+  }
+  &:global(.hsclStyle-hover-border-block-end):hover {
+    border-block-end: var(--hscl-#{$component-name}-hover-border-block-end, revert-layer);
+  }
+  &:global(.hsclStyle-hover-border-inline-start):hover {
+    border-inline-start: var(--hscl-#{$component-name}-hover-border-inline-start, revert-layer);
+  }
+  &:global(.hsclStyle-hover-border-inline-end):hover {
+    border-inline-end: var(--hscl-#{$component-name}-hover-border-inline-end, revert-layer);
+  }
+  &:global(.hsclStyle-hover-opacity):hover {
+    opacity: var(--hscl-#{$component-name}-hover-opacity, revert-layer);
+  }
+  &:global(.hsclStyle-hover-transform):hover {
+    transform: var(--hscl-#{$component-name}-hover-transform, revert-layer);
+  }
+  &:global(.hsclStyle-hover-box-shadow):hover {
+    box-shadow: var(--hscl-#{$component-name}-hover-box-shadow, revert-layer);
+  }
+}

package/components/componentLibrary/types/index.ts

@@ -0,0 +1,308 @@
+// Style-related props that generate CSS variables
+
+import { ChoiceFieldType } from '@hubspot/cms-components/fields';
+
+// Typography types
+export type TextAlign = 'left' | 'center' | 'right' | 'justify';
+export type TextTransform = 'none' | 'uppercase' | 'lowercase' | 'capitalize';
+export type FontWeight = 'lighter' | 'normal' | 'bold' | 'bolder' | number;
+export type FontStyle = 'normal' | 'italic' | 'oblique';
+
+export const STYLE_COMPONENT_PROPS = {
+  // CSS property props
+  color: String,
+  background: String,
+  backgroundColor: String,
+  fontSize: [String, Number] as const,
+  fontStyle: String as () => FontStyle,
+  fontWeight: String as () => FontWeight,
+  fontFamily: String,
+  lineHeight: [String, Number] as const,
+  letterSpacing: [String, Number] as const,
+  textAlign: String as () => TextAlign,
+  textTransform: String as () => TextTransform,
+  textDecoration: String,
+  cursor: String,
+  opacity: Number,
+  boxShadow: String,
+
+  // Transition properties
+  transition: String,
+  transitionProperty: String,
+  transitionDuration: String,
+  transitionTimingFunction: String,
+  transitionDelay: String,
+
+  // Transform properties
+  transform: String,
+  transformOrigin: String,
+
+  // Border props
+  borderBlockStart: String,
+  borderBlockEnd: String,
+  borderInlineStart: String,
+  borderInlineEnd: String,
+  border: String,
+  borderRadius: [String, Number] as const,
+  outline: String,
+
+  // Hover state props
+  hoverColor: String,
+  hoverBackground: String,
+  hoverBackgroundColor: String,
+  hoverBorderBlockStart: String,
+  hoverBorderBlockEnd: String,
+  hoverBorderInlineStart: String,
+  hoverBorderInlineEnd: String,
+  hoverOpacity: Number,
+  hoverTransform: String,
+  hoverBoxShadow: String,
+
+  // Space props (margin/padding) - flexible user-defined values
+  marginInline: String,
+  marginBlock: String,
+  margin: String,
+  paddingInline: String,
+  paddingBlock: String,
+  padding: String,
+
+  // Position props
+  position: String as () =>
+    | 'static'
+    | 'relative'
+    | 'absolute'
+    | 'fixed'
+    | 'sticky',
+  top: [String, Number] as const,
+  right: [String, Number] as const,
+  bottom: [String, Number] as const,
+  left: [String, Number] as const,
+  zIndex: Number,
+
+  // Size props
+  width: [String, Number] as const,
+  height: [String, Number] as const,
+  minWidth: [String, Number] as const,
+  minHeight: [String, Number] as const,
+  maxWidth: [String, Number] as const,
+  maxHeight: [String, Number] as const,
+
+  // Display props
+  display: String as () =>
+    | 'block'
+    | 'inline'
+    | 'inline-block'
+    | 'flex'
+    | 'inline-flex'
+    | 'grid'
+    | 'none',
+  overflow: String as () => 'visible' | 'hidden' | 'scroll' | 'auto',
+  visibility: String as () => 'visible' | 'hidden' | 'collapse',
+
+  // Flex layout properties
+  justifyContent: String as () =>
+    | 'flex-start'
+    | 'center'
+    | 'flex-end'
+    | 'space-between'
+    | 'space-around'
+    | 'space-evenly'
+    | 'start'
+    | 'end',
+  alignItems: String as () =>
+    | 'stretch'
+    | 'flex-start'
+    | 'center'
+    | 'flex-end'
+    | 'baseline'
+    | 'start'
+    | 'end',
+  flexDirection: String as () => 'row' | 'column',
+  gap: [String, Number] as const,
+
+  // Flex item properties
+  alignSelf: String as () =>
+    | 'auto'
+    | 'stretch'
+    | 'flex-start'
+    | 'center'
+    | 'flex-end'
+    | 'baseline'
+    | 'start'
+    | 'end',
+  flex: [Number] as const,
+  flexGrow: Number,
+  flexShrink: Number,
+  flexBasis: [String, Number] as const,
+  order: Number,
+
+  // Enhanced text properties
+  whiteSpace: String as () =>
+    | 'normal'
+    | 'nowrap'
+    | 'pre'
+    | 'pre-line'
+    | 'pre-wrap'
+    | 'break-spaces',
+  wordBreak: String as () => 'normal' | 'break-all' | 'keep-all' | 'break-word',
+  textWrap: String as () => 'wrap' | 'nowrap' | 'balance' | 'pretty' | 'stable',
+  overflowWrap: String as () => 'normal' | 'anywhere' | 'break-word',
+  textOverflow: String as () => 'clip' | 'ellipsis' | string,
+  wordWrap: String as () => 'normal' | 'break-word' | 'anywhere',
+
+  // Interaction properties
+  pointerEvents: String as () =>
+    | 'auto'
+    | 'none'
+    | 'visiblePainted'
+    | 'visibleFill'
+    | 'visibleStroke'
+    | 'visible'
+    | 'painted'
+    | 'fill'
+    | 'stroke'
+    | 'all',
+
+  // Media/object properties
+  objectFit: String as () =>
+    | 'fill'
+    | 'contain'
+    | 'cover'
+    | 'none'
+    | 'scale-down',
+  aspectRatio: String,
+} as const;
+
+// Helper type to convert config to proper TypeScript types
+type ConvertMapToType<T> = T extends readonly [
+  StringConstructor,
+  NumberConstructor
+]
+  ? string | number
+  : T extends StringConstructor
+  ? string
+  : T extends NumberConstructor
+  ? number
+  : T extends ObjectConstructor
+  ? React.CSSProperties
+  : T extends () => infer U
+  ? U
+  : never;
+
+// Single source of truth for all base component props
+export const BASE_COMPONENT_PROPS_CONFIG = {
+  // Basic element props
+  className: String,
+  style: Object as () => React.CSSProperties,
+
+  // Spread in all style props
+  ...STYLE_COMPONENT_PROPS,
+
+  // Accessibility props
+  role: String,
+} as const;
+
+// Generate TypeScript type from the config
+export type BaseComponentProps = {
+  [K in keyof typeof BASE_COMPONENT_PROPS_CONFIG]?: ConvertMapToType<
+    (typeof BASE_COMPONENT_PROPS_CONFIG)[K]
+  >;
+};
+
+// Generate runtime keys directly from the config - exported for use in utils
+export const BASE_COMPONENT_PROP_KEYS = new Set(
+  Object.keys(BASE_COMPONENT_PROPS_CONFIG) as (keyof BaseComponentProps)[]
+);
+// ==============================================================================
+// Helpers
+// ==============================================================================
+
+// Common type constraint for React components
+export type AnyReactComponent = React.ComponentType<unknown> & {
+  hsclComponentName: string;
+  cssModule: Record<string, string>;
+};
+
+// Props that are generated by the component factory and consumed internally.
+// Think of them as pre-processed props that the developer doesn't need to know about.
+export type HsclInternalProps = {
+  hsclInternal?: {
+    hsclProcessedClasses?: string;
+    hsclCssVars?: CSSVariableMap;
+    hsclResolvedProps?: BaseComponentProps;
+    hsclProcessedStyles?: React.CSSProperties;
+  };
+};
+
+export type ComponentPropsType<T extends AnyReactComponent> =
+  React.ComponentProps<T>;
+
+// Alias which merges BaseComponentProps with component props while excluding internal props
+// This type preserves discriminated unions by distributing over union types
+export type InferPublicProps<
+  T extends
+    | keyof React.JSX.IntrinsicElements
+    | React.JSXElementConstructor<unknown>
+> = React.ComponentProps<T> extends infer U
+  ? U extends unknown
+    ? BaseComponentProps & Omit<U, keyof HsclInternalProps>
+    : never
+  : never;
+
+export type BaseAndInternalComponentProps = BaseComponentProps &
+  HsclInternalProps;
+
+export type CSSVariableMap = {
+  [variableName: string]: string | number;
+};
+
+// ==============================================================================
+// Chainable API
+// ==============================================================================
+
+export interface DimensionOption {
+  props: Partial<BaseComponentProps>;
+  choiceFieldOptionLabel?: string;
+}
+
+export interface Dimension {
+  options: Record<string, DimensionOption>;
+  choiceFieldLabel?: string;
+}
+
+export type DimensionConfiguration = Record<string, Dimension>;
+
+export type ChainableAPI = {
+  setDimension: (key: string) => DimensionAPI;
+};
+
+export interface DimensionAPI {
+  setOption: (key: string) => OptionAPI;
+  setDimension: (key: string) => DimensionAPI;
+  label: (label: string) => DimensionAPI;
+  createDimensionChoiceField: () => DimensionAPI;
+}
+
+export interface OptionAPI extends DimensionAPI {
+  setProps: (styleProps: Record<string, unknown>) => OptionAPI;
+  label: (label: string) => OptionAPI;
+  setOption: (key: string) => OptionAPI;
+}
+
+export type DimensionChoiceField = (
+  props: Omit<Partial<ChoiceFieldType>, 'choices'>
+) => React.ReactElement;
+
+export interface ComponentState {
+  dimensionConfiguration: DimensionConfiguration;
+  userConfiguration: DimensionConfiguration | null;
+  dimensionLabels: Record<string, string>;
+  optionLabels: Record<string, Record<string, string>>;
+  currentDimension: string | null;
+  dimensionChoiceFields: Record<string, DimensionChoiceField>;
+}
+
+export type ComponentInstanceFactory<T extends AnyReactComponent> =
+  ChainableAPI & {
+    (props: InferPublicProps<T>): React.ReactElement;
+  };

package/components/componentLibrary/utils/chainApi/choiceFieldGenerator.tsx

@@ -0,0 +1,64 @@
+import { ChoiceField, ChoiceFieldType } from '@hubspot/cms-components/fields';
+import {
+  generateChoicesWithLabels,
+  getDimensionLabel,
+} from './labelGenerator.js';
+import {
+  DimensionChoiceField,
+  DimensionConfiguration,
+} from '../../types/index.js';
+
+/**
+ * Creates prebuilt choice field components with enhanced labeling
+ */
+export const createDimensionChoiceField = (
+  configuration: DimensionConfiguration,
+  dimensionLabels: Record<string, string>,
+  optionLabels: Record<string, Record<string, string>>
+) => {
+  const dimensionChoiceFields: Record<string, DimensionChoiceField> = {};
+
+  for (const [dimensionKey, dimension] of Object.entries(configuration)) {
+    if (!dimension?.options) {
+      continue;
+    }
+
+    const dimensionLabel = getDimensionLabel(dimensionKey, dimensionLabels);
+    const choices = generateChoicesWithLabels(
+      dimensionKey,
+      dimension.options,
+      optionLabels
+    );
+
+    // Create prebuilt component for this dimension
+    dimensionChoiceFields[dimensionKey] = (props: Partial<ChoiceFieldType>) => {
+      const { name, label, ...restProps } = props;
+
+      return (
+        <ChoiceField
+          {...restProps}
+          name={name || dimensionKey}
+          label={label || dimensionLabel}
+          choices={choices}
+        />
+      );
+    };
+  }
+
+  return dimensionChoiceFields;
+};
+
+/**
+ * Creates a choice field generator factory with predefined configuration
+ * Returns functions that have access to the provided configuration and labels
+ */
+export const createChoiceFieldGenerator = (
+  configuration: DimensionConfiguration,
+  dimensionLabels: Record<string, string>,
+  optionLabels: Record<string, Record<string, string>>
+) => {
+  return {
+    createDimensionChoiceField: () =>
+      createDimensionChoiceField(configuration, dimensionLabels, optionLabels),
+  };
+};