Builder (M2A) Button Matrix for Directus

This interface extension replaces Directus' default Many-to-Any (M2A) builder dropdown with a fast, visual grid that makes large collections easy to scan. Users can open a modal, search, filter by category or tag, and trigger the original builder actions with keyboard shortcuts or mouse clicks.

Highlights

• Transforms the M2A builder into a responsive grid with collection banners, icons, and labels.
• Supports optional search, category, and tag chips so editors can zero in on the right content type.
• Mirrors the built-in builder actions, so you keep existing permissions, relations, and behaviors.
• Keyboard-friendly: arrow keys, Home/End, and Enter continue to work for power users.
• Written with the Directus Extensions SDK, Vue 3, and VueUse utilities for a lightweight footprint.

Requirements

• Directus ^11.8.0 (the interface hooks into the builder introduced in 11.8).
• Node.js >=18 (matches the Directus SDK toolchain) and npm.
• Access to your Directus project files so you can place the compiled interface under extensions/interfaces.

Installation

1. Install dependencies

   npm install

2. Build the extension

   npm run build

   This emits dist/index.js, the entry point declared in package.json.
3. Copy or link the interface into Directus
   • Copy the dist folder (or the entire repository) into <directus-root>/extensions/interfaces/m2a-button-matrix, or
   • Run npm run link to symlink the extension into a locally running Directus instance via the Extensions SDK helper.
4. Restart Directus so it discovers the new interface.

Tip: npm run dev rebuilds the extension in watch mode and is ideal when paired with npm run link during active development.

Usage inside Directus

1. Open Settings → Data Model and edit the collection that contains your existing M2A field.
2. Add a new field (alias or presentation) where you want the matrix to render.
3. Choose Builder (M2A) Button Matrix as the interface.
4. Configure the options below, then place the field directly above or below the real M2A builder as indicated by the notice rendered by the interface.

Configuration Options

| Option | Type | Description | | --- | --- | --- | | Target Builder (M2A) field placement | Select (above or below) | Where the original builder sits relative to this presentation field. Determines which sibling DOM node the extension hijacks. | Enable Search | Boolean | Turns on the search input inside the modal. | Search Placeholder | String | Placeholder text for the search bar (only visible when search is enabled). | Category Collection | Collection picker | Optional collection containing category terms. | Category Relation Field | String | Field name (in the allowed collections) that stores the category relation. Used to auto-tag the grid cards. | Tag Collection | Collection picker | Optional collection containing tag terms. | Tag Relation Field | String | Field name in the allowed collections that stores tag relations.

Filters & Keyboard Controls

• Search: Type to instantly filter the cards by their label.
• Category/Tag chips: Click chips to toggle filters; the modal shows active filters above the grid.
• Clear filters: Use the Clear all button to reset search, categories, and tags.
• Arrow keys: Navigate between cards.
• Home / End: Jump to the first or last card.
• Enter / Space: Activate the focused card, triggering the original builder action.

Development Workflow

• npm run dev – watch mode build with readable output; pair with npm run link for hot iterations.
• npm run build – production build with minified output.
• npm run link – symlink the extension into a Directus project (requires the DIRECTUS_ENV variables expected by the Extensions SDK).
• npm run validate – run the Directus validator to ensure the manifest, bundle, and metadata are correct before shipping.

Project Structure

src/
  index.ts        # Registers the interface, exposes builder options, and metadata.
  interface.vue   # Vue 3 component implementing the matrix UI, modal, filters, and keyboard UX.
tsconfig.json     # TypeScript settings used by the Extensions SDK build.

Releasing

1. Update version in package.json according to semver.
2. Run npm run build.
3. Publish the package or distribute the dist folder to customers or internal projects.

Publishing to npm

1. Tag & commit – ensure the version bump and build artifacts are committed and pushed (git tag vX.Y.Z && git push --tags).
2. Authenticate – run npm login (or npm login --scope @veribir for scoped publishing) with an account that has publish rights; complete the 2FA prompt if required.
3. Verify access level – this package is scoped and should stay public, so use npm publish --access public unless your org mandates otherwise.
4. Publish – execute npm publish --workspace . (or run from this folder) after confirming dist/ contains the latest build.
5. Post-publish checks – confirm the new version appears on npmjs.com, then update downstream Directus projects or internal registries.

License

Proprietary © Veribir. All rights reserved.