npm - sovrium - Versions diffs - 0.0.2 - Mend

sovrium 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (527) hide show

package/src/presentation/rendering/render-homepage.tsx ADDED Viewed

@@ -0,0 +1,137 @@
+/**
+ * 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 { renderToString } from 'react-dom/server'
+import { findMatchingRoute } from '@/domain/utils/route-matcher'
+import { DefaultHomePage } from '@/presentation/ui/pages/DefaultHomePage'
+import { DynamicPage } from '@/presentation/ui/pages/DynamicPage'
+import type { App } from '@/domain/models/app'
+import type { BuiltInAnalytics } from '@/domain/models/app/analytics'
+/**
+ * Extract session timeout from analytics config, defaulting to 30 minutes
+ */
+function extractSessionTimeout(analytics: BuiltInAnalytics | undefined): number {
+  if (analytics === undefined || analytics === false || analytics === true) return 30
+  return analytics.sessionTimeout ?? 30
+}
+/**
+ * Check if built-in analytics tracking should be injected for a given page path
+ *
+ * Returns true when analytics is configured and enabled, and the page path
+ * is not in the excludedPaths list.
+ */
+function shouldInjectAnalytics(analytics: BuiltInAnalytics | undefined, pagePath: string): boolean {
+  if (analytics === undefined || analytics === false) return false
+  if (analytics === true) return true
+  const { excludedPaths } = analytics
+  if (!excludedPaths || excludedPaths.length === 0) return true
+  return !excludedPaths.some((pattern: string) => {
+    // Support simple glob patterns: * matches any segment, ** matches anything
+    const regex = new RegExp('^' + pattern.replace(/\*\*/g, '.*').replace(/\*/g, '[^/]*') + '$')
+    return regex.test(pagePath)
+  })
+}
+/**
+ * Renders a page by path to HTML string for server-side rendering
+ *
+ * Supports both static routes (exact match) and dynamic routes (with :param segments)
+ *
+ * @param app - Validated application data from AppSchema
+ * @param path - Page path to render (e.g., '/', '/about', '/blog/hello-world')
+ * @param detectedLanguage - Optional detected language from Accept-Language header or URL
+ * @returns Complete HTML document as string with DOCTYPE, or undefined if page not found
+ */
+export function renderPageByPath(
+  app: App,
+  path: string,
+  detectedLanguage?: string
+): string | undefined {
+  // If no pages configured, return undefined
+  if (!app.pages || app.pages.length === 0) {
+    return undefined
+  }
+  // Extract all page patterns and find matching route
+  const pagePatterns = app.pages.map((p) => p.path)
+  const match = findMatchingRoute(pagePatterns, path)
+  if (!match) {
+    return undefined
+  }
+  // Get the matched page
+  const page = app.pages[match.index]
+  if (!page) {
+    return undefined
+  }
+  const injectAnalytics = shouldInjectAnalytics(app.analytics, page.path)
+  const sessionTimeout = extractSessionTimeout(app.analytics)
+  const html = renderToString(
+    <DynamicPage
+      page={page}
+      components={app.components}
+      theme={app.theme}
+      languages={app.languages}
+      detectedLanguage={detectedLanguage}
+      routeParams={match.params}
+      builtInAnalyticsEnabled={injectAnalytics}
+      builtInAnalyticsSessionTimeout={sessionTimeout}
+    />
+  )
+  return `<!DOCTYPE html>\n${html}`
+}
+/**
+ * Renders homepage to HTML string for server-side rendering
+ *
+ * If the app has custom pages configured, renders the page with path '/'
+ * Otherwise, renders the default homepage
+ *
+ * @param app - Validated application data from AppSchema
+ * @param detectedLanguage - Optional detected language from Accept-Language header
+ * @returns Complete HTML document as string with DOCTYPE
+ */
+// @knip-ignore - Used via dynamic import in StartServer.ts
+export function renderHomePage(app: App, detectedLanguage?: string): string {
+  // Try to render custom homepage first
+  const customHomePage = renderPageByPath(app, '/', detectedLanguage)
+  if (customHomePage) {
+    return customHomePage
+  }
+  // Fallback to default homepage
+  // Check if analytics should be enabled for homepage (path '/')
+  const injectAnalytics = shouldInjectAnalytics(app.analytics, '/')
+  const defaultSessionTimeout = extractSessionTimeout(app.analytics)
+  const html = renderToString(
+    <DefaultHomePage
+      app={app}
+      builtInAnalyticsEnabled={injectAnalytics}
+      builtInAnalyticsSessionTimeout={defaultSessionTimeout}
+    />
+  )
+  return `<!DOCTYPE html>\n${html}`
+}
+/**
+ * Renders any page by path to HTML string for server-side rendering
+ *
+ * @param app - Validated application data from AppSchema
+ * @param path - Page path to render (e.g., '/', '/about')
+ * @param detectedLanguage - Optional detected language from Accept-Language header
+ * @returns Complete HTML document as string with DOCTYPE, or undefined if page not found
+ */
+// @knip-ignore - Used via dynamic import in server.ts
+export function renderPage(app: App, path: string, detectedLanguage?: string): string | undefined {
+  return renderPageByPath(app, path, detectedLanguage)
+}

