meno-core 1.0.0

package/lib/shared/types/errors.test.ts

@@ -0,0 +1,103 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  createValidationError,
+  createTypeSafetyError,
+  type ValidationError,
+  type TypeSafetyError,
+} from './errors';
+
+describe('error types', () => {
+  describe('createValidationError', () => {
+    test('creates error with message only', () => {
+      const error = createValidationError('Invalid input');
+      expect(error.message).toBe('Invalid input');
+      expect(error.path).toBeUndefined();
+      expect(error.receivedValue).toBeUndefined();
+      expect(error.expectedType).toBeUndefined();
+    });
+
+    test('creates error with all options', () => {
+      const error = createValidationError('Type mismatch', {
+        path: 'user.name',
+        receivedValue: 123,
+        expectedType: 'string',
+      });
+      expect(error.message).toBe('Type mismatch');
+      expect(error.path).toBe('user.name');
+      expect(error.receivedValue).toBe(123);
+      expect(error.expectedType).toBe('string');
+    });
+
+    test('creates error with partial options', () => {
+      const error = createValidationError('Missing field', {
+        path: 'user.email',
+      });
+      expect(error.message).toBe('Missing field');
+      expect(error.path).toBe('user.email');
+      expect(error.receivedValue).toBeUndefined();
+    });
+  });
+
+  describe('createTypeSafetyError', () => {
+    test('creates error with message only', () => {
+      const error = createTypeSafetyError('Type error');
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('Type error');
+      expect(error.path).toBeUndefined();
+    });
+
+    test('creates error with all options', () => {
+      const error = createTypeSafetyError('Invalid type', {
+        path: 'config.value',
+        receivedValue: null,
+        expectedType: 'number',
+      });
+      expect(error.message).toBe('Invalid type');
+      expect(error.path).toBe('config.value');
+      expect(error.receivedValue).toBeNull();
+      expect(error.expectedType).toBe('number');
+    });
+
+    test('error has name property', () => {
+      const error = createTypeSafetyError('Test error');
+      expect(error.name).toBe('Error');
+    });
+
+    test('error has stack trace', () => {
+      const error = createTypeSafetyError('Test error');
+      expect(error.stack).toBeDefined();
+    });
+  });
+
+  describe('ValidationError interface', () => {
+    test('supports all properties', () => {
+      const error: ValidationError = {
+        message: 'Test',
+        path: 'test.path',
+        receivedValue: 'value',
+        expectedType: 'type',
+      };
+      expect(error.message).toBe('Test');
+    });
+
+    test('allows optional properties', () => {
+      const error: ValidationError = {
+        message: 'Test only',
+      };
+      expect(error.message).toBe('Test only');
+    });
+  });
+
+  describe('TypeSafetyError interface', () => {
+    test('is an Error instance', () => {
+      const error = createTypeSafetyError('Test');
+      expect(error).toBeInstanceOf(Error);
+    });
+
+    test('has readonly properties', () => {
+      const error = createTypeSafetyError('Test', { path: 'test' });
+      expect(error.path).toBe('test');
+      // TypeScript enforces readonly at compile time
+    });
+  });
+});

package/lib/shared/types/errors.ts

@@ -0,0 +1,69 @@
+/**
+ * Error Types
+ * Structured error types for validation and type safety
+ */
+
+/**
+ * Validation error with context
+ */
+export interface ValidationError {
+  path?: string;
+  message: string;
+  receivedValue?: unknown;
+  expectedType?: string;
+}
+
+/**
+ * Type safety error
+ * Errors from type mismatches or invalid data structures
+ */
+export interface TypeSafetyError extends Error {
+  readonly path?: string;
+  readonly receivedValue?: unknown;
+  readonly expectedType?: string;
+}
+
+/**
+ * Result type for operations that can fail
+ * Replaces null returns with explicit success/failure
+ */
+export type Result<T> =
+  | { success: true; data: T }
+  | { success: false; error: ValidationError };
+
+/**
+ * Create a validation error
+ */
+export function createValidationError(
+  message: string,
+  options?: {
+    path?: string;
+    receivedValue?: unknown;
+    expectedType?: string;
+  }
+): ValidationError {
+  return {
+    message,
+    ...options,
+  };
+}
+
+/**
+ * Create a type safety error
+ */
+export function createTypeSafetyError(
+  message: string,
+  options?: {
+    path?: string;
+    receivedValue?: unknown;
+    expectedType?: string;
+  }
+): TypeSafetyError {
+  const error = new Error(message) as TypeSafetyError;
+  error.path = options?.path;
+  error.receivedValue = options?.receivedValue;
+  error.expectedType = options?.expectedType;
+  return error;
+}
+
+

