@synetics/ui 0.7.0-alpha

package/src/components/formular/types/form-provider.type.ts

@@ -0,0 +1,67 @@
+/// <reference path="../../../synetics.dev/pulsar.d.ts" />
+
+/**
+ * FormProvider component prop types
+ */
+
+import type { IFormular } from '@synetics/formular.dev';
+
+/**
+ * Props for the FormProvider component
+ *
+ * @template T - The shape of the form data
+ */
+export interface IFormProviderProps<T extends object> {
+  /** The form instance to provide context for */
+  readonly form?: IFormular<T>;
+
+  /** Initial data to populate the form with */
+  readonly data?: T;
+
+  /** Callback when form is saved (after validation) */
+  readonly onSaveCallback: () => void;
+
+  /** Callback when user quits/cancels the form */
+  readonly onQuitCallback: () => void;
+
+  /** Child components that will be rendered within the form (or a thunk returning children) */
+  readonly children: JSX.Children;
+}
+
+/**
+ * Modal command types for FormProvider
+ */
+export enum ModaleCommands {
+  YesCancel = 'yes-cancel',
+  OkCancel = 'ok-cancel',
+  Ok = 'ok',
+}
+
+/**
+ * Modal style types
+ */
+export enum ModaleStyle {
+  Primary = 'primary',
+  Secondary = 'secondary',
+  Warning = 'warning',
+  Danger = 'danger',
+  Info = 'info',
+}
+
+/**
+ * Modal result interface
+ */
+export interface IModaleResult {
+  readonly Yes?: boolean;
+  readonly No?: boolean;
+  readonly Ok?: boolean;
+  readonly Cancel?: boolean;
+}
+
+/**
+ * Translation keys for form messages
+ */
+export enum FormModaleMessagesTranslationKeyEnum {
+  OnQuitMessageKey = 'form.quit.confirm',
+  OnResetMessageKey = 'form.reset.confirm',
+}

package/src/components/formular/types/formular.types.ts

@@ -0,0 +1,49 @@
+/**
+ * TypeScript types for formular.dev validation results
+ * These types provide type safety when working with validation data
+ */
+
+/**
+ * Validation result from formular.dev
+ */
+export interface IValidationResult {
+  /** Whether this validation rule passed (true) or failed (false) */
+  state: boolean;
+
+  /** Name of the field being validated */
+  fieldName: string;
+
+  /** Validation rule code (e.g., 'REQUIRED', 'MIN_LENGTH_ERROR', 'CUSTOM') */
+  code: string;
+
+  /** Error message when validation fails (undefined when state is true) */
+  error?: string;
+
+  /** Guide/hint message to help user fix the error */
+  guide?: string;
+
+  /** Validation strategy name */
+  strategy?: string;
+}
+
+/**
+ * Field error for display in UI components
+ */
+export interface IFieldError {
+  /** Field name */
+  name: string;
+
+  /** Error message to display */
+  message: string;
+
+  /** Error code for programmatic handling */
+  code: string;
+}
+
+/**
+ * Field guide/hint for display in UI components
+ */
+export interface IFieldGuide {
+  /** Guide message to display */
+  message: string;
+}

package/src/components/formular/types/index.ts