package/src/presentation/scripts/script-renderers.ts ADDED Viewed

@@ -0,0 +1,112 @@
+/**
+ * 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 React, { type ReactElement } from 'react'
+/**
+ * Render a script tag with optional attributes
+ * Unified helper for rendering external scripts (analytics, external scripts, etc.)
+ */
+export function renderScriptTag({
+  src,
+  async: asyncProp,
+  defer,
+  module,
+  integrity,
+  crossOrigin,
+  dataTestId,
+  reactKey,
+  hidden,
+}: {
+  readonly src: string
+  readonly async?: boolean
+  readonly defer?: boolean
+  readonly module?: boolean
+  readonly integrity?: string
+  readonly crossOrigin?: 'anonymous' | 'use-credentials'
+  readonly dataTestId?: string
+  readonly reactKey: string | number
+  readonly hidden?: boolean
+}): Readonly<ReactElement> {
+  const props: Record<string, unknown> = {
+    key: reactKey,
+    src,
+    ...(asyncProp && { async: true }),
+    ...(defer && { defer: true }),
+    ...(module && { type: 'module' }),
+    ...(integrity && { integrity }),
+    ...(crossOrigin && { crossOrigin }),
+    ...(dataTestId && { 'data-testid': dataTestId }),
+    ...(hidden && { style: { display: 'none' } }),
+  }
+  return React.createElement('script', props)
+}
+/**
+ * Render an inline script tag with JavaScript code
+ * Wraps code in async IIFE if async property is true
+ *
+ * SECURITY: Safe use of dangerouslySetInnerHTML
+ * - Content: Inline JavaScript code from page configuration
+ * - Source: Validated InlineScripts schema (page.scripts.inlineScripts[].code)
+ * - Risk: Low - content is from server configuration, not user input
+ * - Validation: Schema validation ensures string type
+ * - Purpose: Render inline scripts for page-specific functionality
+ * - CSP: Inline script - consider using nonce for stricter CSP
+ * - Transformation: Optionally wraps in async IIFE for async execution
+ */
+export function renderInlineScriptTag({
+  code,
+  async: asyncProp,
+  reactKey,
+}: {
+  readonly code: string
+  readonly async?: boolean
+  readonly reactKey: string | number
+}): Readonly<ReactElement> {
+  const scriptContent = asyncProp ? `(async () => { ${code} })();` : code
+  return React.createElement('script', {
+    key: reactKey,
+    dangerouslySetInnerHTML: { __html: scriptContent },
+  })
+}
+/**
+ * Renders an inline script tag that exposes configuration data to window object
+ * Merges with existing window property if it already exists
+ *
+ * SECURITY: Safe use of dangerouslySetInnerHTML
+ * - Content: Build-time generated configuration data (JSON.stringify)
+ * - Source: Validated schema from app/page configuration
+ * - Risk: None - no user input, server-controlled data only
+ * - Purpose: Expose configuration for client-side JavaScript access
+ * - CSP: Compatible - inline script with deterministic content
+ * - Note: Only public configuration (no secrets)
+ *
+ * @param windowKey - Name of the window property (e.g., 'APP_CONFIG', 'APP_LANGUAGES')
+ * @param data - Configuration object to expose
+ * @param reactKey - Unique React key for the script element
+ * @returns React script element with inline configuration
+ */
+export function renderWindowConfig({
+  windowKey,
+  data,
+  reactKey,
+}: {
+  readonly windowKey: string
+  readonly data: unknown
+  readonly reactKey: string | number
+}): Readonly<ReactElement> {
+  return React.createElement('script', {
+    key: reactKey,
+    dangerouslySetInnerHTML: {
+      __html: `window.${windowKey} = Object.assign({}, window.${windowKey} || {}, ${JSON.stringify(data)});`,
+    },
+  })
+}

