Q2 Tecton Framework Wrappers

Common errors

• Error: Uncaught (in promise): Error: A custom element with name 'tct-button' has already been defined.

  cause Attempting to call `defineCustomElements()` multiple times, or importing the Tecton elements bundle more than once in a single execution context.
  fix Ensure `defineCustomElements()` is called only once in your application. Check for duplicate imports of Tecton element bundles or loaders.

• [Vue warn]: Unknown custom element: <tct-button> - did you register the component correctly?

  cause The underlying custom element `tct-button` was not registered before the Vue wrapper attempted to use it, or Vue is not configured to recognize custom elements.
  fix Call `defineCustomElements()` from `q2-tecton-elements/loader` at the application's entry point. For Vue, ensure `app.config.isCustomElement = (tag) => tag.startsWith('tct-')` is configured if you're not using the wrappers and interacting with raw web components.

Warnings

• breaking The Tecton system dropped support for Internet Explorer with version 1.0. Applications targeting IE11 or older browsers will no longer function as expected without significant polyfills or alternative strategies.
  Fix: Ensure target browser compatibility does not include Internet Explorer. Update your `browserslist` configuration to exclude IE.
• breaking All events emitted by Tecton components were prefixed with `tct` starting from Tecton v1.65.0. This is a breaking change for existing event listeners.
  Fix: Update all event listeners for Tecton components to use the `tct` prefix (e.g., `tctClick` instead of `click`).
• gotcha Custom elements must be defined globally before framework wrappers can instantiate them. Forgetting to call `defineCustomElements()` or calling it too late will result in errors.
  Fix: Ensure `defineCustomElements()` from `q2-tecton-elements/loader` is called once, early in your application's lifecycle, typically before mounting your main framework application.

Install

• npm install q2-tecton-framework-wrappers npm
• yarn add q2-tecton-framework-wrappers yarn
• pnpm add q2-tecton-framework-wrappers pnpm

Imports

• defineCustomElements
  wrong:

  import { defineCustomElements } from 'q2-tecton-framework-wrappers';

  correct:

  import { defineCustomElements } from 'q2-tecton-elements/loader';

  This is crucial for registering the underlying custom elements before any framework wrappers can utilize them. It comes from the `q2-tecton-elements` package loader, not the wrappers directly.
• applyPolyfills

  import { applyPolyfills, defineCustomElements } from 'q2-tecton-elements/loader';

  In older environments or for specific browser support, `applyPolyfills` might be necessary before `defineCustomElements` to ensure web components function correctly.
• TctButton
  wrong:

  import { TctButton } from 'q2-tecton-elements';

  correct:

  import { TctButton } from 'q2-tecton-framework-wrappers/vue';
  // or
  import { TctButton } from 'q2-tecton-framework-wrappers/react';

  Framework-specific wrappers are imported from sub-paths (e.g., `/vue`, `/react`). Directly importing from `q2-tecton-elements` would be using the raw web component without framework-specific bindings.

Quickstart

This quickstart demonstrates how to set up a basic Vue application using `q2-tecton-framework-wrappers` to integrate a Tecton button component, including registering custom elements and handling events.

import { defineCustomElements } from 'q2-tecton-elements/loader';
import { createApp } from 'vue';
import { TctButton } from 'q2-tecton-framework-wrappers/vue';

defineCustomElements();

const app = createApp({
  template: `
    <div>
      <h1>Q2 Tecton Integration</h1>
      <p>This example demonstrates integrating a Tecton button using Vue wrappers.</p>
      <TctButton @tctClick="handleClick" :disabled="isDisabled" ref="myButton">
        {{ buttonText }}
      </TctButton>
      <p>Button is currently {{ isDisabled ? 'disabled' : 'enabled' }}.</p>
      <button @click="toggleDisable">Toggle Button State</button>
    </div>
  `,
  components: {
    TctButton
  },
  data() {
    return {
      buttonText: 'Click Me!',
      isDisabled: false
    };
  },
  methods: {
    handleClick(event) {
      console.log('TctButton clicked!', event);
      alert('Tecton Button was clicked!');
    },
    toggleDisable() {
      this.isDisabled = !this.isDisabled;
      if (this.isDisabled) {
        this.buttonText = 'Disabled';
      } else {
        this.buttonText = 'Click Me!';
      }
    }
  },
  mounted() {
    console.log('TctButton instance:', this.$refs.myButton);
  }
});

app.mount('#app');