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 these values into the specified types.

  attributes: { 
      theme: { type: String, default: 'light' },
      maxItems: { type: Number, default: 10 },
      expanded: { type: Boolean, default: false }
  }

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:
  • Client-Side: Coerced using value === '' ? true : (value !== 'false' && value !== null). Empty attributes like disabled evaluate to true.
  • Server-Side: Coerced using value !== 'false' && value !== null && value !== ''.
• Number: Evaluated using Number(value). Strings that are not valid numbers resolve to NaN.
• String: Evaluated using String(value).

When reactive state tokens are bound to element attributes within templates (for example, <button disabled="{{ isDisabled }}">), Coralite handles native HTML boolean attributes with special presence logic:

• Toggled Removal: If the bound token resolves to a falsy value (specifically "", "false", "null", "0", or "undefined"), Coralite completely removes the attribute from the DOM element (e.g., calling element.removeAttribute('disabled')). This matches browser expectations, where the mere presence of a boolean attribute makes it active.
• Presence Insertion: If the value evaluates to truthy, the attribute is set as an empty string presence attribute (e.g. element.setAttribute('disabled', '')).
• The Reserved List: This toggling behavior is restricted to standard HTML boolean attributes including: allowfullscreen, async, autofocus, autoplay, checked, controls, default, defer, disabled, formnovalidate, hidden, inert, ismap, itemscope, loop, multiple, muted, nomodule, novalidate, open, playsinline, readonly, required, reversed, selected, and truespeed.
• Limitation: Custom boolean attributes (like is-active="{{ isActive }}") do not use this toggling logic; instead, their values are written directly as standard string attributes (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 client block is the controller for your component in the browser. This is where you add event listeners and mutate state. Formerly known as script.

  client: ({ state, signal, refs, observe }) => {
      // 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; 
      }, { signal }); // Use the provided 'signal' for auto-cleanup
  }

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

  type CoraliteModuleSlotFunction = (slotNodes: Node[], state: any) => Node[] | string | undefined | null

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));
      }
  }