defineComponent API Reference

This document details the exact API signatures, options, and types for Coralite's core defineComponent plugin.

For a conceptual guide on how to use dynamic components, see the Components Guide.

  function defineComponent(options: DefineComponentOptions): PluginDefinition

The defineComponent function accepts a single configuration object with the following isolated blocks. Note: All components MUST have a hyphen in their name (e.g., <my-component>).

The attributes block defines the inputs your component accepts from HTML. Coralite automatically coerces, transforms, and validates these values through a robust attribute schema engine.

  attributes: { 
      // Type shorthand syntax
      expanded: Boolean,
  
      // Array shorthand syntax (implicit String type & values check)
      variant: ['primary', 'secondary', 'danger'],
  
      // Verbose schema definition with transform and validate pipeline
      theme: { type: String, default: 'light', values: ['light', 'dark', 'system'] },
      maxItems: { type: Number, default: 10, validate: (val) => val > 0 || 'maxItems must be positive' },
      apiKey: { type: String, required: true },
      slug: {
          type: String,
          transform: (val) => val.toLowerCase().trim(),
          validate: (val) => val.length >= 3 || 'Slug must be at least 3 characters'
      }
  }

Attributes execute sequentially through a strict 6-step lifecycle pipeline during component initialization and state changes. When validation fails (e.g., missing required attribute, values enum mismatch, or validate predicate failure), Coralite records the error message gracefully in state.errors and flat error_* tokens without halting SSR or crashing client scripts:

1. 1. required Check: Asserts attribute presence if required: true is configured. Records "Attribute \"\" is required." on omission.
2. 2. Type coerce: Coerces raw attribute string into specified primitive constructor (Boolean, Number, or String).
3. 3. transform: Runs custom synchronous transform(val) function to format or sanitize value. Thrown errors are recorded in state.errors while retaining the attempted value.
4. 4. values Check: Validates that value exists in allowed values: [...] enumeration array. Records formatted expected values error on mismatch.
5. 5. validate: Invokes custom synchronous validate(val) predicate/function. Returning false sets default error message; returning a string records custom message; throwing records error message.
6. 6. State Application: Applies the validated value or retains attempted input in state[key] and updates reactive state.errors and flat error_* template tokens.

Coralite provides two zero-overhead mechanisms to display and handle attribute validation feedback:

• JS Access (state.errors): A reactive dictionary mapping camelCase attribute names to error string messages (e.g. state.errors.age). Implemented as a nested reactive Proxy that automatically tracks getter and observer dependencies on read, symmetrically updates both camelCase and kebab-case flat error_* tokens on mutation/deletion, and schedules reactive DOM re-renders upon property mutation, deletion, or whole-object assignment (state.errors = { ... }). When all attributes are valid, Object.keys(state.errors).length === 0.
• Flat Template Tokens ({{ error_fieldName }}): Automatic flat template tokens populated on state in both camelCase and kebab-case aliases (e.g. {{ error_userAge }} and {{ error_user-age }}). Default to "" (empty string) when valid.
• Client Context (errors): Provided directly in client controller signatures: client: ({ state, errors, ... }) => ....

Coralite maps declared attribute names from camelCase (e.g., isChecked) to their kebab-case equivalent in HTML (e.g., is-checked) and coerces them into JavaScript primitives. Changes to HTML attributes via setAttribute automatically update their values in the component state.

The coercion rules for the supported primitive constructors are detailed below:

• Boolean: Coerced using value === '' ? true : (value !== 'false' && value !== null) on both server and client. Empty attributes like disabled evaluate to true.
• Number: Evaluated using Number(value). Strings that are not valid numbers resolve to NaN.
• String: Evaluated using String(value).

When single reactive state tokens are bound to element attributes within templates, Coralite applies intelligent toggling and auto-removal rules depending on the attribute type:

• 43 Standard Native HTML Boolean Attributes (Presence Toggling): When bound to a boolean attribute (such as disabled="{{ isDisabled }}", hidden="{{ isHidden }}", required="{{ isReq }}", allowpaymentrequest="{{ pay }}"), if the value resolves to falsy (false, "false", null, "null", undefined, "undefined", "", 0, "0"), the attribute is completely removed from the element. When truthy, it is rendered as an empty string presence attribute (e.g. disabled="").
  Supported 43 Boolean Attributes: allowfullscreen, allowpaymentrequest, async, autofocus, autoplay, checked, compact, controls, credentialless, declare, default, defer, disabled, disablepictureinpicture, disableremoteplayback, formnovalidate, hidden, inert, ismap, itemscope, loop, multiple, muted, nohref, nomodule, noresize, noshade, novalidate, nowrap, open, playsinline, readonly, required, reversed, scoped, seamless, selected, shadowrootclonable, shadowrootdelegatesfocus, shadowrootserializable, truespeed, typemustmatch, and webkitdirectory.
