@quatrain/ux-taxonomy 1.0.1

package/dist/ThematicTree.js

@@ -0,0 +1,100 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ThematicTree = void 0;
+const react_1 = __importStar(require("react"));
+const core_1 = require("@mantine/core");
+const icons_react_1 = require("@tabler/icons-react");
+const TreeNodeItem = ({ node, level, controller, selectedIds, searchQuery, onSelect, onAddSubThematic }) => {
+    const hasChildren = Boolean(node.children && node.children.length > 0);
+    const isExpanded = controller.isExpanded(node.id) || Boolean(searchQuery.trim());
+    const isSelected = selectedIds.includes(node.id);
+    const matchesSearch = (0, react_1.useMemo)(() => {
+        if (!searchQuery.trim())
+            return true;
+        const q = searchQuery.toLowerCase();
+        const matchSelf = node.label.toLowerCase().includes(q) || (node.description && node.description.toLowerCase().includes(q));
+        return matchSelf;
+    }, [node, searchQuery]);
+    if (!matchesSearch && !hasChildren) {
+        return null;
+    }
+    return (react_1.default.createElement(core_1.Box, { style: { marginLeft: level * 14 } },
+        react_1.default.createElement(core_1.Group, { justify: "space-between", wrap: "nowrap", p: 6, style: {
+                borderRadius: 6,
+                backgroundColor: isSelected ? 'var(--mantine-color-blue-light)' : 'transparent',
+                cursor: 'pointer',
+                transition: 'background-color 150ms ease'
+            }, onClick: () => {
+                controller.select(node.id);
+                if (onSelect)
+                    onSelect(node);
+            } },
+            react_1.default.createElement(core_1.Group, { gap: "xs", wrap: "nowrap", style: { flex: 1, minWidth: 0 } },
+                hasChildren ? (react_1.default.createElement(core_1.ActionIcon, { size: "xs", variant: "subtle", color: "gray", onClick: (e) => {
+                        e.stopPropagation();
+                        controller.toggleExpand(node.id);
+                    }, "aria-label": isExpanded ? 'Collapse' : 'Expand' }, isExpanded ? react_1.default.createElement(icons_react_1.IconChevronDown, { size: 14 }) : react_1.default.createElement(icons_react_1.IconChevronRight, { size: 14 }))) : (react_1.default.createElement(core_1.Box, { style: { width: 18 } })),
+                hasChildren ? (isExpanded ? react_1.default.createElement(icons_react_1.IconFolderOpen, { size: 16, color: "var(--mantine-color-blue-filled)" }) : react_1.default.createElement(icons_react_1.IconFolder, { size: 16, color: "gray" })) : (react_1.default.createElement(icons_react_1.IconFolder, { size: 16, color: "gray" })),
+                react_1.default.createElement(core_1.Text, { size: "sm", fw: isSelected ? 600 : 400, truncate: true, style: { flex: 1 } }, node.label)),
+            react_1.default.createElement(core_1.Group, { gap: 4, wrap: "nowrap" },
+                node.count !== undefined && (react_1.default.createElement(core_1.Badge, { size: "xs", variant: isSelected ? 'filled' : 'light', color: node.color || 'blue' }, node.count)),
+                onAddSubThematic && (react_1.default.createElement(core_1.Tooltip, { label: "Ajouter une sous-th\u00E9matique", withArrow: true, position: "right" },
+                    react_1.default.createElement(core_1.ActionIcon, { size: "xs", variant: "subtle", color: "gray", onClick: (e) => {
+                            e.stopPropagation();
+                            onAddSubThematic(node);
+                        }, "aria-label": "Add sub-thematic" },
+                        react_1.default.createElement(icons_react_1.IconPlus, { size: 12 })))))),
+        hasChildren && (react_1.default.createElement(core_1.Collapse, { in: isExpanded },
+            react_1.default.createElement(core_1.Stack, { gap: 2, mt: 2 }, node.children.map((child) => (react_1.default.createElement(TreeNodeItem, { key: child.id, node: child, level: level + 1, controller: controller, selectedIds: selectedIds, searchQuery: searchQuery, onSelect: onSelect, onAddSubThematic: onAddSubThematic }))))))));
+};
+/**
+ * Tree component rendering interactive taxonomic hierarchies with Mantine styling.
+ */
+const ThematicTree = ({ controller, onSelect, onAddSubThematic, searchable = true, className = '', style }) => {
+    const [tree, setTree] = (0, react_1.useState)(controller.getTree());
+    const [selectedIds, setSelectedIds] = (0, react_1.useState)(controller.getSelected());
+    const [searchQuery, setSearchQuery] = (0, react_1.useState)('');
+    (0, react_1.useEffect)(() => {
+        return controller.subscribe((updatedTree, updatedSelected) => {
+            setTree(updatedTree);
+            setSelectedIds(updatedSelected);
+        });
+    }, [controller]);
+    return (react_1.default.createElement(core_1.Box, { className: `q-thematic-tree ${className}`, style: style },
+        searchable && (react_1.default.createElement(core_1.TextInput, { placeholder: "Filtrer les th\u00E9matiques...", size: "xs", mb: "xs", leftSection: react_1.default.createElement(icons_react_1.IconSearch, { size: 14 }), value: searchQuery, onChange: (e) => setSearchQuery(e.currentTarget.value) })),
+        react_1.default.createElement(core_1.Stack, { gap: 2 }, tree.length === 0 ? (react_1.default.createElement(core_1.Text, { size: "sm", c: "dimmed", fs: "italic", p: "xs" }, "Aucune th\u00E9matique d\u00E9finie.")) : (tree.map((node) => (react_1.default.createElement(TreeNodeItem, { key: node.id, node: node, level: 0, controller: controller, selectedIds: selectedIds, searchQuery: searchQuery, onSelect: onSelect, onAddSubThematic: onAddSubThematic })))))));
+};
+exports.ThematicTree = ThematicTree;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './TaxonomyController';
+export * from './ThematicTree';
+export * from './ThematicBadgeGroup';

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./TaxonomyController"), exports);
+__exportStar(require("./ThematicTree"), exports);
+__exportStar(require("./ThematicBadgeGroup"), exports);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@quatrain/ux-taxonomy",
+  "version": "1.0.1",
+  "description": "Headless taxonomy and thematic hierarchy controller with React Mantine components",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bun": "src/index.ts",
+  "license": "AGPL-3.0-only",
+  "files": [
+    "LICENSE.md",
+    "dist/",
+    "src/",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "dependencies": {
+    "@mantine/core": "^7.10.0",
+    "@mantine/hooks": "^7.10.0",
+    "@quatrain/types": "^1.2.18",
+    "@tabler/icons-react": "^3.5.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "jest": "^29.7.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.2.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "wbuild": "tsc --watch",
+    "test": "jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Quatrain/CoreUX.git",
+    "directory": "packages/ux-taxonomy"
+  }
+}

