sovrium 0.0.2

package/src/presentation/ui/sections/props/element-props.ts

@@ -0,0 +1,179 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { CONTAINER_TYPES } from '../component-renderer.types'
+import { buildFlexClasses, buildGridClasses } from '../styling/class-builders'
+import type { Component } from '@/domain/models/app/page/sections'
+
+/**
+ * Build data-testid based on component name and instance index
+ */
+export function buildTestId(
+  componentName?: string,
+  componentInstanceIndex?: number,
+  type?: string,
+  substitutedProps?: Record<string, unknown>
+): string | undefined {
+  if (componentName) {
+    return componentInstanceIndex !== undefined
+      ? `component-${componentName}-${componentInstanceIndex}`
+      : `component-${componentName}`
+  }
+
+  const dataTestId = substitutedProps?.['data-testid']
+  if (typeof dataTestId === 'string') {
+    return dataTestId
+  }
+
+  // Auto-generate testid for common component types to support testing
+  if (type === 'container') return 'container'
+  if (type === 'flex') return 'flex'
+  if (type === 'text') return 'text'
+
+  return undefined
+}
+
+/**
+ * Component types that have corresponding CSS classes
+ * These types will automatically get their type name added as a CSS class
+ */
+const COMPONENT_TYPES_WITH_CSS_CLASSES = new Set(['card', 'badge'])
+
+/**
+ * Build final className based on component type
+ */
+export function buildClassName(
+  type: string,
+  substitutedProps?: Record<string, unknown>
+): string | undefined {
+  if (type === 'flex') {
+    return [buildFlexClasses(substitutedProps), substitutedProps?.className]
+      .filter(Boolean)
+      .join(' ')
+  }
+
+  if (type === 'grid') {
+    return [buildGridClasses(substitutedProps), substitutedProps?.className]
+      .filter(Boolean)
+      .join(' ')
+  }
+
+  // Auto-apply component type as CSS class for types with CSS definitions
+  if (COMPONENT_TYPES_WITH_CSS_CLASSES.has(type)) {
+    return [type, substitutedProps?.className].filter(Boolean).join(' ')
+  }
+
+  return substitutedProps?.className as string | undefined
+}
+
+/**
+ * Build component data attributes
+ */
+function buildComponentDataAttrs(componentName?: string, type?: string) {
+  if (!componentName) {
+    return {}
+  }
+  return {
+    'data-component': componentName,
+    'data-type': type,
+  }
+}
+
+/**
+ * Build translation data attributes
+ */
+function buildTranslationDataAttrs(
+  firstTranslationKey?: string,
+  translationData?: Record<string, unknown>
+) {
+  if (!firstTranslationKey || !translationData) {
+    return {}
+  }
+  return {
+    'data-translation-key': firstTranslationKey,
+    'data-translations': JSON.stringify(translationData),
+  }
+}
+
+/**
+ * Build empty content style
+ */
+function buildEmptyStyle(
+  componentName?: string,
+  type?: string,
+  hasContent?: boolean,
+  styleWithShadow?: Record<string, unknown>
+) {
+  if (componentName && !hasContent) {
+    return {
+      ...styleWithShadow,
+      minHeight: '1px',
+      minWidth: '1px',
+      display: 'inline-block',
+    }
+  }
+  if (!componentName && type === 'grid' && !hasContent) {
+    return {
+      ...styleWithShadow,
+      minHeight: '100px',
+      minWidth: '100px',
+    }
+  }
+  return styleWithShadow
+}
+
+/**
+ * Build element props including data attributes, ARIA, and styling
+ */
+export function buildElementProps({
+  component,
+  substitutedProps,
+  finalClassName,
+  styleWithShadow,
+  testId,
+  componentName,
+  firstTranslationKey,
+  translationData,
+  hasScrollAnimation,
+  hasContent,
+  children,
+}: {
+  readonly component: Component
+  readonly substitutedProps?: Record<string, unknown>
+  readonly finalClassName?: string
+  readonly styleWithShadow?: Record<string, unknown>
+  readonly testId?: string
+  readonly componentName?: string
+  readonly firstTranslationKey?: string
+  readonly translationData?: Record<string, unknown>
+  readonly hasScrollAnimation?: boolean
+  readonly hasContent?: boolean
+  readonly children?: readonly (Component | string)[]
+}): Record<string, unknown> {
+  const { type } = component
+  const hasChildren = Boolean(children?.length)
+  const finalStyle = buildEmptyStyle(componentName, type, hasContent, styleWithShadow)
+
+  return {
+    ...substitutedProps,
+    className: finalClassName,
+    ...(finalStyle && { style: finalStyle }),
+    ...(testId && { 'data-testid': testId }),
+    ...buildComponentDataAttrs(componentName, type),
+    ...(componentName && hasChildren && CONTAINER_TYPES.includes(type) && { role: 'group' }),
+    ...buildTranslationDataAttrs(firstTranslationKey, translationData),
+    ...(hasScrollAnimation && { 'data-scroll-animation': 'scale-up' }),
+  }
+}
+
+/**
+ * Convert custom props to data-* attributes for badge components
+ * Standard HTML attributes (className, style, id, etc.) pass through unchanged
+ *
+ * Re-exported from prop-conversion module for backward compatibility
+ */
+export { convertBadgeProps } from './prop-conversion'