package/lib/shared/types/index.ts

@@ -0,0 +1,96 @@
+/**
+ * Shared TypeScript types and interfaces
+ * Used by both client and server code
+ * 
+ * This is the main entry point for all shared types.
+ * Types are organized into separate files for better maintainability.
+ */
+
+// Export all node types
+export type {
+  ComponentNode,
+  HtmlNode,
+  ComponentInstanceNode,
+  SlotMarker,
+  EmbedNode,
+  ObjectLinkNode,
+  LocaleListNode,
+} from './nodes';
+
+// Export all component types
+export type {
+  ComponentDefinition,
+  StructuredComponentDefinition,
+  PropDefinition,
+  JSONPage,
+  PageData,
+  PageDataWithComponent,
+  I18nValue,
+  I18nConfig,
+  LocaleConfig,
+} from './components';
+
+// Export all style types
+export type {
+  StyleValue,
+  StyleObject,
+  ResponsiveStyleObject,
+  StyleMapping,
+} from './styles';
+
+// Export all API types
+export type {
+  HMRMessage,
+  PageListResponse,
+  RouteHandler,
+  PageMetaData,
+  PageCmsConfig,
+} from './api';
+
+// Export all CMS types
+export type {
+  CMSFieldType,
+  CMSFieldDefinition,
+  CMSSchema,
+  CMSItem,
+  CMSCollection,
+  CMSRouteMatch,
+  CMSFilterOperator,
+  CMSFilterCondition,
+  CMSSortConfig,
+  CMSListQuery,
+  CMSListProps,
+} from './cms';
+
+// Export rendering types
+export type {
+  RenderingContext,
+  StyleResolutionOptions,
+  ComponentRenderOptions,
+  StyleMergeOptions,
+  TemplateContext,
+} from './rendering';
+
+// Export error types
+export type {
+  ValidationError,
+  TypeSafetyError,
+  Result,
+} from './errors';
+
+export {
+  createValidationError,
+  createTypeSafetyError,
+} from './errors';
+
+// Export color and theme types
+export type {
+  ColorVariables,
+  ColorVariableEntry,
+  Theme,
+  ThemeConfig,
+  ThemeEntry,
+} from './colors';
+
+// Note: Path types are exported from ../paths/index.ts, not from here
+

package/lib/shared/types/nodes.ts

@@ -0,0 +1,20 @@
+/**
+ * Component Node Types
+ * Core types for representing component tree nodes
+ *
+ * Types are now inferred from Zod schemas in the node type definition files.
+ * This file re-exports them for backward compatibility.
+ */
+
+// Re-export all node types from the registry
+// These types are inferred from Zod schemas (single source of truth)
+export type {
+  HtmlNode,
+  ComponentInstanceNode,
+  SlotMarker,
+  EmbedNode,
+  ObjectLinkNode,
+  LocaleListNode,
+  TextNode,
+  ComponentNode,
+} from '../registry/nodeTypes';