@@ -0,0 +1,78 @@
+/**
+ * Type definitions for form components
+ */
+
+// Re-export formular.dev types for convenience
+export type { IFieldError, IFieldGuide, IValidationResult } from './formular.types';
+
+export interface FormFieldProps {
+  name: string;
+  label?: string;
+  placeholder?: string;
+  required?: boolean;
+  disabled?: boolean;
+  error?: string;
+  helperText?: string;
+}
+
+export interface FormInputProps extends FormFieldProps {
+  type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url';
+  value?: string;
+  onChange?: (value: string) => void;
+}
+
+export interface FormSelectProps extends FormFieldProps {
+  options: Array<{ value: string; label: string }>;
+  value?: string;
+  onChange?: (value: string) => void;
+}
+
+export interface FormCheckboxProps extends Omit<FormFieldProps, 'placeholder'> {
+  checked?: boolean;
+  onChange?: (checked: boolean) => void;
+}
+
+export interface FormRadioProps extends Omit<FormFieldProps, 'placeholder'> {
+  value: string;
+  checked?: boolean;
+  onChange?: (value: string) => void;
+}
+
+export interface FormGroupProps {
+  children: any;
+  className?: string;
+}
+
+export interface FormProps {
+  onSubmit?: (data: Record<string, any>) => void;
+  children: any;
+  className?: string;
+}
+
+/**
+ * Integrated field component props
+ * For components that include label, validation, etc.
+ */
+export interface IIntegratedFieldProps {
+  /** Field name (must match field descriptor) */
+  readonly name: string;
+  /** Optional CSS class name */
+  readonly className?: string;
+  /** Optional helper text */
+  readonly helperText?: string;
+  /** Label override (defaults to field.label) */
+  readonly label?: string;
+  /** Whether to show the label (default: true) */
+  readonly showLabel?: boolean;
+  /** Whether to show validation errors (default: true) */
+  readonly showErrors?: boolean;
+  /** Whether to show validation guides (default: true) */
+  readonly showGuides?: boolean;
+}
+
+// Export new type definitions
+export * from './field-component.type';
+export * from './field-descriptor-config.type';
+export * from './form-context.type';
+export * from './form-provider.type';
+export * from './portal.type';

package/src/components/formular/types/portal.type.ts

@@ -0,0 +1,36 @@
+/// <reference path="../../../synetics.dev/pulsar.d.ts" />
+
+/**
+ * Portal component type definitions
+ * For content projection and slot-based rendering
+ */
+
+/**
+ * Props for PortalSlot component
+ * Defines a target location where portal content can be rendered
+ */
+export interface IPortalSlotProps {
+  /** Unique identifier for this slot (e.g., 'form-a', 'form-b') */
+  readonly id: string
+  
+  /** Slot name/category (e.g., 'commands', 'actions', 'footer') */
+  readonly name: string
+  
+  /** Additional CSS classes for the slot container */
+  readonly className?: string
+}
+
+/**
+ * Props for Portal component
+ * Renders children at a matching PortalSlot location
+ */
+export interface IPortalProps {
+  /** ID to match with PortalSlot (e.g., form.id) */
+  readonly id: string
+  
+  /** Target slot name to render into (e.g., 'commands') */
+  readonly target: string
+  
+  /** Content to render in the portal */
+  readonly children: JSX.Children
+}

package/src/components/formular/utils/dev-logger.ts

@@ -0,0 +1,44 @@
+/**
+ * Development-only logging utilities
+ * These will be stripped out in production builds
+ */
+
+import { isDev } from '@synetics/synetics.dev/env';
+
+const isDevMode = isDev();
+
+export const devLog = {
+  /**
+   * Log a warning message (only in development)
+   */
+  warn: (...args: any[]) => {
+    if (isDevMode) {
+      console.warn(...args);
+    }
+  },
+
+  /**
+   * Log an error message (always logged)
+   */
+  error: (...args: any[]) => {
+    console.error(...args);
+  },
+
+  /**
+   * Log a debug message (only in development)
+   */
+  debug: (...args: any[]) => {
+    if (isDevMode) {
+      console.log(...args);
+    }
+  },
+
+  /**
+   * Log an info message (only in development)
+   */
+  info: (...args: any[]) => {
+    if (isDevMode) {
+      console.info(...args);
+    }
+  },
+};