package/src/presentation/ui/sections/props/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+// Barrel export for props building utilities
+// Files will be added during migration

package/src/presentation/ui/sections/props/prop-conversion.ts

@@ -0,0 +1,171 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { toKebabCase } from '@/presentation/utils/string-utils'
+
+/**
+ * HTML/React props that should not be converted to data attributes
+ * This includes standard HTML attributes, React-specific props, ARIA attributes,
+ * event handlers, and existing data-* attributes
+ */
+export const RESERVED_PROPS = new Set([
+  // Standard HTML/React props
+  'className',
+  'style',
+  'children',
+  'ref',
+  'key',
+  'id',
+  'role',
+  'title',
+  'alt',
+  'src',
+  'href',
+  'type',
+  'value',
+  'placeholder',
+  'disabled',
+  'checked',
+  'selected',
+  'multiple',
+  'autoFocus',
+  'autoComplete',
+  'readOnly',
+  'required',
+  'maxLength',
+  'minLength',
+  'pattern',
+  'name',
+  'tabIndex',
+  // ARIA attributes
+  'aria-label',
+  'aria-labelledby',
+  'aria-describedby',
+  // Event handlers
+  'onClick',
+  'onChange',
+  'onSubmit',
+  'onFocus',
+  'onBlur',
+  'onKeyDown',
+  'onKeyUp',
+  'onKeyPress',
+  'onMouseEnter',
+  'onMouseLeave',
+  // Application-specific props
+  'level', // For text elements (h1-h6, p, label)
+  'animation',
+  'data-testid',
+  'data-component',
+  'data-type',
+  'data-translation-key',
+  'data-translations',
+  'data-scroll-animation',
+  'data-scroll-threshold',
+  'data-scroll-delay',
+  'data-scroll-duration',
+  'data-scroll-once',
+  'data-i18n-content',
+])
+
+/**
+ * Checks if a prop should be skipped during conversion
+ */
+function shouldSkipProp(key: string, _value: unknown): boolean {
+  return RESERVED_PROPS.has(key) || key.startsWith('data-') || key.startsWith('aria-')
+}
+
+/**
+ * Converts a value to a data attribute string
+ */
+function valueToDataAttributeString(value: unknown): string | undefined {
+  if (typeof value === 'string') {
+    return value
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return value.toString()
+  }
+  if (Array.isArray(value)) {
+    return JSON.stringify(value)
+  }
+  if (typeof value === 'object' && value !== null) {
+    return JSON.stringify(value)
+  }
+  return undefined
+}
+
+/**
+ * Converts a single prop value to a data attribute value
+ *
+ * @param key - Prop key
+ * @param value - Prop value
+ * @returns Data attribute entry or undefined if should be skipped
+ */
+function convertPropToDataAttribute(
+  key: string,
+  value: unknown
+): readonly [string, string] | undefined {
+  // Skip reserved props, data-*, aria-*, strings, and style objects
+  if (shouldSkipProp(key, value) || key === 'style') return undefined
+
+  const stringValue = valueToDataAttributeString(value)
+  return stringValue ? ([`data-${toKebabCase(key)}`, stringValue] as const) : undefined
+}
+
+/**
+ * Converts custom props to data attributes
+ * Handles numeric, boolean, array, and object values
+ *
+ * This is the comprehensive version that handles all prop types.
+ * Use this for components that need full prop conversion (e.g., dynamic components).
+ *
+ * @param props - Props object to convert
+ * @returns Object with data attributes for custom props
+ */
+export function convertCustomPropsToDataAttributes(
+  props: Record<string, unknown> | undefined
+): Record<string, string> {
+  if (!props) return {}
+
+  return Object.entries(props).reduce<Record<string, string>>((acc, [key, value]) => {
+    const dataAttr = convertPropToDataAttribute(key, value)
+    return dataAttr ? { ...acc, [dataAttr[0]]: dataAttr[1] } : acc
+  }, {})
+}
+
+/**
+ * Convert custom props to data-* attributes (simplified version for badges)
+ * Standard HTML attributes (className, style, id, etc.) pass through unchanged
+ * String values are converted to data attributes (unlike the comprehensive version)
+ *
+ * This is used for badge components where all custom props should become data attributes.
+ *
+ * @param elementProps - Element props to convert
+ * @returns Props with custom values converted to data attributes
+ */
+export function convertBadgeProps(elementProps: Record<string, unknown>): Record<string, unknown> {
+  const standardHtmlAttrs = new Set([
+    'className',
+    'style',
+    'id',
+    'role',
+    'data-testid',
+    'data-component',
+    'data-type',
+    'data-translation-key',
+    'data-translations',
+  ])
+
+  return Object.entries(elementProps).reduce<Record<string, unknown>>((acc, [key, value]) => {
+    // Keep standard HTML attrs, data-*, and aria-* unchanged
+    if (standardHtmlAttrs.has(key) || key.startsWith('data-') || key.startsWith('aria-')) {
+      return { ...acc, [key]: value }
+    }
+    // Convert custom props to data-* attributes (including strings)
+    return { ...acc, [`data-${toKebabCase(key)}`]: value }
+  }, {})
+}