package/src/TaxonomyController.test.ts

@@ -0,0 +1,151 @@
+import { TaxonomyController, TaxonomyNode } from './TaxonomyController'
+
+describe('TaxonomyController', () => {
+  const sampleNodes: TaxonomyNode[] = [
+    {
+      id: 'soil-health',
+      label: 'Soil Health & Biology',
+      description: 'Soil microbiology and structure',
+      children: [
+        {
+          id: 'mycorrhizae',
+          label: 'Mycorrhizae & Fungi',
+          description: 'Symbiotic fungal networks'
+        }
+      ]
+    },
+    {
+      id: 'cover-crops',
+      label: 'Cover Crops & Mulching',
+      description: 'Biomass and species selection'
+    }
+  ]
+
+  it('initializes correctly with provided nodes and active selection', () => {
+    const controller = new TaxonomyController({
+      initialNodes: sampleNodes,
+      selectedId: 'soil-health'
+    })
+
+    const tree = controller.getTree()
+    expect(tree).toHaveLength(2)
+    expect(tree[0].id).toBe('soil-health')
+    expect(tree[0].children).toHaveLength(1)
+    expect(tree[0].children![0].id).toBe('mycorrhizae')
+    expect(controller.getSelected()).toEqual(['soil-health'])
+    expect(controller.isSelected('soil-health')).toBe(true)
+    expect(controller.isSelected('cover-crops')).toBe(false)
+  })
+
+  it('handles single selection mode correctly', () => {
+    const controller = new TaxonomyController({ initialNodes: sampleNodes })
+    controller.select('soil-health')
+    expect(controller.getSelected()).toEqual(['soil-health'])
+
+    controller.select('cover-crops')
+    expect(controller.getSelected()).toEqual(['cover-crops'])
+  })
+
+  it('handles multi-selection mode when configured', () => {
+    const controller = new TaxonomyController({
+      initialNodes: sampleNodes,
+      multiSelect: true
+    })
+
+    controller.select('soil-health')
+    controller.select('cover-crops')
+    expect(controller.getSelected()).toEqual(['soil-health', 'cover-crops'])
+
+    controller.deselect('soil-health')
+    expect(controller.getSelected()).toEqual(['cover-crops'])
+
+    controller.toggleSelect('mycorrhizae')
+    expect(controller.getSelected()).toEqual(['cover-crops', 'mycorrhizae'])
+    controller.toggleSelect('cover-crops')
+    expect(controller.getSelected()).toEqual(['mycorrhizae'])
+  })
+
+  it('adds and removes nodes with cascade deletion', () => {
+    const controller = new TaxonomyController({ initialNodes: sampleNodes })
+
+    controller.addNode({
+      id: 'irrigation',
+      label: 'Irrigation & Water',
+      parentId: null
+    })
+
+    expect(controller.getNode('irrigation')).toBeDefined()
+    expect(controller.getTree()).toHaveLength(3)
+
+    // Remove soil-health should also remove mycorrhizae
+    controller.removeNode('soil-health')
+    expect(controller.getNode('soil-health')).toBeUndefined()
+    expect(controller.getNode('mycorrhizae')).toBeUndefined()
+    expect(controller.getTree()).toHaveLength(2)
+  })
+
+  it('notifies subscribers upon state change', () => {
+    const controller = new TaxonomyController({ initialNodes: sampleNodes })
+    const listener = jest.fn()
+
+    const unsubscribe = controller.subscribe(listener)
+    expect(listener).toHaveBeenCalledTimes(1)
+
+    controller.select('cover-crops')
+    expect(listener).toHaveBeenCalledTimes(2)
+
+    controller.updateCount('cover-crops', 42)
+    expect(listener).toHaveBeenCalledTimes(3)
+    expect(controller.getNode('cover-crops')?.count).toBe(42)
+
+    unsubscribe()
+    controller.select('soil-health')
+    expect(listener).toHaveBeenCalledTimes(3)
+  })
+
+  it('manages expand and collapse state', () => {
+    const controller = new TaxonomyController({ initialNodes: sampleNodes })
+    expect(controller.isExpanded('soil-health')).toBe(false)
+
+    controller.toggleExpand('soil-health')
+    expect(controller.isExpanded('soil-health')).toBe(true)
+
+    controller.toggleExpand('soil-health')
+    expect(controller.isExpanded('soil-health')).toBe(false)
+  })
+
+  it('manages multi-axial facet filters and matches items', () => {
+    const controller = new TaxonomyController({ initialNodes: sampleNodes })
+
+    controller.setFacetFilter('soils', ['argilo-calcaire', 'limoneux'])
+    controller.setFacetFilter('climates', ['mediterraneen'])
+
+    expect(controller.getFacetFilter('soils')).toEqual(['argilo-calcaire', 'limoneux'])
+    expect(controller.getFacetFilter('climates')).toEqual(['mediterraneen'])
+    expect(controller.getAllFacetFilters()).toEqual({
+      soils: ['argilo-calcaire', 'limoneux'],
+      climates: ['mediterraneen']
+    })
+
+    const matchingDoc = {
+      category: 'soil-health',
+      thematics: ['soil-health'],
+      soils: ['argilo-calcaire'],
+      climates: ['mediterraneen', 'semi-aride']
+    }
+
+    const nonMatchingDoc = {
+      category: 'soil-health',
+      thematics: ['soil-health'],
+      soils: ['sableux'],
+      climates: ['mediterraneen']
+    }
+
+    expect(controller.matchesFilters(matchingDoc)).toBe(true)
+    expect(controller.matchesFilters(nonMatchingDoc)).toBe(false)
+
+    controller.clearFacetFilters()
+    expect(controller.getAllFacetFilters()).toEqual({})
+    expect(controller.matchesFilters(nonMatchingDoc)).toBe(true)
+  })
+})