• WAI-ARIA Attributes (aria-* Auto-Removal): When an aria-* attribute (e.g. aria-hidden="{{ isHidden }}", aria-expanded="{{ expanded }}", aria-label="{{ label }}", aria-valuenow="{{ progress }}") is bound with a single template token:
  • If the value evaluates to falsy (false, "false", null, "null", undefined, "undefined", ""), the attribute is completely removed from the element.
  • Numeric 0 / "0" Preservation: Numeric 0 and "0" are valid ARIA values (e.g., aria-valuenow="0") and do NOT trigger removal. They resolve to "0".
  • If truthy (or 0), the attribute is set to its evaluated string representation (e.g., aria-hidden="true", aria-label="Search").
• Standard Custom Attributes: Standard custom or unreserved attributes (e.g. is-active="{{ isActive }}") are evaluated as string values (e.g., is-active="false").

The server block is used for heavy-lifting, such as database queries or API calls. This code runs only on the server during the build process and is completely removed from the JavaScript sent to the browser. Formerly known as data.

  async server(context) {
      const users = await db.users.findMany();
      return { users };
  }

Note: In testing mode, you can override this block for specific components to provide deterministic mock data.

Getters are pure functions used to calculate derived data. They are reactive; if an attribute or a data value changes, the getter automatically re-calculates.

  getters: {
      // state is a Read-Only Proxy here
      visibleUsers: (state) => state.users.slice(0, state.maxItems)
  }

The style block defines declarative, reactive inline CSS properties and CSS Custom Properties (--*) on the custom element host tag.

  style: {
      // CSS Custom Property (preserved with -- prefix)
      '--accent-color': (state) => state.theme === 'dark' ? '#38bdf8' : '#0284c7',
      
      // Standard CSS property (automatically camelCase -> kebab-case)
      backgroundColor: (state) => state.isActive ? '#e0f2fe' : null,
      fontSize: (state) => `${state.size}px`,
      
      // Static values
      cursor: 'pointer'
  }

• Property Name Normalization: Standard camelCase properties (e.g., backgroundColor) are automatically converted to kebab-case (e.g., background-color). Custom property names starting with -- are preserved as-is.
• Removal Triggers: Returning null, undefined, false, or '' (empty string) removes the property from the host element's inline style (`this.style.removeProperty()` on client, omitted in SSR).
• Zero Value Preservation: Returning the numeric value 0 (zero) is strictly preserved as valid CSS (e.g., opacity: 0).
• Synchronous Function Enforcement: Style getter functions must be strictly synchronous. Returning a Promise throws a CoraliteError.

The client block is the controller for your component in the browser. This is where you add event listeners, mutate state, and dispatch custom events. Formerly known as script.

  client: ({ state, signal, refs, observe, emit }) => {
      // Access unique DOM elements via the 'refs' utility
      const btn = refs('loadMoreBtn');
      
      // Register an observer to react to state changes
      observe('maxItems', (newVal, oldVal) => {
          console.log(`maxItems updated from ${oldVal} to ${newVal}`);
      });
  
      btn.addEventListener('click', () => {
          // Imperative mutation triggers DOM updates
          state.maxItems += 10; 
  
          // Dispatch custom DOM event to parent components
          emit('items-expanded', { count: state.maxItems });
      }, { signal }); // Use the provided 'signal' for auto-cleanup
  }

Allows you to intercept and transform content passed into your component's slots.

  type CoraliteSlotContext<state = any> = {
    state: State;                                  // reactive proxy (client) / plain merged state (SSR)
    observe: (prop: string, cb: (newVal: any, oldVal?: any) =&gt; any) =&gt; () =&gt; void; // ALWAYS returns a disposer
    signal: AbortSignal;
    root: HTMLElement | null;                      // element on client, null during SSR build
    refs: (name: string) =&gt; HTMLElement | null;    // no-op returning null on SSR
    instanceId: string;
  } &amp; Record<string, any>
  
  type SlotTransformer<state = any> = (
    nodes: Node[],
    context: CoraliteSlotContext<state>
  ) =&gt; Node[] | Node | string | null | Promise<node[] | node string null>
      </node[]></state></state></string,></state>

To ensure high performance and prevent unnecessary re-rendering during client-side hydration, Coralite uses a "Void = Bypass" approach for slot transformations:

• undefined (Bypass): Signals the framework to skip processing and preserve the current content. On the server, it preserves the original AST nodes; on the client, it preserves the existing DOM nodes. Use this in the browser to prevent flushing SSR-rendered content.
• null, "", or [] (Clear): Explicitly instructs the framework to remove all content from the slot.

  slots: {
      default: (nodes, state) => {
          // Bypass hydration in the browser to preserve SSR content
          if (typeof window !== 'undefined') return undefined;
  
          // Otherwise, perform complex transformation on the server
          return nodes.map(n => transform(n));
      }
  }