package/src/presentation/ui/sections/props/props-builder-config.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import type { Interactions } from '@/domain/models/app/page/common/interactions/interactions'
+import type { Component } from '@/domain/models/app/page/sections'
+import type { Theme } from '@/domain/models/app/theme'
+
+/**
+ * Configuration for building test IDs
+ * Replaces 5 parameters with a single config object
+ */
+export interface TestIdConfig {
+  readonly type: Component['type']
+  readonly componentName?: string
+  readonly componentInstanceIndex?: number
+  readonly substitutedProps?: Record<string, unknown>
+  readonly childIndex?: number
+}
+
+/**
+ * Configuration for building element props
+ * Replaces 12 parameters with a single config object
+ */
+export interface ElementPropsConfig {
+  readonly type: Component['type']
+  readonly substitutedProps: Record<string, unknown> | undefined
+  readonly finalClassName: string | undefined
+  readonly styleWithShadow: Record<string, unknown> | undefined
+  readonly componentName: string | undefined
+  readonly componentInstanceIndex: number | undefined
+  readonly firstTranslationKey: string | undefined
+  readonly translationData: Record<string, string> | undefined
+  readonly hasContent: boolean
+  readonly hasChildren: boolean
+  readonly theme: Theme | undefined
+  readonly childIndex?: number
+  readonly interactions?: Interactions
+}

package/src/presentation/ui/sections/props/props-builder.ts