package/src/presentation/styling/animation-composer.ts ADDED Viewed

@@ -0,0 +1,117 @@
+/**
+ * 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'
+import type { Theme } from '@/domain/models/app/theme'
+/**
+ * Additional style properties to apply when composing animation
+ */
+interface AnimationStyleOptions {
+  readonly animationPlayState?: string
+  readonly animationFillMode?: string
+  readonly opacity?: number
+  readonly infinite?: boolean
+}
+/**
+ * Configuration for composing animations
+ */
+interface AnimationComposerConfig {
+  readonly baseStyle?: Record<string, unknown>
+  readonly componentType?: string
+  readonly animationName: string
+  readonly theme?: Theme
+  readonly defaultDuration: string
+  readonly defaultEasing: string
+  readonly options?: AnimationStyleOptions
+}
+/**
+ * Animation timing configuration
+ */
+type AnimationTiming = {
+  readonly duration: string
+  readonly easing: string
+}
+/**
+ * Extract animation timing from config
+ */
+function extractAnimationTiming(
+  animationConfig: unknown,
+  defaultDuration: string,
+  defaultEasing: string
+): AnimationTiming {
+  const duration =
+    typeof animationConfig === 'object' && animationConfig !== null && 'duration' in animationConfig
+      ? (animationConfig.duration as string)
+      : defaultDuration
+  const easing =
+    typeof animationConfig === 'object' && animationConfig !== null && 'easing' in animationConfig
+      ? (animationConfig.easing as string)
+      : defaultEasing
+  return { duration, easing }
+}
+/**
+ * Build animation style object
+ */
+function buildAnimationStyle(
+  baseStyle: Record<string, unknown> | undefined,
+  animationValue: string,
+  options?: AnimationStyleOptions
+): Record<string, unknown> {
+  return {
+    ...baseStyle,
+    animation: animationValue,
+    ...(options?.animationPlayState && { animationPlayState: options.animationPlayState }),
+    ...(options?.animationFillMode && { animationFillMode: options.animationFillMode }),
+    ...(options?.opacity !== undefined && { opacity: options.opacity }),
+  }
+}
+/**
+ * Compose animation style for a given component type
+ *
+ * Extracts animation configuration from theme and composes it with base style.
+ * Follows functional programming principles: pure function, immutable operations.
+ *
+ * @param config - Configuration object for animation composition
+ * @returns New style object with animation composed
+ *
+ * @example
+ * ```typescript
+ * const style = composeAnimation({
+ *   baseStyle,
+ *   componentType: 'toast',
+ *   animationName: 'fadeOut',
+ *   theme,
+ *   defaultDuration: '300ms',
+ *   defaultEasing: 'ease-out'
+ * })
+ * // Returns: { ...baseStyle, animation: 'fade-out 300ms ease-out' }
+ * ```
+ */
+export function composeAnimation(config: AnimationComposerConfig): Record<string, unknown> {
+  const animationConfig = config.theme?.animations?.[config.animationName]
+  if (!animationConfig) {
+    return config.baseStyle || {}
+  }
+  const { duration, easing } = extractAnimationTiming(
+    animationConfig,
+    config.defaultDuration,
+    config.defaultEasing
+  )
+  const infiniteSuffix = config.options?.infinite ? ' infinite' : ''
+  const animationValue = `${toKebabCase(config.animationName)} ${duration} ${easing}${infiniteSuffix}`
+  return buildAnimationStyle(config.baseStyle, animationValue, config.options)
+}

package/src/presentation/styling/index.ts ADDED Viewed

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+// Utility functions
+export { parseStyle, normalizeStyleAnimations } from './parse-style'
+export { isCssValue, isTailwindClass } from './style-utils'
+// Animation composition
+export { composeAnimation } from './animation-composer'

package/src/presentation/styling/parse-style.ts ADDED Viewed