package/src/TaxonomyController.ts

@@ -0,0 +1,373 @@
+/**
+ * Interface representing a node within a taxonomy or thematic hierarchy tree.
+ */
+export interface TaxonomyNode {
+  /** Unique slug identifier for the thematic node (e.g., 'soil-health') */
+  id: string
+  /** Human-readable label displayed in the UI */
+  label: string
+  /** Short description explaining the thematic domain */
+  description?: string
+  /** Parent thematic identifier, or null for root-level categories */
+  parentId?: string | null
+  /** Optional icon identifier from Tabler Icons or UI icon registry */
+  icon?: string
+  /** Accent color token or hex string */
+  color?: string
+  /** Number of curated documents associated with this thematic */
+  count?: number
+  /** Child thematic nodes */
+  children?: TaxonomyNode[]
+  /** Arbitrary domain metadata */
+  metadata?: Record<string, any>
+}
+
+/**
+ * Configuration options for initializing a TaxonomyController instance.
+ */
+export interface TaxonomyControllerOptions {
+  /** Initial tree or flat list of taxonomy nodes */
+  initialNodes?: TaxonomyNode[]
+  /** Initially selected thematic identifier */
+  selectedId?: string | null
+  /** If true, allows multiple simultaneous thematic selections */
+  multiSelect?: boolean
+}
+
+export type TaxonomyListener = (nodes: TaxonomyNode[], selectedIds: string[]) => void
+
+/**
+ * Headless, framework-agnostic controller managing hierarchical thematics,
+ * category trees, transversal tag taxonomies, and active filter selections.
+ */
+export class TaxonomyController {
+  protected nodes: Map<string, TaxonomyNode> = new Map()
+  protected selectedIds: Set<string> = new Set()
+  protected expandedIds: Set<string> = new Set()
+  protected facetFilters: Map<string, Set<string>> = new Map()
+  protected listeners: Set<TaxonomyListener> = new Set()
+  protected multiSelect: boolean
+
+  /**
+   * Instantiates a new TaxonomyController.
+   * 
+   * @param options - Configuration options.
+   */
+  constructor(options: TaxonomyControllerOptions = {}) {
+    this.multiSelect = Boolean(options.multiSelect)
+    if (options.initialNodes && options.initialNodes.length > 0) {
+      this.loadNodes(options.initialNodes)
+    }
+    if (options.selectedId) {
+      this.selectedIds.add(options.selectedId)
+    }
+  }
+
+  /**
+   * Loads or replaces nodes in the taxonomy manager.
+   * 
+   * @param nodes - Array of hierarchical or flat taxonomy nodes.
+   */
+  public loadNodes(nodes: TaxonomyNode[]): void {
+    this.nodes.clear()
+    const flatten = (items: TaxonomyNode[], parentId: string | null = null) => {
+      for (const item of items) {
+        const node: TaxonomyNode = {
+          ...item,
+          parentId: item.parentId !== undefined ? item.parentId : parentId,
+          children: []
+        }
+        this.nodes.set(node.id, node)
+        if (item.children && item.children.length > 0) {
+          flatten(item.children, item.id)
+        }
+      }
+    }
+    flatten(nodes)
+    this.notify()
+  }
+
+  /**
+   * Adds or updates a thematic node in the taxonomy.
+   * 
+   * @param node - The thematic node to insert or update.
+   */
+  public addNode(node: TaxonomyNode): void {
+    this.nodes.set(node.id, {
+      ...node,
+      children: []
+    })
+    this.notify()
+  }
+
+  /**
+   * Removes a node and recursively removes its sub-thematics.
+   * 
+   * @param id - The identifier of the node to remove.
+   */
+  public removeNode(id: string): void {
+    const childrenToRemove: string[] = []
+    const findDescendants = (parentId: string) => {
+      for (const [nodeId, node] of this.nodes.entries()) {
+        if (node.parentId === parentId) {
+          childrenToRemove.push(nodeId)
+          findDescendants(nodeId)
+        }
+      }
+    }
+    findDescendants(id)
+    childrenToRemove.push(id)
+
+    for (const childId of childrenToRemove) {
+      this.nodes.delete(childId)
+      this.selectedIds.delete(childId)
+      this.expandedIds.delete(childId)
+    }
+    this.notify()
+  }
+
+  /**
+   * Selects a thematic node. Clears previous selection unless multiSelect is enabled.
+   * 
+   * @param id - The node identifier to select.
+   */
+  public select(id: string): void {
+    if (!this.multiSelect) {
+      this.selectedIds.clear()
+    }
+    this.selectedIds.add(id)
+    this.notify()
+  }
+
+  /**
+   * Deselects a thematic node.
+   * 
+   * @param id - The node identifier to deselect.
+   */
+  public deselect(id: string): void {
+    this.selectedIds.delete(id)
+    this.notify()
+  }
+
+  /**
+   * Toggles the selection status of a thematic node.
+   * 
+   * @param id - The node identifier to toggle.
+   */
+  public toggleSelect(id: string): void {
+    if (this.selectedIds.has(id)) {
+      this.deselect(id)
+    } else {
+      this.select(id)
+    }
+  }
+
+  /**
+   * Clears all active selections.
+   */
+  public clearSelection(): void {
+    this.selectedIds.clear()
+    this.notify()
+  }
+
+  /**
+   * Retrieves the set of currently selected thematic node identifiers.
+   * 
+   * @returns Array of selected IDs.
+   */
+  public getSelected(): string[] {
+    return Array.from(this.selectedIds)
+  }
+
+  /**
+   * Checks whether a specific thematic node is currently selected.
+   * 
+   * @param id - The thematic identifier to verify.
+   * @returns True if selected, false otherwise.
+   */
+  public isSelected(id: string): boolean {
+    return this.selectedIds.has(id)
+  }
+
+  /**
+   * Toggles the expansion collapse state of a parent thematic node.
+   * 
+   * @param id - The thematic identifier to toggle.
+   */
+  public toggleExpand(id: string): void {
+    if (this.expandedIds.has(id)) {
+      this.expandedIds.delete(id)
+    } else {
+      this.expandedIds.add(id)
+    }
+    this.notify()
+  }
+
+  /**
+   * Checks whether a thematic node is currently expanded.
+   * 
+   * @param id - The thematic identifier to check.
+   * @returns True if expanded, false otherwise.
+   */
+  public isExpanded(id: string): boolean {
+    return this.expandedIds.has(id)
+  }
+
+  /**
+   * Reconstructs and returns the full hierarchical taxonomy tree.
+   * 
+   * @returns Array of root-level TaxonomyNodes with nested children.
+   */
+  public getTree(): TaxonomyNode[] {
+    const rootNodes: TaxonomyNode[] = []
+    const nodeMap = new Map<string, TaxonomyNode>()
+
+    for (const [id, node] of this.nodes.entries()) {
+      nodeMap.set(id, { ...node, children: [] })
+    }
+
+    for (const node of nodeMap.values()) {
+      if (node.parentId && nodeMap.has(node.parentId)) {
+        const parent = nodeMap.get(node.parentId)!
+        parent.children = parent.children || []
+        parent.children.push(node)
+      } else {
+        rootNodes.push(node)
+      }
+    }
+
+    return rootNodes
+  }
+
+  /**
+   * Returns a flat array of all registered taxonomy nodes.
+   * 
+   * @returns Array of TaxonomyNode objects.
+   */
+  public getFlatNodes(): TaxonomyNode[] {
+    return Array.from(this.nodes.values())
+  }
+
+  /**
+   * Finds a specific thematic node by identifier.
+   * 
+   * @param id - The node identifier to locate.
+   * @returns The TaxonomyNode or undefined if not found.
+   */
+  public getNode(id: string): TaxonomyNode | undefined {
+    return this.nodes.get(id)
+  }
+
+  /**
+   * Updates the document counter for a thematic node.
+   * 
+   * @param id - The thematic identifier.
+   * @param count - The updated count.
+   */
+  public updateCount(id: string, count: number): void {
+    const existing = this.nodes.get(id)
+    if (existing) {
+      existing.count = count
+      this.notify()
+    }
+  }
+
+  /**
+   * Subscribes a listener callback to state changes.
+   * 
+   * @param listener - Callback receiving updated nodes and active selection.
+   * @returns Unsubscribe function.
+   */
+  public subscribe(listener: TaxonomyListener): () => void {
+    this.listeners.add(listener)
+    listener(this.getTree(), this.getSelected())
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  /**
+   * Sets or updates active filter values for a specific multi-axial facet axis (e.g., 'soils', 'climates').
+   * 
+   * @param axis - The facet axis identifier (e.g. 'soils', 'climates', 'itineraries').
+   * @param values - Array of selected facet values.
+   */
+  public setFacetFilter(axis: string, values: string[]): void {
+    if (!values || values.length === 0) {
+      this.facetFilters.delete(axis)
+    } else {
+      this.facetFilters.set(axis, new Set(values))
+    }
+    this.notify()
+  }
+
+  /**
+   * Retrieves active filter values for a specific facet axis.
+   * 
+   * @param axis - The facet axis identifier.
+   * @returns Array of active facet values.
+   */
+  public getFacetFilter(axis: string): string[] {
+    const set = this.facetFilters.get(axis)
+    return set ? Array.from(set) : []
+  }
+
+  /**
+   * Retrieves all active multi-axial facet filters.
+   * 
+   * @returns Key-value map of axis name to selected filter values array.
+   */
+  public getAllFacetFilters(): Record<string, string[]> {
+    const res: Record<string, string[]> = {}
+    for (const [axis, set] of this.facetFilters.entries()) {
+      if (set.size > 0) {
+        res[axis] = Array.from(set)
+      }
+    }
+    return res
+  }
+
+  /**
+   * Clears all active multi-axial facet filters.
+   */
+  public clearFacetFilters(): void {
+    this.facetFilters.clear()
+    this.notify()
+  }
+
+  /**
+   * Tests whether an item's multi-axial facets match the currently active filters.
+   * 
+   * @param itemFacets - Document facet metadata (e.g. { soils: ['argilo-calcaire'], climates: ['mediterraneen'] }).
+   * @returns True if the item satisfies all active facet criteria.
+   */
+  public matchesFilters(itemFacets: Record<string, any>): boolean {
+    // 1. Check thematic selection
+    if (this.selectedIds.size > 0) {
+      const selected = Array.from(this.selectedIds)
+      const itemThematics = Array.isArray(itemFacets.thematics) ? itemFacets.thematics : [itemFacets.category].filter(Boolean)
+      const matchesThematic = selected.some(s => itemThematics.includes(s) || itemFacets.category === s)
+      if (!matchesThematic) return false
+    }
+
+    // 2. Check each multi-axial facet
+    for (const [axis, filterSet] of this.facetFilters.entries()) {
+      if (filterSet.size === 0) continue
+      const itemVals = itemFacets[axis]
+      if (!itemVals) return false
+      const itemValArray = Array.isArray(itemVals) ? itemVals : [itemVals]
+      const hasMatch = itemValArray.some((v: string) => filterSet.has(v))
+      if (!hasMatch) return false
+    }
+
+    return true
+  }
+
+  protected notify(): void {
+    const tree = this.getTree()
+    const selected = this.getSelected()
+    for (const listener of this.listeners) {
+      listener(tree, selected)
+    }
+  }
+}