feat: wrap Tagify field in nowo-tag-input custom element (#29)

Give the widget the same host API as other Nowo inputs without changing Tagify's light-DOM contract.

Author: HecFranco

docs/CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+### Changed
+
+- **Web Component:** the form theme now renders `<nowo-tag-input>` (light DOM). `tag-input.js` defines the custom element and still initializes fields with `data-controller="nowo-tag-input"`.
+
 
 ## [1.1.3] - 2026-08-24
 

docs/UPGRADING.md

@@ -2,8 +2,13 @@
 
 ## Table of contents
 
+- [Unreleased](#unreleased)
 - [From 1.1.2 to 1.1.3](#from-112-to-113)
 
+## Unreleased
+
+The default form theme now wraps the field in `<nowo-tag-input>`. Include the same `tag-input.js` / `tag-input.css` assets as before. Custom theme overrides that copied `tag_input_theme.html.twig` should switch the outer `<div>` to `<nowo-tag-input>` (legacy wrappers and `data-controller="nowo-tag-input"` fields still initialize).
+
 ## From 1.1.2 to 1.1.3
 
 Review the [CHANGELOG](CHANGELOG.md) entry. PHP **8.2+** may now be required.

docs/USAGE.md

@@ -83,6 +83,8 @@ php bin/console assets:install public
 <script src="{{ asset('tag-input.js', 'nowo_tag_input') }}"></script>
 ```
 
+The widget is `<nowo-tag-input>` (light DOM: native input wrapped by Tagify). Legacy `[data-nowo-tag-container="1"]` hosts still initialize.
+
 ## Customization
 
 - `value_format`: `array` (default) or `string`

src/Resources/assets/src/nowo-tag-input-element.test.ts

@@ -0,0 +1,35 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ensureNowoTagInputDefined } from './nowo-tag-input-element';
+import { TAG_NOWO_TAG_INPUT } from './tag-input-lib';
+
+describe('nowo-tag-input-element', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    document.body.innerHTML = '';
+  });
+
+  it('defines the custom element once', () => {
+    ensureNowoTagInputDefined();
+    const defined = customElements.get(TAG_NOWO_TAG_INPUT);
+    expect(defined).toBeDefined();
+    ensureNowoTagInputDefined();
+    expect(customElements.get(TAG_NOWO_TAG_INPUT)).toBe(defined);
+  });
+
+  it('initializes Tagify on connectedCallback', () => {
+    ensureNowoTagInputDefined();
+    const el = document.createElement(TAG_NOWO_TAG_INPUT);
+    el.innerHTML = '<input data-controller="nowo-tag-input" />';
+    document.body.appendChild(el);
+    const input = el.querySelector('input') as HTMLInputElement;
+    expect(input.dataset.nowoTagInputInitialized).toBe('1');
+    expect(el.style.display).toBe('block');
+  });
+
+  it('no-ops when customElements is unavailable', () => {
+    const original = globalThis.customElements;
+    Object.defineProperty(globalThis, 'customElements', { configurable: true, value: undefined });
+    expect(() => ensureNowoTagInputDefined()).not.toThrow();
+    Object.defineProperty(globalThis, 'customElements', { configurable: true, value: original });
+  });
+});

src/Resources/assets/src/nowo-tag-input-element.ts

@@ -0,0 +1,37 @@
+/**
+ * Autonomous custom element `<nowo-tag-input>` used by the default form theme.
+ */
+
+import { initTagContainer, TAG_NOWO_TAG_INPUT } from './tag-input-lib';
+
+export class NowoTagInputElement extends HTMLElement {
+  constructor() {
+    super();
+    if (!this.style.display) {
+      this.style.display = 'block';
+    }
+  }
+
+  connectedCallback(): void {
+    initTagContainer(this);
+  }
+}
+
+let definitionRequested = false;
+
+/**
+ * Defines {@link TAG_NOWO_TAG_INPUT} once. Safe to call multiple times.
+ */
+export function ensureNowoTagInputDefined(): void {
+  if (typeof customElements === 'undefined') {
+    return;
+  }
+  if (customElements.get(TAG_NOWO_TAG_INPUT) !== undefined) {
+    return;
+  }
+  if (definitionRequested) {
+    return;
+  }
+  definitionRequested = true;
+  customElements.define(TAG_NOWO_TAG_INPUT, NowoTagInputElement);
+}

src/Resources/assets/src/tag-input-lib.ts

@@ -0,0 +1,208 @@
+/**
+ * Tag input library shared by the custom element and the standalone IIFE.
+ * Initializes Tagify on Symfony form fields enhanced with data-nowo-tag-input attributes.
+ */
+
+import Tagify from '@yaireo/tagify';
+
+import { createBundleLogger } from './logger';
+import type { BundleLogger } from './logger';
+
+export const TAG_NOWO_TAG_INPUT = 'nowo-tag-input';
+export const HOST_SELECTOR = `${TAG_NOWO_TAG_INPUT}, [data-nowo-tag-container="1"]`;
+export const INPUT_SELECTOR =
+  'input[data-controller*="nowo-tag-input"], textarea[data-controller*="nowo-tag-input"]';
+
+export type TagifyInput = HTMLInputElement | HTMLTextAreaElement;
+
+export type TagifySettings = {
+  maxTags?: number;
+  whitelist?: string[];
+  pattern?: RegExp | null;
+  duplicates?: boolean;
+  dropdown?: {
+    enabled: boolean;
+    maxItems: number;
+    closeOnSelect: boolean;
+    highlightFirst: boolean;
+  };
+  placeholder?: string;
+};
+
+let bundleLogger: BundleLogger | null = null;
+
+/**
+ * @param logger - Bundle logger used by init helpers.
+ */
+export function setBundleLogger(logger: BundleLogger): void {
+  bundleLogger = logger;
+}
+
+/**
+ * @returns Active logger, or a silent fallback if the entry has not registered one.
+ */
+export function getLogger(): BundleLogger {
+  if (bundleLogger !== null) {
+    return bundleLogger;
+  }
+
+  return createBundleLogger('tag-input');
+}
+
+/**
+ * @param value - Attribute/dataset flag.
+ */
+export function toBool(value: string | undefined): boolean {
+  return value === '1' || value === 'true';
+}
+
+/**
+ * @param raw - JSON array of allowed tags.
+ */
+export function parseWhitelist(raw: string | undefined): string[] | undefined {
+  if (!raw) {
+    return undefined;
+  }
+
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) {
+      return undefined;
+    }
+
+    return parsed.filter((item): item is string => typeof item === 'string');
+  } catch {
+    getLogger().warn('invalid whitelist JSON', { raw });
+    return undefined;
+  }
+}
+
+/**
+ * @param raw - Regex source without delimiters.
+ */
+export function parsePattern(raw: string | undefined): RegExp | null {
+  if (!raw) {
+    return null;
+  }
+
+  try {
+    return new RegExp(raw);
+  } catch {
+    getLogger().warn('invalid pattern regex', { raw });
+    return null;
+  }
+}
+
+/**
+ * @param input - Native field Tagify wraps.
+ */
+export function buildSettings(input: TagifyInput): TagifySettings {
+  const dataset = input.dataset;
+  const maxTagsRaw = dataset.nowoTagInputMaxTagsValue;
+  const settings: TagifySettings = {
+    duplicates: toBool(dataset.nowoTagInputDuplicatesValue),
+    dropdown: {
+      enabled: toBool(dataset.nowoTagInputDropdownEnabledValue),
+      maxItems: 20,
+      closeOnSelect: true,
+      highlightFirst: true,
+    },
+  };
+
+  if (maxTagsRaw !== undefined && maxTagsRaw !== '') {
+    const maxTags = Number.parseInt(maxTagsRaw, 10);
+    if (!Number.isNaN(maxTags) && maxTags > 0) {
+      settings.maxTags = maxTags;
+    }
+  }
+
+  const whitelist = parseWhitelist(dataset.nowoTagInputWhitelistValue);
+  if (whitelist !== undefined && whitelist.length > 0) {
+    settings.whitelist = whitelist;
+  }
+
+  const pattern = parsePattern(dataset.nowoTagInputPatternValue);
+  if (pattern !== null) {
+    settings.pattern = pattern;
+  }
+
+  const placeholder = dataset.nowoTagInputPlaceholderValue;
+  if (placeholder !== undefined && placeholder !== '') {
+    settings.placeholder = placeholder;
+  }
+
+  return settings;
+}
+
+/**
+ * @param input - Native field to enhance.
+ */
+export function initTagInput(input: TagifyInput): void {
+  if (input.dataset.nowoTagInputInitialized === '1') {
+    return;
+  }
+
+  const settings = buildSettings(input);
+  // Tagify mutates the input in place; the instance is owned by the host element.
+  new Tagify(input, settings);
+  input.dataset.nowoTagInputInitialized = '1';
+}
+
+/**
+ * Initialize Tagify on a host custom element or legacy wrapper.
+ *
+ * @param host - `<nowo-tag-input>` or `[data-nowo-tag-container]`.
+ */
+export function initTagContainer(host: HTMLElement): void {
+  const input = host.querySelector<TagifyInput>(INPUT_SELECTOR);
+  if (input) {
+    initTagInput(input);
+  }
+}
+
+/**
+ * Discover and initialize every tag field currently in the document.
+ */
+export function initAllTagInputs(): void {
+  const inputs = Array.from(document.querySelectorAll<TagifyInput>(INPUT_SELECTOR));
+  getLogger().info('initializing tag inputs', { count: inputs.length });
+  inputs.forEach(initTagInput);
+}
+
+let observer: MutationObserver | null = null;
+
+/**
+ * Initialize existing hosts and watch for nodes added later (Turbo / live forms).
+ */
+export function runInitAndObserve(): void {
+  initAllTagInputs();
+  if (observer !== null || typeof MutationObserver === 'undefined' || document.body === null) {
+    return;
+  }
+
+  observer = new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      mutation.addedNodes.forEach((node) => {
+        if (!(node instanceof HTMLElement)) {
+          return;
+        }
+        if (node.matches(HOST_SELECTOR)) {
+          initTagContainer(node);
+        } else if (node.matches(INPUT_SELECTOR)) {
+          initTagInput(node as TagifyInput);
+        }
+        node.querySelectorAll<HTMLElement>(HOST_SELECTOR).forEach(initTagContainer);
+        node.querySelectorAll<TagifyInput>(INPUT_SELECTOR).forEach(initTagInput);
+      });
+    }
+  });
+  observer.observe(document.body, { childList: true, subtree: true });
+}
+
+/**
+ * Disconnect the document observer. Used by tests when resetting modules.
+ */
+export function stopObserving(): void {
+  observer?.disconnect();
+  observer = null;
+}

src/Resources/assets/src/tag-input.css

@@ -1,7 +1,10 @@
+nowo-tag-input,
 .nowo-tag-input {
+  display: block;
   width: 100%;
 }
 
+nowo-tag-input .tagify,
 .nowo-tag-input .tagify {
   width: 100%;
 }

src/Resources/assets/src/tag-input.test.ts

@@ -8,7 +8,9 @@ function setReadyState(value: DocumentReadyState): void {
 }
 
 describe('tag-input entrypoint', () => {
-  beforeEach(() => {
+  beforeEach(async () => {
+    const { stopObserving } = await import('./tag-input-lib');
+    stopObserving();
     vi.resetModules();
     document.body.innerHTML = '';
     setReadyState('complete');