strapi-plugin-tags-custom-field 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rony Freitas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# strapi-plugin-tags-custom-field
+
+Strapi 5 plugin that adds a `tags` custom field to edit a list of tags (`array of strings`) and store it as a native JSON array.
+
+## What this plugin does
+
+- Registers the `tags` custom field on the server (`type: json`).
+- Registers the custom field in the admin panel with a tags input component.
+- Saves tags as JSON array values (e.g. `["news","featured","tech"]`).
+- Uses Strapi Design System components for native admin look and feel.
+- Supports keyboard and clipboard workflows for faster data entry.
+
+## Requirements
+
+- Node.js 18+ (recommended: Node.js 20)
+- Strapi 5
+
+## Local plugin development
+
+```bash
+npm install
+npm run build
+npm run test:ts
+npm run verify
+```
+
+## Install from npm (recommended)
+
+```bash
+npm install strapi-plugin-tags-custom-field
+```
+
+Then restart your Strapi server and add the field in Content-Type Builder:
+
+- Add a new field.
+- Open the Custom fields category.
+- Select `Tags`.
+- Configure the custom field options if needed (see below).
+
+## Link locally during development
+
+1. In the plugin project:
+
+```bash
+npm install
+npm run watch:link
+```
+
+2. In the Strapi project (in another terminal):
+
+```bash
+npx yalc add --link strapi-plugin-tags-custom-field
+npm install
+npm run develop
+```
+
+3. In the Strapi Content-Type Builder, add the `Tags` custom field.
+
+## Input behavior and UX
+
+- Press `Enter` to add the current tag.
+- Press the configured separator (default: `,`) to add the current tag.
+- Paste multiple tags at once (separated by newline or the configured separator).
+- Press `Backspace` on an empty input to remove the last tag.
+- Each draft tag has a configurable character limit with a live counter in the UI.
+
+## Custom field options (Content-Type Builder)
+
+- `maxTags` (number, default: `20`): maximum number of tags allowed.
+- `maxTagLength` (number, default: `40`): maximum number of characters per tag.
+- `allowDuplicates` (boolean, default: `false`): allows repeated tags.
+- `separator` (text, default: `,`): character used for splitting input/paste.
+- `normalizeCase` (select, default: `none`): `none`, `lowercase`, or `UPPERCASE`.
+
+## Database value format
+
+The value is stored as a native JSON array. Examples:
+
+- No tags: `[]`
+- With tags: `["javascript","strapi","cms"]`
+
+## Main structure
+
+- `server/src/register.ts`: backend custom field registration.
+- `admin/src/index.ts`: admin custom field registration.
+- `admin/src/components/TagsInput.tsx`: visual input with add/remove tag behavior.
+
+## Release checklist
+
+1. Update version in `package.json`.
+2. Run:
+
+```bash
+npm ci
+npm run release:check
+```
+
+3. Publish to npm:
+
+```bash
+npm publish
+```
+

package/dist/admin/TagsInput-BGUydL2t.js

