@coherent.js/core 1.0.0-beta.3 → 1.0.0-beta.6

package/types/index.d.ts

@@ -5,6 +5,9 @@
  * @version 1.0.0-beta.1
  */
 
+// Re-export strict element types
+export * from './elements';
+
 // ============================================================================
 // Basic Types
 // ============================================================================
@@ -12,9 +15,12 @@
 /** Primitive values that can be rendered as HTML */
 export type Primitive = string | number | boolean | null | undefined;
 
+/** Allow objects and functions in attributes */
+export type AttributeValue = Primitive | object;
+
 /** HTML attributes object */
 export interface HTMLAttributes {
-  [key: string]: Primitive | (() => Primitive);
+  [key: string]: AttributeValue;
   className?: string;
   class?: string;
   id?: string;
@@ -47,15 +53,151 @@ export interface ElementProps extends HTMLAttributes {
   text?: Primitive;
 }
 
-/** A Coherent.js HTML element definition */
+/**
+ * Permissive element type - allows any tag name and any attributes.
+ * For strict type checking with per-element attributes, use StrictCoherentElement.
+ *
+ * @example
+ * ```typescript
+ * // Permissive - accepts any attributes on any element
+ * const element: CoherentElement = {
+ *   div: { checked: true }  // No error (but incorrect HTML)
+ * };
+ *
+ * // For strict checking, use StrictCoherentElement instead
+ * import { StrictCoherentElement } from '@coherent.js/core';
+ * const strictElement: StrictCoherentElement = {
+ *   div: { checked: true }  // Type error! checked not valid on div
+ * };
+ * ```
+ *
+ * @see StrictCoherentElement for strict per-element attribute validation
+ */
 export interface CoherentElement {
-  [tagName: string]: ElementProps | string;
+  [tagName: string]: ElementProps | string | undefined;
+
+  // Common HTML Elements
+  a?: ElementProps | string;
+  abbr?: ElementProps | string;
+  address?: ElementProps | string;
+  area?: ElementProps | string;
+  article?: ElementProps | string;
+  aside?: ElementProps | string;
+  audio?: ElementProps | string;
+  b?: ElementProps | string;
+  base?: ElementProps | string;
+  bdi?: ElementProps | string;
+  bdo?: ElementProps | string;
+  blockquote?: ElementProps | string;
+  body?: ElementProps | string;
+  br?: ElementProps | string;
+  button?: ElementProps | string;
+  canvas?: ElementProps | string;
+  caption?: ElementProps | string;
+  cite?: ElementProps | string;
+  code?: ElementProps | string;
+  col?: ElementProps | string;
+  colgroup?: ElementProps | string;
+  data?: ElementProps | string;
+  datalist?: ElementProps | string;
+  dd?: ElementProps | string;
+  del?: ElementProps | string;
+  details?: ElementProps | string;
+  dfn?: ElementProps | string;
+  dialog?: ElementProps | string;
+  div?: ElementProps | string;
+  dl?: ElementProps | string;
+  dt?: ElementProps | string;
+  em?: ElementProps | string;
+  embed?: ElementProps | string;
+  fieldset?: ElementProps | string;
+  figcaption?: ElementProps | string;
+  figure?: ElementProps | string;
+  footer?: ElementProps | string;
+  form?: ElementProps | string;
+  h1?: ElementProps | string;
+  h2?: ElementProps | string;
+  h3?: ElementProps | string;
+  h4?: ElementProps | string;
+  h5?: ElementProps | string;
+  h6?: ElementProps | string;
+  head?: ElementProps | string;
+  header?: ElementProps | string;
+  hgroup?: ElementProps | string;
+  hr?: ElementProps | string;
+  html?: ElementProps | string;
+  i?: ElementProps | string;
+  iframe?: ElementProps | string;
+  img?: ElementProps | string;
+  input?: ElementProps | string;
+  ins?: ElementProps | string;
+  kbd?: ElementProps | string;
+  label?: ElementProps | string;
+  legend?: ElementProps | string;
+  li?: ElementProps | string;
+  link?: ElementProps | string;
+  main?: ElementProps | string;
+  map?: ElementProps | string;
+  mark?: ElementProps | string;
+  menu?: ElementProps | string;
+  meta?: ElementProps | string;
+  meter?: ElementProps | string;
+  nav?: ElementProps | string;
+  noscript?: ElementProps | string;
+  object?: ElementProps | string;
+  ol?: ElementProps | string;
+  optgroup?: ElementProps | string;
+  option?: ElementProps | string;
+  output?: ElementProps | string;
+  p?: ElementProps | string;
+  picture?: ElementProps | string;
+  pre?: ElementProps | string;
+  progress?: ElementProps | string;
+  q?: ElementProps | string;
+  rp?: ElementProps | string;
+  rt?: ElementProps | string;
+  ruby?: ElementProps | string;
+  s?: ElementProps | string;
+  samp?: ElementProps | string;
+  script?: ElementProps | string;
+  section?: ElementProps | string;
+  select?: ElementProps | string;
+  slot?: ElementProps | string;
+  small?: ElementProps | string;
+  source?: ElementProps | string;
+  span?: ElementProps | string;
+  strong?: ElementProps | string;
+  style?: ElementProps | string;
+  sub?: ElementProps | string;
+  summary?: ElementProps | string;
+  sup?: ElementProps | string;
+  table?: ElementProps | string;
+  tbody?: ElementProps | string;
+  td?: ElementProps | string;
+  template?: ElementProps | string;
+  textarea?: ElementProps | string;
+  tfoot?: ElementProps | string;
+  th?: ElementProps | string;
+  thead?: ElementProps | string;
+  time?: ElementProps | string;
+  title?: ElementProps | string;
+  tr?: ElementProps | string;
+  track?: ElementProps | string;
+  u?: ElementProps | string;
+  ul?: ElementProps | string;
+  var?: ElementProps | string;
+  video?: ElementProps | string;
+  wbr?: ElementProps | string;
 }
 
-/** Valid nodes that can be rendered */
+/**
+ * Valid nodes that can be rendered.
+ * Accepts both permissive CoherentElement and strict StrictCoherentElement.
+ */
 export type CoherentNode =
   | Primitive
   | CoherentElement
+  | StrictCoherentElement
   | CoherentNode[]
   | CoherentComponent
   | ContextProvider
@@ -218,11 +360,11 @@ export interface StateUtilities<S extends ComponentState = ComponentState> {
 }
 
 /** Enhanced props with state for withState HOC */
-export interface WithStateProps<P extends ComponentProps, S extends ComponentState> extends P {
+export type WithStateProps<P extends ComponentProps, S extends ComponentState> = P & {
   state: S;
   setState: (newState: Partial<S> | ((state: S) => Partial<S>)) => void;
   stateUtils: StateUtilities<S>;
-}
+};
 
 // ============================================================================
 // Higher-Order Components (HOCs)
@@ -256,7 +398,7 @@ export interface MemoOptions {
 }
 
 /** Memoized function with utilities */
-export interface MemoizedFunction<T extends (...args: any[]) => any> extends T {
+export type MemoizedFunction<T extends (...args: any[]) => any> = T & {
   cache: Map<string, any>;
   clear(): void;
   delete(key: string): boolean;
@@ -265,7 +407,7 @@ export interface MemoizedFunction<T extends (...args: any[]) => any> extends T {
   refresh(...args: Parameters<T>): ReturnType<T>;
   stats?(): { hits: number; misses: number; evictions: number };
   resetStats?(): void;
-}
+};
 
 /** Props transformation function */
 export type PropsTransform<P, T> = (props: P, state?: ComponentState, context?: ComponentContext) => T | Promise<T>;
@@ -370,14 +512,57 @@ export interface PerformanceMetrics {
 // Core Functions
 // ============================================================================
 
-/** Render a Coherent node to HTML string */
-export function render(obj: CoherentNode): string;
+/** Render options for `render(component, options)` */
+export interface RenderOptions {
+  enableCache?: boolean;
+  enableMonitoring?: boolean;
+  minify?: boolean;
+  maxDepth?: number;
+  cacheSize?: number;
+  cacheTTL?: number;
+  scoped?: boolean;
+  encapsulate?: boolean;
+}
+
+/** Render a Coherent node to an HTML string */
+export function render(component: CoherentNode, options?: RenderOptions): string;
 
-/** Alias for render */
-export function render(obj: CoherentNode): string;
+export interface RenderUtilityOptions {
+  enablePerformanceMonitoring?: boolean;
+  template?: string;
+}
+
+export function renderWithMonitoring(component: CoherentNode, options?: RenderUtilityOptions): string;
+export function renderWithTemplate(component: CoherentNode, options?: RenderUtilityOptions): string;
+export function renderComponentFactory(
+  componentFactory: (...args: any[]) => CoherentNode | Promise<CoherentNode>,
+  factoryArgs: any[],
+  options?: RenderUtilityOptions
+): Promise<string>;
+export function isCoherentComponent(obj: unknown): boolean;
+export function createErrorResponse(
+  error: Error,
+  context?: string
+): {
+  error: string;
+  message: string;
+  context: string;
+  timestamp: string;
+};
 
-/** Synchronous version of render */
-export function renderSync(obj: CoherentNode): string;
+export function isPeerDependencyAvailable(packageName: string): boolean;
+export function importPeerDependency(packageName: string, integrationName: string): Promise<any>;
+export function createLazyIntegration(
+  packageName: string,
+  integrationName: string,
+  createIntegration: (module: any) => (...args: any[]) => any
+): (...args: any[]) => Promise<any>;
+export function checkPeerDependencies(
+  dependencies: Array<{ package: string; integration: string }>
+): Record<string, boolean>;
+
+export function hasChildren(component: unknown): boolean;
+export function normalizeChildren(children: unknown): unknown[];
 
 /** Escape HTML characters in text */
 export function escapeHtml(text: string): string;
@@ -564,55 +749,6 @@ export class VDOMDiffer {
   patch(element: HTMLElement, patches: VDOMPatch[]): void;
 }
 
-// ============================================================================
-// Advanced Rendering Functions (Additional)
-// ============================================================================
-
-/** Render options */
-export interface RenderOptions {
-  cache?: boolean;
-  pretty?: boolean;
-  minify?: boolean;
-  streaming?: boolean;
-  chunkSize?: number;
-}
-
-/** Render component to string */
-export function render(component: CoherentNode, options?: RenderOptions): string;
-
-/** Render multiple components in batch */
-export function renderBatch(components: CoherentNode[], options?: RenderOptions): string[];
-
-/** Render to chunks generator */
-export function renderToChunks(component: CoherentNode, options?: RenderOptions): Generator<string, void, unknown>;
-
-/** Render to stream async generator */
-export function renderToStream(component: CoherentNode, options?: RenderOptions): AsyncGenerator<string, void, unknown>;
-
-/** Get rendering cache */
-export function getCache(): Map<string, any>;
-
-/** Reset rendering cache */
-export function resetCache(): void;
-
-/** Get rendering statistics */
-export function getRenderingStats(): {
-  totalRenders: number;
-  cacheHits: number;
-  cacheMisses: number;
-  averageRenderTime: number;
-};
-
-/** Precompile component for faster rendering */
-export function precompileComponent(component: CoherentNode, options?: RenderOptions): any;
-
-/** Render with timing information */
-export function renderWithTiming(component: CoherentNode, options?: RenderOptions): {
-  html: string;
-  time: number;
-  metrics: Record<string, any>;
-};
-
 // ============================================================================
 // CSS Management (Additional)
 // ============================================================================
@@ -720,8 +856,6 @@ export const componentUtils: ComponentUtils;
 /** Default export with all core functionality */
 declare const coherent: {
   render: typeof render;
-  render: typeof render;
-  renderSync: typeof renderSync;
   withState: typeof withState;
   memo: typeof memo;
   validateComponent: typeof validateComponent;