package/lib/shared/types/rendering.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared Rendering Types
+ * Types used by both SSR and client rendering for consistency
+ */
+
+import type { ComponentNode, StyleValue } from './nodes';
+import type { ComponentDefinition, StructuredComponentDefinition } from './components';
+
+/**
+ * Rendering context shared between SSR and client
+ */
+export interface RenderingContext {
+  viewportWidth: number;
+  componentContext?: string | null;
+  parentComponentName?: string | null;
+}
+
+/**
+ * Style resolution options
+ * Unified options for resolving responsive styles
+ */
+export interface StyleResolutionOptions {
+  viewportWidth: number;
+  breakpoint?: 'base' | 'tablet' | 'mobile';
+}
+
+/**
+ * Component render options
+ * Shared options for rendering component instances
+ */
+export interface ComponentRenderOptions {
+  node: ComponentNode;
+  componentDef: StructuredComponentDefinition;
+  props: Record<string, unknown>;
+  children?: ComponentNode['children'];
+  viewportWidth: number;
+  componentContext?: string | null;
+  parentComponentName?: string | null;
+}
+
+/**
+ * Style merge options
+ */
+export interface StyleMergeOptions {
+  base: StyleValue | null | undefined;
+  override: StyleValue | null | undefined;
+  viewportWidth: number;
+}
+
+/**
+ * Template evaluation context
+ * Extensible context object for template processing in processStructure
+ */
+export interface TemplateContext {
+  /** Component instance props */
+  props: Record<string, unknown>;
+  /** Component definition (for variants, defaults) */
+  componentDef?: ComponentDefinition | StructuredComponentDefinition;
+  /** Future extension points (cms, page, etc.) */
+  [namespace: string]: unknown;
+}

package/lib/shared/types/styles.ts

@@ -0,0 +1,38 @@
+/**
+ * Style-related Types
+ */
+
+export interface StyleMapping {
+  _mapping: true;
+  prop: string;
+  values: Record<string, string | number>;
+}
+
+/**
+ * Link mapping for object-link href - maps prop values to link objects
+ * When values is omitted, acts as passthrough for link-type props
+ */
+export interface LinkMapping {
+  _mapping: true;
+  prop: string;
+  values?: Record<string, { href: string; target?: string }>;
+}
+
+export interface StyleObject {
+  [key: string]: string | number | StyleMapping;
+}
+
+/**
+ * Responsive style object supporting dynamic breakpoints
+ * Always includes 'base', plus any breakpoints defined in project.config.json
+ */
+export interface ResponsiveStyleObject {
+  base?: StyleObject;
+  [breakpointName: string]: StyleObject | undefined;
+}
+
+/**
+ * Style can be either a flat StyleObject (legacy) or ResponsiveStyleObject (new format)
+ */
+export type StyleValue = StyleObject | ResponsiveStyleObject;
+

package/lib/shared/types.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared TypeScript types and interfaces
+ * Used by both client and server code
+ * 
+ * This file maintains backward compatibility while using the new modular type system.
+ * All types are re-exported from the organized type modules.
+ */
+
+// Re-export all types from the new modular structure
+export * from './types/index';
+

package/lib/shared/utilityClassConfig.ts

