slash-dw/tagging-kit

SlashDw shared tagging infrastructure for Laravel projects (Spatie laravel-tags based, multi-tenant + multi-locale + config-driven)

v0.0.3 2026-05-29 20:23 UTC

Requires

• php: ^8.5
• illuminate/contracts: ^13.0
• illuminate/database: ^13.0
• illuminate/http: ^13.0
• illuminate/support: ^13.0
• slash-dw/core-kit: ^0.0.4
• slash-dw/idempotency-kit: ^0.0.2
• spatie/laravel-tags: ^4.0

Requires (Dev)

• larastan/larastan: ^3.9
• laravel/pint: ^1.29
• orchestra/testbench: ^11.0
• phpunit/phpunit: ^12.0

MIT

README

Generic tagging infrastructure for Laravel. Spatie laravel-tags based, multi-tenant + multi-locale + config-driven. Mixed system/user tag model.

Status

🚧 Active development — v0.0.x. Public API may change between minor versions. SemVer applies from v0.1.0.

This is a monorepo: the PHP backend lives at the root (Packagist: slash-dw/tagging-kit) and the React frontend in js/ (npm: @slash-dw/tagging-ui). See Frontend below.

Installation

composer require slash-dw/tagging-kit

Publish config (optional — defaults work out of the box):

php artisan vendor:publish --tag="tagging-kit-config"

Documentation

Detailed documentation is in progress. For now, see:

• config/tagging-kit.php — all configuration options with inline comments
• src/Contracts/ — public API interfaces (TagTypeContract, ActorContextContract, TenantContextContract, SharedTypesResolverContract)

Full README will be published with v0.1.0 (Faz 6).

Frontend — @slash-dw/tagging-ui

React/TypeScript companion in js/, published to npm as @slash-dw/tagging-ui. Headless <TagAutocomplete> + hooks (debounce, Fuse.js local-first, LRU cache, AbortController). Styling is host-owned via data-tagging-* attributes + className.

Install

npm install @slash-dw/tagging-ui
npm install react @tanstack/react-query   # peer deps

Bootstrap (once, at app entry)

import { configureTaggingUi, useTaggingBootstrap } from '@slash-dw/tagging-ui';

// Optional host overrides (win over backend /tagging/config defaults).
configureTaggingUi({
  baseUrl: '/api',                  // → {base}/tagging/{suggest,config,tags/:id}
  fetch: myCsrfAwareFetch,          // optional auth-aware fetch wrapper
  i18n: { placeholder: 'Etiket ekle…' },
  hooks: { onUserTagDeleted: (t) => analytics.track('tag_deleted', t) },
});

function TaggingBootstrap() {
  useTaggingBootstrap();            // GET /api/tagging/config → internal store
  return null;
}

Use the component

import { TagAutocomplete, type Tag } from '@slash-dw/tagging-ui';

function Form() {
  const [tags, setTags] = useState<Tag[]>([]);
  return <TagAutocomplete tagType={100} value={tags} onChange={setTags} />;
}

Public API

Kind	Exports
Components	TagAutocomplete, TagChip, TagSuggestionItem
Hooks	useTagAutocomplete, useTaggingBootstrap, useDeleteUserTag
Config	configureTaggingUi, getTaggingConfig
Low-level API	suggestTags, deleteUserTag, fetchTaggingConfig
Types	Tag, TagAutocompleteProps, TaggingConfig, TaggingDefaults, …

Config precedence (low → high): hardcoded → backend /tagging/config → configureTaggingUi → per-component prop.

Develop the frontend

cd js
npm install
npm run ci        # typecheck + vitest + vite build (ESM + CJS + d.ts)

Development (backend)

composer install
composer ci   # runs lint + analyse + test

Individual scripts:

• composer format — Pint auto-format
• composer lint — Pint check (no fix)
• composer analyse — PHPStan level 8 (no baseline)
• composer test — PHPUnit feature + unit + contract tests

License

MIT. See LICENSE.

Related packages

Part of the SlashDw kit ecosystem:

• slash-dw/core-kit — Repository + API response helpers
• slash-dw/error-kit — Exception handling
• slash-dw/filter-kit — Eloquent filter/sort DSL
• slash-dw/idempotency-kit — Per-route idempotency middleware
• slash-dw/tagging-kit — This package (PHP backend)
• @slash-dw/tagging-ui — React frontend companion (NPM)