package/src/components/formular/utils/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Utility functions for form components
+ */
+
+export function classNames(...classes: (string | boolean | undefined)[]): string {
+  return classes.filter(Boolean).join(' ');
+}
+
+export function generateId(prefix: string = 'field'): string {
+  return `${prefix}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+export function isEmpty(value: any): boolean {
+  if (value === null || value === undefined) return true;
+  if (typeof value === 'string') return value.trim().length === 0;
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === 'object') return Object.keys(value).length === 0;
+  return false;
+}
+
+// Export hooks and utilities
+export * from './use-field-descriptors';
+export * from './use-formular-manager';

package/src/components/formular/utils/use-field-descriptors.ts

@@ -0,0 +1,75 @@
+/**
+ * useFieldDescriptors hook
+ * Converts declarative field configuration to IFieldDescriptor[]
+ *
+ * @example
+ * ```typescript
+ * const userFields = useFieldDescriptors<User>({
+ *   username: {
+ *     type: 'text',
+ *     validation: ValidationPresets.username(true)
+ *   },
+ *   email: {
+ *     type: 'email',
+ *     validation: ValidationPresets.email(true)
+ *   }
+ * })
+ * ```
+ */
+
+import type { IFieldDescriptor } from '@synetics/formular.dev';
+import type { FieldDescriptorConfig } from '../types';
+
+/**
+ * Hook for creating field descriptors from configuration
+ *
+ * @template T - The shape of the form data
+ * @param config - Field configuration object
+ * @returns Array of field descriptors
+ */
+export function useFieldDescriptors<T extends Record<string, any>>(
+  config: FieldDescriptorConfig<T>
+): IFieldDescriptor[] {
+  return Object.entries(config).map(([key, fieldConfig], index) => {
+    const descriptor: IFieldDescriptor = {
+      id: index,
+      name: key,
+      type: (fieldConfig?.type || 'text') as any,
+      label: fieldConfig?.label || key,
+      value: null,
+      objectValue: null,
+      defaultValue: fieldConfig?.defaultValue ?? null,
+      errors: [],
+      guides: [],
+      validationOptions: {
+        min: fieldConfig?.min ? { value: fieldConfig.min } : undefined,
+        max: fieldConfig?.max ? { value: fieldConfig.max } : undefined,
+        minLength: fieldConfig?.minLength ? { value: fieldConfig.minLength } : undefined,
+        maxLength: fieldConfig?.maxLength ? { value: fieldConfig.maxLength } : undefined,
+        pattern: fieldConfig?.pattern ? { value: new RegExp(fieldConfig.pattern) } : undefined,
+      },
+      options:
+        fieldConfig?.options?.map((opt, idx) => ({
+          id: idx,
+          value: opt.value,
+          label: opt.label,
+          selected: false,
+        })) || [],
+      isValid: true, // Start valid, validation constraints will determine actual state
+      isDirty: false,
+      isPristine: true,
+      isFocus: false,
+      shouldValidate: true,
+      loaded: false,
+      changed: false,
+      mask: fieldConfig?.mask,
+      disabled: fieldConfig?.disabled,
+      readOnly: fieldConfig?.readOnly,
+      placeholder: fieldConfig?.placeholder,
+      // Spread any additional properties from config
+      ...fieldConfig,
+    };
+
+    return descriptor;
+  });
+}

package/src/components/formular/utils/use-formular-manager.ts

@@ -0,0 +1,37 @@
+/**
+ * useFormularManager hook
+ * Provides access to the FormularManager instance
+ * Can be injected via props or retrieved from service container
+ */
+
+import type { IFormularManager } from '@synetics/formular.dev';
+
+/**
+ * Hook for accessing the FormularManager singleton
+ *
+ * @param manager - Optional manager instance (for dependency injection)
+ * @returns The FormularManager instance
+ *
+ * @example
+ * ```typescript
+ * const formManager = useFormularManager()
+ * const form = useMemo(
+ *   () => formManager.createFromDescriptors('userForm', userFields),
+ *   [formManager, userFields]
+ * )
+ * ```
+ */
+export function useFormularManager(manager?: IFormularManager): IFormularManager {
+  if (manager) {
+    return manager;
+  }
+
+  // TODO: Retrieve from service container when available
+  // For now, assume FormularManager is a singleton
+  // return ServiceManager.get(SFormularManager)
+
+  throw new Error(
+    'FormularManager must be provided via props or service container. ' +
+      'Pass manager prop to useFormularManager() or configure service container.'
+  );
+}

package/src/components/hooks/use-drawer-position.ts

@@ -0,0 +1,91 @@
+import { useEffect, useState } from '@synetics/synetics.dev';
+
+interface UseDrawerPositionOptions {
+  containerRef: { current: HTMLElement | null };
+  isOpen: boolean;
+  desiredWidth: string;
+  desiredHeight: string;
+}
+
+interface DrawerStyle {
+  position: 'absolute' | 'fixed';
+  width: string;
+  height: string;
+  top?: string;
+  bottom?: string;
+  left?: string;
+  right?: string;
+  zIndex: number;
+}
+
+/**
+ * Hook to calculate drawer positioning based on container position
+ * and available space in the viewport
+ */
+export function useDrawerPosition({
+  containerRef,
+  isOpen,
+  desiredWidth,
+  desiredHeight,
+}: UseDrawerPositionOptions): () => DrawerStyle {
+  const [style, setStyle] = useState<DrawerStyle>({
+    position: 'absolute',
+    width: desiredWidth,
+    height: desiredHeight,
+    top: '100%',
+    left: '0',
+    zIndex: 1000,
+  });
+
+  useEffect(() => {
+    if (!isOpen || !containerRef.current) {
+      return;
+    }
+
+    const updatePosition = () => {
+      const container = containerRef.current;
+      if (!container) return;
+
+      const rect = container.getBoundingClientRect();
+      const viewportHeight = window.innerHeight;
+      const viewportWidth = window.innerWidth;
+
+      // Parse numeric values
+      const drawerHeight = parseInt(desiredHeight);
+      const drawerWidth = parseInt(desiredWidth);
+
+      // Check space below
+      const spaceBelow = viewportHeight - rect.bottom;
+      const spaceAbove = rect.top;
+
+      // Determine if drawer should open above or below
+      const openAbove = spaceBelow < drawerHeight && spaceAbove > spaceBelow;
+
+      // Determine horizontal position
+      const spaceRight = viewportWidth - rect.left;
+      const alignRight = spaceRight < drawerWidth;
+
+      setStyle({
+        position: 'absolute',
+        width: desiredWidth,
+        height: desiredHeight,
+        top: openAbove ? undefined : '100%',
+        bottom: openAbove ? '100%' : undefined,
+        left: alignRight ? undefined : '0',
+        right: alignRight ? '0' : undefined,
+        zIndex: 1000,
+      });
+    };
+
+    updatePosition();
+    window.addEventListener('resize', updatePosition);
+    window.addEventListener('scroll', updatePosition, true);
+
+    return () => {
+      window.removeEventListener('resize', updatePosition);
+      window.removeEventListener('scroll', updatePosition, true);
+    };
+  });
+
+  return () => style();
+}

package/src/components/interfaces/component-config-internal.interface.ts

@@ -0,0 +1,10 @@
+/**
+ * Component configuration internal interface
+ * Used internally by ComponentConfig builder
+ */
+
+import { type IComponentConfig } from './component-config.interface'
+
+export interface IComponentConfigInternal extends IComponentConfig {
+  _built: boolean
+}

package/src/components/interfaces/component-config.interface.ts

@@ -0,0 +1,57 @@
+/**
+ * Common component configuration interface
+ * Used across all components to provide consistent styling configuration
+ */
+
+import { type ComponentColor, type ComponentSize, type ComponentVariant } from '@synetics/design-tokens'
+
+export interface IComponentConfig {
+  // Visual style
+  readonly variant?: ComponentVariant
+  readonly color?: ComponentColor
+  readonly size?: ComponentSize
+  
+  // Border
+  readonly rounded?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full'
+  readonly border?: boolean
+  
+  // Shadow
+  readonly shadow?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+  
+  // States
+  readonly disabled?: boolean
+  readonly loading?: boolean
+  readonly fullWidth?: boolean
+  
+  // Transitions
+  readonly transition?: boolean
+  readonly transitionDuration?: 'fast' | 'normal' | 'slow'
+  
+  // Interactive states
+  readonly hover?: boolean
+  readonly focus?: boolean
+  readonly active?: boolean
+  
+  // Additional styling
+  readonly className?: string
+}
+
+/**
+ * Default component configuration
+ */
+export const defaultComponentConfig: Required<Omit<IComponentConfig, 'className'>> = {
+  variant: 'solid',
+  color: 'primary',
+  size: 'md',
+  rounded: 'md',
+  border: true,
+  shadow: 'sm',
+  disabled: false,
+  loading: false,
+  fullWidth: false,
+  transition: true,
+  transitionDuration: 'normal',
+  hover: true,
+  focus: true,
+  active: true
+}