@@ -0,0 +1,243 @@
+/**
+ * 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'
+/**
+ * Normalize animation names in CSS value to kebab-case
+ *
+ * Converts animation names (first token) from camelCase to kebab-case
+ * while preserving other CSS values (duration, easing, etc.)
+ *
+ * @param animationValue - CSS animation value (e.g., "fadeIn 1s ease-in-out")
+ * @returns Normalized animation value (e.g., "fade-in 1s ease-in-out")
+ *
+ * @example
+ * ```typescript
+ * normalizeAnimationValue('fadeIn 1s ease-in-out') // 'fade-in 1s ease-in-out'
+ * normalizeAnimationValue('slideInUp 0.5s') // 'slide-in-up 0.5s'
+ * ```
+ */
+function normalizeAnimationValue(animationValue: string): string {
+  const parts = animationValue.trim().split(/\s+/)
+  if (parts.length === 0) return animationValue
+  // First part is the animation name, convert to kebab-case
+  const animationName = parts[0]
+  if (!animationName) return animationValue
+  const normalizedName = toKebabCase(animationName)
+  // Rejoin with other parts (duration, easing, etc.)
+  return [normalizedName, ...parts.slice(1)].join(' ')
+}
+/**
+ * Common CSS properties in camelCase (used to identify CSS props in component props)
+ * This is not exhaustive but covers common use cases
+ */
+const CSS_PROPERTIES = new Set([
+  'alignContent',
+  'alignItems',
+  'alignSelf',
+  'animation',
+  'animationDelay',
+  'animationDirection',
+  'animationDuration',
+  'animationFillMode',
+  'animationIterationCount',
+  'animationName',
+  'animationPlayState',
+  'animationTimingFunction',
+  'background',
+  'backgroundColor',
+  'backgroundImage',
+  'backgroundPosition',
+  'backgroundRepeat',
+  'backgroundSize',
+  'border',
+  'borderBottom',
+  'borderColor',
+  'borderLeft',
+  'borderRadius',
+  'borderRight',
+  'borderStyle',
+  'borderTop',
+  'borderWidth',
+  'bottom',
+  'boxShadow',
+  'color',
+  'cursor',
+  'display',
+  'flex',
+  'flexBasis',
+  'flexDirection',
+  'flexGrow',
+  'flexShrink',
+  'flexWrap',
+  'font',
+  'fontFamily',
+  'fontSize',
+  'fontStyle',
+  'fontWeight',
+  'gap',
+  'grid',
+  'gridArea',
+  'gridAutoColumns',
+  'gridAutoFlow',
+  'gridAutoRows',
+  'gridColumn',
+  'gridColumnEnd',
+  'gridColumnGap',
+  'gridColumnStart',
+  'gridGap',
+  'gridRow',
+  'gridRowEnd',
+  'gridRowGap',
+  'gridRowStart',
+  'gridTemplate',
+  'gridTemplateAreas',
+  'gridTemplateColumns',
+  'gridTemplateRows',
+  'height',
+  'justifyContent',
+  'justifyItems',
+  'justifySelf',
+  'left',
+  'letterSpacing',
+  'lineHeight',
+  'listStyle',
+  'listStyleImage',
+  'listStylePosition',
+  'listStyleType',
+  'margin',
+  'marginBottom',
+  'marginLeft',
+  'marginRight',
+  'marginTop',
+  'maxHeight',
+  'maxWidth',
+  'minHeight',
+  'minWidth',
+  'objectFit',
+  'objectPosition',
+  'opacity',
+  'order',
+  'outline',
+  'outlineColor',
+  'outlineOffset',
+  'outlineStyle',
+  'outlineWidth',
+  'overflow',
+  'overflowX',
+  'overflowY',
+  'padding',
+  'paddingBottom',
+  'paddingLeft',
+  'paddingRight',
+  'paddingTop',
+  'position',
+  'right',
+  'textAlign',
+  'textDecoration',
+  'textOverflow',
+  'textShadow',
+  'textTransform',
+  'top',
+  'transform',
+  'transformOrigin',
+  'transition',
+  'transitionDelay',
+  'transitionDuration',
+  'transitionProperty',
+  'transitionTimingFunction',
+  'verticalAlign',
+  'visibility',
+  'whiteSpace',
+  'width',
+  'wordBreak',
+  'wordSpacing',
+  'wordWrap',
+  'zIndex',
+])
+/**
+ * Check if a property name is a known CSS property
+ *
+ * @param propName - Property name to check
+ * @returns True if the property is a known CSS property
+ */
+export function isCssProperty(propName: string): boolean {
+  return CSS_PROPERTIES.has(propName)
+}
+/**
+ * Parse a CSS string into a React style object
+ *
+ * Converts kebab-case CSS properties to camelCase React style properties.
+ * Handles semicolon-separated CSS declarations.
+ * Normalizes animation names to kebab-case for consistency.
+ *
+ * @param styleString - CSS string (e.g., "background-color: #007bff; padding: 1rem;")
+ * @returns React style object (e.g., { backgroundColor: '#007bff', padding: '1rem' })
+ *
+ * @example
+ * ```typescript
+ * const style = parseStyle('background-color: #007bff; padding: 1rem;')
+ * // { backgroundColor: '#007bff', padding: '1rem' }
+ * ```
+ */
+export function parseStyle(styleString: string): Record<string, string> {
+  // Split by semicolon and process each declaration
+  const declarations = styleString.split(';').filter((d) => d.trim())
+  // Use reduce for immutable accumulation instead of for-of loop with mutations
+  return declarations.reduce<Record<string, string>>((acc, declaration) => {
+    const [property, value] = declaration.split(':').map((s) => s.trim())
+    if (property && value) {
+      // Convert kebab-case to camelCase (e.g., background-color → backgroundColor)
+      const camelCaseProperty = property.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())
+      // Normalize animation names to kebab-case
+      const normalizedValue =
+        camelCaseProperty === 'animation' ? normalizeAnimationValue(value) : value
+      return { ...acc, [camelCaseProperty]: normalizedValue }
+    }
+    return acc
+  }, {})
+}
+/**
+ * Normalize animation names in style object to kebab-case
+ *
+ * Converts animation property values from camelCase to kebab-case.
+ * Useful for style objects (not CSS strings).
+ *
+ * @param style - React style object
+ * @returns Style object with normalized animation names
+ *
+ * @example
+ * ```typescript
+ * const style = { animation: 'fadeIn 1s ease-in-out' }
+ * normalizeStyleAnimations(style) // { animation: 'fade-in 1s ease-in-out' }
+ * ```
+ */
+export function normalizeStyleAnimations(
+  style: Record<string, unknown> | undefined
+): Record<string, unknown> | undefined {
+  if (!style) return style
+  const animationValue = style.animation
+  if (typeof animationValue === 'string') {
+    return {
+      ...style,
+      animation: normalizeAnimationValue(animationValue),
+    }
+  }
+  return style
+}