@@ -0,0 +1,354 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const jsxRuntime = require("react/jsx-runtime");
+const React = require("react");
+const designSystem = require("@strapi/design-system");
+const icons = require("@strapi/icons");
+const reactIntl = require("react-intl");
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  const n = Object.create(null, { [Symbol.toStringTag]: { value: "Module" } });
+  if (e) {
+    for (const k in e) {
+      if (k !== "default") {
+        const d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: () => e[k]
+        });
+      }
+    }
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+const React__namespace = /* @__PURE__ */ _interopNamespace(React);
+const DEFAULT_SEPARATOR = ",";
+const DEFAULT_MAX_TAGS = 20;
+const DEFAULT_MAX_TAG_LENGTH = 40;
+const parseTagsValue = (value) => {
+  if (Array.isArray(value)) {
+    return value.map((item) => String(item).trim()).filter((item) => item.length > 0);
+  }
+  if (typeof value !== "string") {
+    return [];
+  }
+  const normalized = value.trim();
+  if (!normalized) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(normalized);
+    if (Array.isArray(parsed)) {
+      return parsed.map((item) => String(item).trim()).filter((item) => item.length > 0);
+    }
+  } catch {
+  }
+  return [normalized];
+};
+const serializeTagsValue = (tags) => tags;
+const normalizeCaseValue = (rawValue) => {
+  if (rawValue === "lowercase" || rawValue === "uppercase") {
+    return rawValue;
+  }
+  return "none";
+};
+const normalizeTag = (value, normalizeCase) => {
+  const cleanedValue = value.trim();
+  if (!cleanedValue) {
+    return "";
+  }
+  if (normalizeCase === "lowercase") {
+    return cleanedValue.toLowerCase();
+  }
+  if (normalizeCase === "uppercase") {
+    return cleanedValue.toUpperCase();
+  }
+  return cleanedValue;
+};
+const parseBoolean = (value, defaultValue = false) => {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "string") {
+    return value.toLowerCase() === "true";
+  }
+  return defaultValue;
+};
+const parsePositiveInt = (value, fallbackValue) => {
+  const parsedValue = Number(value);
+  if (Number.isFinite(parsedValue) && parsedValue > 0) {
+    return Math.floor(parsedValue);
+  }
+  return fallbackValue;
+};
+const getSplitRegex = (separator) => {
+  const characters = Array.from(/* @__PURE__ */ new Set([separator, "\n", "\r"])).filter(
+    (character) => character.length > 0
+  );
+  const escapedCharacters = characters.map((character) => character.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("");
+  return new RegExp(`[${escapedCharacters}]+`);
+};
+const parseRawTags = (rawValue, separator, normalizeCase) => rawValue.split(getSplitRegex(separator)).map((tag) => normalizeTag(tag, normalizeCase)).filter((tag) => tag.length > 0);
+const hasSplitCharacters = (value, separator) => [separator, "\n", "\r"].some(
+  (character) => character.length > 0 && value.includes(character)
+);
+const TagsInput = React__namespace.forwardRef(
+  ({
+    attribute,
+    disabled = false,
+    error,
+    hint,
+    intlLabel,
+    name,
+    onChange,
+    placeholder,
+    required = false,
+    value
+  }, ref) => {
+    const { formatMessage } = reactIntl.useIntl();
+    const [tags, setTags] = React__namespace.useState(() => parseTagsValue(value));
+    const [draft, setDraft] = React__namespace.useState("");
+    const [localError, setLocalError] = React__namespace.useState();
+    React__namespace.useEffect(() => {
+      setTags(parseTagsValue(value));
+    }, [value]);
+    const fieldType = attribute?.type ?? "json";
+    const options = attribute?.options ?? {};
+    const separator = typeof options.separator === "string" && options.separator.trim().length > 0 ? options.separator.trim().charAt(0) : DEFAULT_SEPARATOR;
+    const maxTags = parsePositiveInt(options.maxTags, DEFAULT_MAX_TAGS);
+    const maxTagLength = parsePositiveInt(
+      options.maxTagLength,
+      DEFAULT_MAX_TAG_LENGTH
+    );
+    const allowDuplicates = parseBoolean(options.allowDuplicates, false);
+    const normalizeCase = normalizeCaseValue(options.normalizeCase);
+    const label = intlLabel?.id || intlLabel?.defaultMessage ? formatMessage({
+      id: intlLabel?.id ?? `${name}.label`,
+      defaultMessage: intlLabel?.defaultMessage ?? "Tags"
+    }) : "Tags";
+    const hintMessage = hint ?? formatMessage({
+      id: "tags-input.hint",
+      defaultMessage: "Press Enter or type the separator to add tags. Paste multiple tags at once."
+    });
+    const shownError = error || localError;
+    const emitChange = React__namespace.useCallback(
+      (nextTags) => {
+        onChange({
+          target: {
+            name,
+            type: fieldType,
+            value: serializeTagsValue(nextTags)
+          }
+        });
+      },
+      [fieldType, name, onChange]
+    );
+    const addTags = React__namespace.useCallback(
+      (rawTags) => {
+        if (rawTags.length === 0) {
+          return false;
+        }
+        let didChange = false;
+        setTags((currentTags) => {
+          const nextTags = [...currentTags];
+          for (const rawTag of rawTags) {
+            if (nextTags.length >= maxTags) {
+              setLocalError(
+                formatMessage(
+                  {
+                    id: "tags-input.error.max-tags",
+                    defaultMessage: "You can only add up to {maxTags} tags."
+                  },
+                  { maxTags }
+                )
+              );
+              break;
+            }
+            if (rawTag.length > maxTagLength) {
+              setLocalError(
+                formatMessage(
+                  {
+                    id: "tags-input.error.max-length",
+                    defaultMessage: "Each tag must be at most {maxLength} characters."
+                  },
+                  { maxLength: maxTagLength }
+                )
+              );
+              continue;
+            }
+            const duplicateIndex = nextTags.findIndex(
+              (tag) => tag.toLowerCase() === rawTag.toLowerCase()
+            );
+            if (duplicateIndex !== -1 && !allowDuplicates) {
+              setLocalError(
+                formatMessage({
+                  id: "tags-input.error.duplicate",
+                  defaultMessage: "Duplicate tags are not allowed."
+                })
+              );
+              continue;
+            }
+            nextTags.push(rawTag);
+            didChange = true;
+          }
+          if (didChange) {
+            setLocalError(void 0);
+            emitChange(nextTags);
+          }
+          return didChange ? nextTags : currentTags;
+        });
+        return didChange;
+      },
+      [allowDuplicates, emitChange, formatMessage, maxTagLength, maxTags]
+    );
+    const commitDraft = React__namespace.useCallback(() => {
+      const parsedTags = parseRawTags(draft, separator, normalizeCase);
+      const added = addTags(parsedTags);
+      if (added) {
+        setDraft("");
+      }
+    }, [addTags, draft, normalizeCase, separator]);
+    const removeTag = React__namespace.useCallback(
+      (index) => {
+        setTags((currentTags) => {
+          const nextTags = currentTags.filter((_, currentIndex) => currentIndex !== index);
+          emitChange(nextTags);
+          return nextTags;
+        });
+      },
+      [emitChange]
+    );
+    const removeLastTag = React__namespace.useCallback(() => {
+      setTags((currentTags) => {
+        if (currentTags.length === 0) {
+          return currentTags;
+        }
+        const nextTags = currentTags.slice(0, currentTags.length - 1);
+        emitChange(nextTags);
+        setLocalError(void 0);
+        return nextTags;
+      });
+    }, [emitChange]);
+    const onKeyDown = (event) => {
+      if (event.key === "Enter" || event.key === separator) {
+        event.preventDefault();
+        commitDraft();
+      }
+      if (event.key === "Backspace" && draft.length === 0 && !disabled) {
+        event.preventDefault();
+        removeLastTag();
+      }
+    };
+    const onPaste = (event) => {
+      const pastedText = event.clipboardData.getData("text");
+      if (!pastedText || !hasSplitCharacters(pastedText, separator)) {
+        return;
+      }
+      event.preventDefault();
+      const parsedTags = parseRawTags(pastedText, separator, normalizeCase);
+      addTags(parsedTags);
+    };
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      designSystem.Field.Root,
+      {
+        id: name,
+        name,
+        required,
+        hint: hintMessage,
+        error: shownError,
+        children: /* @__PURE__ */ jsxRuntime.jsxs(designSystem.Flex, { direction: "column", alignItems: "stretch", gap: 2, children: [
+          /* @__PURE__ */ jsxRuntime.jsx(designSystem.Field.Label, { children: label }),
+          tags.length > 0 ? /* @__PURE__ */ jsxRuntime.jsx(
+            designSystem.Box,
+            {
+              borderColor: "neutral150",
+              borderStyle: "solid",
+              borderWidth: "1px",
+              borderRadius: "4px",
+              padding: 2,
+              background: "neutral0",
+              children: /* @__PURE__ */ jsxRuntime.jsx(designSystem.Flex, { wrap: "wrap", gap: 2, children: tags.map((tag, index) => /* @__PURE__ */ jsxRuntime.jsx(
+                designSystem.Tag,
+                {
+                  icon: /* @__PURE__ */ jsxRuntime.jsx(icons.Cross, {}),
+                  disabled,
+                  onClick: !disabled ? () => removeTag(index) : void 0,
+                  label: `Remove ${tag}`,
+                  children: tag
+                },
+                `${tag}-${index}`
+              )) })
+            }
+          ) : null,
+          /* @__PURE__ */ jsxRuntime.jsx(
+            designSystem.TextInput,
+            {
+              id: name,
+              ref,
+              disabled,
+              required: required && tags.length === 0,
+              value: draft,
+              onChange: (event) => {
+                const nextDraft = event.currentTarget.value;
+                if (nextDraft.length <= maxTagLength) {
+                  setDraft(nextDraft);
+                  if (localError) {
+                    setLocalError(void 0);
+                  }
+                } else {
+                  setLocalError(
+                    formatMessage(
+                      {
+                        id: "tags-input.error.max-length",
+                        defaultMessage: "Each tag must be at most {maxLength} characters."
+                      },
+                      { maxLength: maxTagLength }
+                    )
+                  );
+                }
+              },
+              onBlur: commitDraft,
+              onKeyDown,
+              onPaste,
+              placeholder: placeholder ?? formatMessage(
+                {
+                  id: "tags-input.placeholder",
+                  defaultMessage: "Type a tag and press Enter or {separator} to add it"
+                },
+                { separator }
+              )
+            }
+          ),
+          /* @__PURE__ */ jsxRuntime.jsxs(designSystem.Flex, { justifyContent: "space-between", gap: 2, children: [
+            /* @__PURE__ */ jsxRuntime.jsx(designSystem.Typography, { variant: "pi", textColor: "neutral600", children: formatMessage(
+              {
+                id: "tags-input.counter.tags",
+                defaultMessage: "{count}/{maxTags} tags"
+              },
+              { count: tags.length, maxTags }
+            ) }),
+            /* @__PURE__ */ jsxRuntime.jsx(
+              designSystem.Typography,
+              {
+                variant: "pi",
+                textColor: draft.length >= maxTagLength ? "danger600" : "neutral600",
+                children: formatMessage(
+                  {
+                    id: "tags-input.counter.characters",
+                    defaultMessage: "{count}/{maxLength} characters"
+                  },
+                  { count: draft.length, maxLength: maxTagLength }
+                )
+              }
+            )
+          ] }),
+          /* @__PURE__ */ jsxRuntime.jsx(designSystem.Field.Hint, {}),
+          /* @__PURE__ */ jsxRuntime.jsx(designSystem.Field.Error, {})
+        ] })
+      }
+    );
+  }
+);
+TagsInput.displayName = "TagsInput";
+exports.TagsInput = TagsInput;