@@ -0,0 +1,287 @@
+/**
+ * Centralized configuration for utility class mappings
+ * Single source of truth for property-to-prefix and CSS generation
+ */
+
+// Mapping of CSS properties to utility class prefixes
+export const propertyMap: Record<string, string> = {
+  // Padding
+  padding: 'p',
+  paddingTop: 'pt',
+  paddingRight: 'pr',
+  paddingBottom: 'pb',
+  paddingLeft: 'pl',
+  paddingInline: 'px',
+  paddingBlock: 'py',
+
+  // Margin
+  margin: 'm',
+  marginTop: 'mt',
+  marginRight: 'mr',
+  marginBottom: 'mb',
+  marginLeft: 'ml',
+  marginInline: 'mx',
+  marginBlock: 'my',
+
+  // Display & Layout
+  display: 'd',
+  flexDirection: 'fd',
+  justifyContent: 'jc',
+  alignItems: 'ai',
+  alignContent: 'ac',
+  flex: 'flex',
+  flexWrap: 'fw',
+  gap: 'g',
+  rowGap: 'rg',
+  columnGap: 'cg',
+
+  // Sizing
+  width: 'w',
+  height: 'h',
+  maxWidth: 'mw',
+  maxHeight: 'mh',
+  minWidth: 'miw',
+  minHeight: 'mih',
+
+  // Colors & Background
+  backgroundColor: 'bgc',
+  background: 'bg',
+  color: 'c',
+
+  // Borders & Radius
+  border: 'b',
+  borderRadius: 'br',
+  borderTop: 'bt',
+  borderRight: 'border-r',
+  borderBottom: 'bb',
+  borderLeft: 'bl',
+  borderTopLeftRadius: 'brtl',
+  borderTopRightRadius: 'brtr',
+  borderBottomLeftRadius: 'brbl',
+  borderBottomRightRadius: 'brbr',
+  borderColor: 'bc',
+
+  // Text
+  fontSize: 'fs',
+  fontWeight: 'fe',
+  fontFamily: 'ff',
+  textAlign: 'ta',
+  textDecoration: 'td',
+  lineHeight: 'lh',
+  letterSpacing: 'ls',
+  listStyle: 'lst',
+
+  // Transform & Effects
+  opacity: 'o',
+  transform: 'tm',
+  boxShadow: 'bs',
+  textShadow: 'ts',
+  filter: 'flt',
+
+  // Positioning
+  position: 'pos',
+  top: 'top',
+  right: 'r',
+  bottom: 'bo',
+  left: 'l',
+  zIndex: 'z',
+
+  // Grid Layout
+  gridTemplateColumns: 'gtc',
+  gridTemplateRows: 'gtr',
+  gridGap: 'gg',
+  gridAutoFlow: 'gaf',
+  gridColumn: 'gc',
+  gridRow: 'gr',
+  gridAutoRows: 'gar',
+  gridAutoColumns: 'gac',
+
+  // Flexbox extras
+  flexGrow: 'fg',
+  flexShrink: 'fs',
+  flexBasis: 'fb',
+  order: 'ord',
+
+  // Other
+  overflow: 'ov',
+  overflowX: 'ovx',
+  overflowY: 'ovy',
+  cursor: 'cu',
+  transition: 'tn',
+  objectFit: 'objf',
+  objectPosition: 'objp',
+  boxSizing: 'bs',
+  visibility: 'vis',
+};
+
+// Mapping of prefixes to CSS property names for dynamic rule generation
+export const prefixToCSSProperty: Record<string, string> = {
+  // Spacing
+  p: 'padding',
+  pt: 'padding-top',
+  pr: 'padding-right',
+  pb: 'padding-bottom',
+  pl: 'padding-left',
+  px: 'padding',
+  py: 'padding',
+  m: 'margin',
+  mt: 'margin-top',
+  mr: 'margin-right',
+  mb: 'margin-bottom',
+  ml: 'margin-left',
+  mx: 'margin',
+  my: 'margin',
+  g: 'gap',
+  rg: 'row-gap',
+  cg: 'column-gap',
+
+  // Sizing
+  w: 'width',
+  h: 'height',
+  mw: 'max-width',
+  mh: 'max-height',
+  miw: 'min-width',
+  mih: 'min-height',
+
+  // Colors & Background
+  bgc: 'background-color',
+  bg: 'background',
+  c: 'color',
+  bc: 'border-color',
+
+  // Borders
+  b: 'border',
+  br: 'border-radius',
+  brtl: 'border-top-left-radius',
+  brtr: 'border-top-right-radius',
+  brbl: 'border-bottom-left-radius',
+  brbr: 'border-bottom-right-radius',
+  bt: 'border-top',
+  bb: 'border-bottom',
+  bl: 'border-left',
+
+  // Text
+  fs: 'font-size',
+  fe: 'font-weight',
+  ff: 'font-family',
+  ta: 'text-align',
+  td: 'text-decoration',
+  lh: 'line-height',
+  ls: 'letter-spacing',
+  lst: 'list-style',
+
+  // Flexbox
+  fd: 'flex-direction',
+  jc: 'justify-content',
+  ai: 'align-items',
+  ac: 'align-content',
+  flex: 'flex',
+  fw: 'flex-wrap',
+  fg: 'flex-grow',
+  flsh: 'flex-shrink',
+  fb: 'flex-basis',
+  ord: 'order',
+
+  // Grid
+  gtc: 'grid-template-columns',
+  gtr: 'grid-template-rows',
+  gg: 'grid-gap',
+  gaf: 'grid-auto-flow',
+  gc: 'grid-column',
+  gr: 'grid-row',
+  gar: 'grid-auto-rows',
+  gac: 'grid-auto-columns',
+
+  // Effects
+  o: 'opacity',
+  bsh: 'box-shadow',
+  ts: 'text-shadow',
+  flt: 'filter',
+
+  // Positioning
+  pos: 'position',
+  top: 'top',
+  r: 'right',
+  bo: 'bottom',
+  l: 'left',
+  z: 'z-index',
+
+  // Other
+  ov: 'overflow',
+  ovx: 'overflow-x',
+  ovy: 'overflow-y',
+  cu: 'cursor',
+  tn: 'transition',
+  objf: 'object-fit',
+  objp: 'object-position',
+  bsz: 'box-sizing',
+  vis: 'visibility',
+};
+
+// Special value mappings for specific properties
+export const specialValueMappings: Record<string, Record<string, string>> = {
+  display: {
+    flex: 'f',
+    grid: 'g',
+    block: 'b',
+    inline: 'i',
+    'inline-block': 'ib',
+    none: 'h',
+  },
+  flexDirection: {
+    column: 'fd-col',
+    row: 'fd-row',
+  },
+  justifyContent: {
+    center: 'jc-c',
+    'flex-start': 'jc-s',
+    'flex-end': 'jc-e',
+    'space-between': 'jc-b',
+    'space-around': 'jc-a',
+    'space-evenly': 'jc-e',
+  },
+  alignItems: {
+    center: 'ai-c',
+    'flex-start': 'ai-s',
+    'flex-end': 'ai-e',
+    stretch: 'ai-s',
+    baseline: 'ai-b',
+  },
+  overflow: {
+    hidden: 'o-h',
+    auto: 'o-a',
+    scroll: 'o-s',
+    visible: 'o-v',
+  },
+  cursor: {
+    pointer: 'cursor-pointer',
+    default: 'cursor-default',
+  },
+};
+
+// Reverse mapping for class-to-style conversion
+export const classToStyleSpecialCases: Record<string, { prop: string; value: string }> = {
+  f: { prop: 'display', value: 'flex' },
+  'fd-col': { prop: 'flexDirection', value: 'column' },
+  'fd-row': { prop: 'flexDirection', value: 'row' },
+  g: { prop: 'display', value: 'grid' },
+  b: { prop: 'display', value: 'block' },
+  i: { prop: 'display', value: 'inline' },
+  ib: { prop: 'display', value: 'inline-block' },
+  h: { prop: 'display', value: 'none' },
+  'jc-c': { prop: 'justifyContent', value: 'center' },
+  'jc-s': { prop: 'justifyContent', value: 'flex-start' },
+  'jc-e': { prop: 'justifyContent', value: 'flex-end' },
+  'jc-b': { prop: 'justifyContent', value: 'space-between' },
+  'jc-a': { prop: 'justifyContent', value: 'space-around' },
+  'ai-c': { prop: 'alignItems', value: 'center' },
+  'ai-s': { prop: 'alignItems', value: 'flex-start' },
+  'ai-e': { prop: 'alignItems', value: 'flex-end' },
+  'ai-b': { prop: 'alignItems', value: 'baseline' },
+  'o-h': { prop: 'overflow', value: 'hidden' },
+  'o-a': { prop: 'overflow', value: 'auto' },
+  'o-s': { prop: 'overflow', value: 'scroll' },
+  'o-v': { prop: 'overflow', value: 'visible' },
+  'cursor-pointer': { prop: 'cursor', value: 'pointer' },
+  'cursor-default': { prop: 'cursor', value: 'default' },
+};