package/src/presentation/styling/style-utils.ts ADDED Viewed

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+/**
+ * Checks if a value is a CSS value with units (rem, px, em, %, vh, vw)
+ * CSS values must contain units and not include spaces (to distinguish from Tailwind classes)
+ *
+ * @param value - String value to check
+ * @returns true if value is a raw CSS value, false if it's a Tailwind class
+ *
+ * @example
+ * isCssValue('4rem') // true
+ * isCssValue('80rem') // true
+ * isCssValue('py-16') // false
+ * isCssValue('py-16 sm:py-20') // false
+ */
+export const isCssValue = (value: string): boolean => {
+  return /\d+(rem|px|em|%|vh|vw)/.test(value) && !value.includes(' ')
+}
+/**
+ * Checks if a container spacing value is a Tailwind class (not a raw CSS value)
+ * Tailwind classes include utility classes like "max-w-7xl", "mx-auto", "px-4"
+ * CSS values like "80rem" or "1280px" should return false
+ *
+ * @param value - Container spacing value to check
+ * @returns true if value contains Tailwind classes, false if it's a raw CSS value
+ *
+ * @example
+ * isTailwindClass('max-w-7xl mx-auto px-4') // true
+ * isTailwindClass('max-w-7xl') // true
+ * isTailwindClass('80rem') // false
+ * isTailwindClass('1280px') // false
+ */
+export const isTailwindClass = (value: string): boolean => {
+  // If it has spaces, it's multiple classes (Tailwind)
+  if (value.includes(' ')) {
+    return true
+  }
+  // If it matches Tailwind patterns (max-w-*, mx-*, px-*, etc.), it's a class
+  if (/^(max-w-|mx-|px-|py-|p-|m-|w-|h-)/.test(value)) {
+    return true
+  }
+  // Otherwise, assume it's a CSS value
+  return false
+}