@@ -0,0 +1,296 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { calculateTotalDelay } from '../utils/time-parser'
+import { convertCustomPropsToDataAttributes } from './prop-conversion'
+import type { ElementPropsConfig, TestIdConfig } from './props-builder-config'
+
+/**
+ * Component types that should receive role="group" when used as component references with children
+ */
+const CONTAINER_TYPES = ['div', 'container', 'flex', 'grid', 'card', 'badge'] as const
+
+/**
+ * Builds test ID for component references
+ */
+function buildComponentTestId(
+  componentName: string,
+  componentInstanceIndex: number | undefined
+): string {
+  return componentInstanceIndex !== undefined
+    ? `component-${componentName}-${componentInstanceIndex}`
+    : `component-${componentName}`
+}
+
+/**
+ * Auto-generates test ID for common component types
+ */
+function buildDefaultTestId(type: string): string | undefined {
+  const typeMap: Record<string, string> = {
+    container: 'container',
+    flex: 'flex',
+    'hero-section': 'hero-section',
+    hero: 'hero',
+    text: 'text',
+    icon: 'icon',
+  }
+  return typeMap[type]
+}
+
+/**
+ * Build test ID for component using config object
+ */
+
+function buildTestId(config: TestIdConfig): string | undefined {
+  const { type, componentName, componentInstanceIndex, substitutedProps, childIndex } = config
+
+  if (componentName) {
+    return buildComponentTestId(componentName, componentInstanceIndex)
+  }
+
+  if (substitutedProps?.['data-testid']) {
+    return substitutedProps['data-testid'] as string
+  }
+
+  if (childIndex !== undefined) {
+    return `child-${childIndex}`
+  }
+
+  return buildDefaultTestId(type)
+}
+
+/**
+ * Build element props with all attributes using config object
+ * Complexity reduced by extracting helper functions
+ */
+export function buildElementProps(config: ElementPropsConfig): Record<string, unknown> {
+  return buildElementPropsFromConfig(config)
+}
+
+/**
+ * Build element props from config object
+ */
+function buildElementPropsFromConfig(config: ElementPropsConfig): Record<string, unknown> {
+  const hasScrollAnimation = config.type === 'card' && Boolean(config.theme?.animations?.scaleUp)
+  const testId = buildTestId({
+    type: config.type,
+    componentName: config.componentName,
+    componentInstanceIndex: config.componentInstanceIndex,
+    substitutedProps: config.substitutedProps,
+    childIndex: config.childIndex,
+  })
+
+  // Build all props
+  const coreProps = buildCoreProps(config, testId)
+  const componentDataProps = buildComponentDataProps(config)
+  const translationProps = buildTranslationProps(config)
+  const animationProps = buildAnimationProps(hasScrollAnimation)
+  const entranceProps = buildEntranceInteractionProps(config)
+  const scrollProps = buildScrollInteractionProps(config)
+  const emptyStyleProps = buildEmptyElementStyles(config)
+
+  // Merge all style objects to prevent overwrites
+  const mergedStyle = {
+    ...(coreProps.style as Record<string, unknown> | undefined),
+    ...(entranceProps.style as Record<string, unknown> | undefined),
+    ...(scrollProps.style as Record<string, unknown> | undefined),
+    ...(emptyStyleProps.style as Record<string, unknown> | undefined),
+  }
+
+  // Remove style from individual prop objects
+  const { style: _coreStyle, ...corePropsWithoutStyle } = coreProps
+  const { style: _entranceStyle, ...entrancePropsWithoutStyle } = entranceProps
+  const { style: _scrollStyle, ...scrollPropsWithoutStyle } = scrollProps
+  const { style: _emptyStyle, ...emptyStylePropsWithoutStyle } = emptyStyleProps
+
+  // Remove animation and style props from substitutedProps (already applied to style object)
+  const {
+    animation: _animation,
+    style: _style,
+    ...substitutedPropsWithoutAnimation
+  } = config.substitutedProps || {}
+
+  // Convert custom props to data attributes
+  const customDataAttributes = convertCustomPropsToDataAttributes(substitutedPropsWithoutAnimation)
+
+  return {
+    ...substitutedPropsWithoutAnimation,
+    ...corePropsWithoutStyle,
+    ...componentDataProps,
+    ...translationProps,
+    ...animationProps,
+    ...entrancePropsWithoutStyle,
+    ...scrollPropsWithoutStyle,
+    ...emptyStylePropsWithoutStyle,
+    ...customDataAttributes,
+    ...(Object.keys(mergedStyle).length > 0 && { style: mergedStyle }),
+  }
+}
+
+/**
+ * Build core props (className, style, data-testid)
+ * Handles animation prop by extracting it from substitutedProps and merging into style
+ *
+ * Note: data-component-type removed for clean production HTML
+ * This debug attribute was useful during development but adds unnecessary
+ * markup to static sites and production builds
+ */
+function buildCoreProps(
+  config: ElementPropsConfig,
+  testId: string | undefined
+): Record<string, unknown> {
+  // Extract animation prop if present (after theme token substitution)
+  const animationProp = config.substitutedProps?.animation
+  const hasAnimationProp = typeof animationProp === 'string'
+
+  // Merge animation into style object if present
+  const styleWithAnimation = hasAnimationProp
+    ? { ...config.styleWithShadow, animation: animationProp }
+    : config.styleWithShadow
+
+  return {
+    className: config.finalClassName,
+    ...(styleWithAnimation && { style: styleWithAnimation }),
+    ...(testId && { 'data-testid': testId }),
+  }
+}
+
+/**
+ * Build component-related data props (data-component, data-type, role)
+ */
+function buildComponentDataProps(config: ElementPropsConfig): Record<string, unknown> {
+  if (!config.componentName) return {}
+
+  return {
+    'data-component': config.componentName,
+    'data-type': config.type,
+    ...(config.hasChildren &&
+      CONTAINER_TYPES.includes(config.type) && {
+        role: 'group',
+      }),
+  }
+}
+
+/**
+ * Build translation props (data-translation-key, data-translations)
+ */
+function buildTranslationProps(config: ElementPropsConfig): Record<string, unknown> {
+  if (!config.firstTranslationKey || !config.translationData) return {}
+
+  return {
+    'data-translation-key': config.firstTranslationKey,
+    'data-translations': JSON.stringify(config.translationData),
+  }
+}
+
+/**
+ * Build animation props (data-scroll-animation)
+ */
+function buildAnimationProps(hasScrollAnimation: boolean): Record<string, unknown> {
+  if (!hasScrollAnimation) return {}
+
+  return {
+    'data-scroll-animation': 'scale-up',
+  }
+}
+
+/**
+ * Build entrance interaction props (style for animations)
+ */
+function buildEntranceInteractionProps(config: ElementPropsConfig): Record<string, unknown> {
+  if (!config.interactions?.entrance) return {}
+
+  const { delay, duration, stagger } = config.interactions.entrance
+
+  // Calculate total delay including stagger
+  const totalDelay = calculateTotalDelay(delay, stagger, config.childIndex)
+
+  // Build animation styles immutably
+  const delayStyle = totalDelay ? { animationDelay: totalDelay } : {}
+  const durationStyle = duration ? { animationDuration: duration } : {}
+  const animationStyles = { ...delayStyle, ...durationStyle }
+
+  // Combine all props immutably
+  const hasAnimationStyles = Object.keys(animationStyles).length > 0
+  const styleProps = hasAnimationStyles
+    ? { style: { ...config.styleWithShadow, ...animationStyles } }
+    : {}
+
+  return styleProps
+}
+
+/**
+ * Build scroll interaction props (data-scroll-*, style for animations)
+ */
+function buildScrollInteractionProps(config: ElementPropsConfig): Record<string, unknown> {
+  if (!config.interactions?.scroll) return {}
+
+  const { animation, threshold, delay, duration, once } = config.interactions.scroll
+
+  // Build base data attributes immutably
+  const baseProps: Record<string, unknown> = {
+    'data-scroll-animation': animation,
+  }
+
+  const thresholdProps =
+    threshold !== undefined ? { 'data-scroll-threshold': threshold.toString() } : {}
+  const delayProps = delay ? { 'data-scroll-delay': delay } : {}
+  const durationProps = duration ? { 'data-scroll-duration': duration } : {}
+  const onceProps = once === true ? { 'data-scroll-once': once.toString() } : {}
+
+  // Build animation styles immutably
+  const delayStyle = delay ? { animationDelay: delay } : {}
+  const durationStyle = duration ? { animationDuration: duration } : {}
+  const animationStyles = { ...delayStyle, ...durationStyle }
+
+  // Combine all props immutably
+  const hasAnimationStyles = Object.keys(animationStyles).length > 0
+  const styleProps = hasAnimationStyles
+    ? { style: { ...config.styleWithShadow, ...animationStyles } }
+    : {}
+
+  return {
+    ...baseProps,
+    ...thresholdProps,
+    ...delayProps,
+    ...durationProps,
+    ...onceProps,
+    ...styleProps,
+  }
+}
+
+/**
+ * Build styles for empty elements (components and grids without content)
+ */
+function buildEmptyElementStyles(config: ElementPropsConfig): Record<string, unknown> {
+  if (config.hasContent) return {}
+
+  // Component reference or child without content
+  if (config.componentName || config.childIndex !== undefined) {
+    return {
+      style: {
+        ...config.styleWithShadow,
+        minHeight: '1px',
+        minWidth: '1px',
+        display: 'inline-block',
+      },
+    }
+  }
+
+  // Grid without content and not a component reference
+  if (!config.componentName && config.type === 'grid') {
+    return {
+      style: {
+        ...config.styleWithShadow,
+        minHeight: '100px',
+        minWidth: '100px',
+      },
+    }
+  }
+
+  return {}
+}