@quatrain/ux-taxonomy 1.0.1

package/README.md

@@ -0,0 +1,41 @@
+# @quatrain/ux-taxonomy
+
+Headless taxonomy controller and interactive React Mantine components for managing thematic trees, categories, and transversal tagging.
+
+## Features
+
+- **Framework-Agnostic Headless Controller**: `TaxonomyController` handles hierarchical nodes, single/multi-selection, expansions, and listener notifications with zero external framework dependencies.
+- **ThematicTree Component**: Accessible, interactive Mantine-based tree view with live filtering, badge counts, and add-subthematic triggers.
+- **ThematicBadgeGroup Component**: Interactive badge cluster for managing multi-thematic tag associations.
+
+## Installation
+
+```bash
+yarn add @quatrain/ux-taxonomy
+```
+
+## Quick Start
+
+```tsx
+import { TaxonomyController, ThematicTree } from '@quatrain/ux-taxonomy'
+
+const controller = new TaxonomyController({
+  initialNodes: [
+    {
+      id: 'soil-health',
+      label: 'Soil Health & Biology',
+      children: [{ id: 'mycorrhizae', label: 'Mycorrhizae' }]
+    },
+    { id: 'cover-crops', label: 'Cover Crops' }
+  ]
+})
+
+export function MyThematicExplorer() {
+  return (
+    <ThematicTree
+      controller={controller}
+      onSelect={(node) => console.log('Selected:', node.id)}
+    />
+  )
+}
+```

package/dist/TaxonomyController.d.ts

@@ -0,0 +1,184 @@
+/**
+ * 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 declare class TaxonomyController {
+    protected nodes: Map<string, TaxonomyNode>;
+    protected selectedIds: Set<string>;
+    protected expandedIds: Set<string>;
+    protected facetFilters: Map<string, Set<string>>;
+    protected listeners: Set<TaxonomyListener>;
+    protected multiSelect: boolean;
+    /**
+     * Instantiates a new TaxonomyController.
+     *
+     * @param options - Configuration options.
+     */
+    constructor(options?: TaxonomyControllerOptions);
+    /**
+     * Loads or replaces nodes in the taxonomy manager.
+     *
+     * @param nodes - Array of hierarchical or flat taxonomy nodes.
+     */
+    loadNodes(nodes: TaxonomyNode[]): void;
+    /**
+     * Adds or updates a thematic node in the taxonomy.
+     *
+     * @param node - The thematic node to insert or update.
+     */
+    addNode(node: TaxonomyNode): void;
+    /**
+     * Removes a node and recursively removes its sub-thematics.
+     *
+     * @param id - The identifier of the node to remove.
+     */
+    removeNode(id: string): void;
+    /**
+     * Selects a thematic node. Clears previous selection unless multiSelect is enabled.
+     *
+     * @param id - The node identifier to select.
+     */
+    select(id: string): void;
+    /**
+     * Deselects a thematic node.
+     *
+     * @param id - The node identifier to deselect.
+     */
+    deselect(id: string): void;
+    /**
+     * Toggles the selection status of a thematic node.
+     *
+     * @param id - The node identifier to toggle.
+     */
+    toggleSelect(id: string): void;
+    /**
+     * Clears all active selections.
+     */
+    clearSelection(): void;
+    /**
+     * Retrieves the set of currently selected thematic node identifiers.
+     *
+     * @returns Array of selected IDs.
+     */
+    getSelected(): string[];
+    /**
+     * Checks whether a specific thematic node is currently selected.
+     *
+     * @param id - The thematic identifier to verify.
+     * @returns True if selected, false otherwise.
+     */
+    isSelected(id: string): boolean;
+    /**
+     * Toggles the expansion collapse state of a parent thematic node.
+     *
+     * @param id - The thematic identifier to toggle.
+     */
+    toggleExpand(id: string): void;
+    /**
+     * Checks whether a thematic node is currently expanded.
+     *
+     * @param id - The thematic identifier to check.
+     * @returns True if expanded, false otherwise.
+     */
+    isExpanded(id: string): boolean;
+    /**
+     * Reconstructs and returns the full hierarchical taxonomy tree.
+     *
+     * @returns Array of root-level TaxonomyNodes with nested children.
+     */
+    getTree(): TaxonomyNode[];
+    /**
+     * Returns a flat array of all registered taxonomy nodes.
+     *
+     * @returns Array of TaxonomyNode objects.
+     */
+    getFlatNodes(): TaxonomyNode[];
+    /**
+     * Finds a specific thematic node by identifier.
+     *
+     * @param id - The node identifier to locate.
+     * @returns The TaxonomyNode or undefined if not found.
+     */
+    getNode(id: string): TaxonomyNode | undefined;
+    /**
+     * Updates the document counter for a thematic node.
+     *
+     * @param id - The thematic identifier.
+     * @param count - The updated count.
+     */
+    updateCount(id: string, count: number): void;
+    /**
+     * Subscribes a listener callback to state changes.
+     *
+     * @param listener - Callback receiving updated nodes and active selection.
+     * @returns Unsubscribe function.
+     */
+    subscribe(listener: TaxonomyListener): () => void;
+    /**
+     * 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.
+     */
+    setFacetFilter(axis: string, values: string[]): void;
+    /**
+     * Retrieves active filter values for a specific facet axis.
+     *
+     * @param axis - The facet axis identifier.
+     * @returns Array of active facet values.
+     */
+    getFacetFilter(axis: string): string[];
+    /**
+     * Retrieves all active multi-axial facet filters.
+     *
+     * @returns Key-value map of axis name to selected filter values array.
+     */
+    getAllFacetFilters(): Record<string, string[]>;
+    /**
+     * Clears all active multi-axial facet filters.
+     */
+    clearFacetFilters(): void;
+    /**
+     * 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.
+     */
+    matchesFilters(itemFacets: Record<string, any>): boolean;
+    protected notify(): void;
+}

package/dist/TaxonomyController.js

@@ -0,0 +1,318 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaxonomyController = void 0;
+/**
+ * Headless, framework-agnostic controller managing hierarchical thematics,
+ * category trees, transversal tag taxonomies, and active filter selections.
+ */
+class TaxonomyController {
+    nodes = new Map();
+    selectedIds = new Set();
+    expandedIds = new Set();
+    facetFilters = new Map();
+    listeners = new Set();
+    multiSelect;
+    /**
+     * Instantiates a new TaxonomyController.
+     *
+     * @param options - Configuration options.
+     */
+    constructor(options = {}) {
+        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.
+     */
+    loadNodes(nodes) {
+        this.nodes.clear();
+        const flatten = (items, parentId = null) => {
+            for (const item of items) {
+                const node = {
+                    ...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.
+     */
+    addNode(node) {
+        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.
+     */
+    removeNode(id) {
+        const childrenToRemove = [];
+        const findDescendants = (parentId) => {
+            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.
+     */
+    select(id) {
+        if (!this.multiSelect) {
+            this.selectedIds.clear();
+        }
+        this.selectedIds.add(id);
+        this.notify();
+    }
+    /**
+     * Deselects a thematic node.
+     *
+     * @param id - The node identifier to deselect.
+     */
+    deselect(id) {
+        this.selectedIds.delete(id);
+        this.notify();
+    }
+    /**
+     * Toggles the selection status of a thematic node.
+     *
+     * @param id - The node identifier to toggle.
+     */
+    toggleSelect(id) {
+        if (this.selectedIds.has(id)) {
+            this.deselect(id);
+        }
+        else {
+            this.select(id);
+        }
+    }
+    /**
+     * Clears all active selections.
+     */
+    clearSelection() {
+        this.selectedIds.clear();
+        this.notify();
+    }
+    /**
+     * Retrieves the set of currently selected thematic node identifiers.
+     *
+     * @returns Array of selected IDs.
+     */
+    getSelected() {
+        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.
+     */
+    isSelected(id) {
+        return this.selectedIds.has(id);
+    }
+    /**
+     * Toggles the expansion collapse state of a parent thematic node.
+     *
+     * @param id - The thematic identifier to toggle.
+     */
+    toggleExpand(id) {
+        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.
+     */
+    isExpanded(id) {
+        return this.expandedIds.has(id);
+    }
+    /**
+     * Reconstructs and returns the full hierarchical taxonomy tree.
+     *
+     * @returns Array of root-level TaxonomyNodes with nested children.
+     */
+    getTree() {
+        const rootNodes = [];
+        const nodeMap = new Map();
+        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.
+     */
+    getFlatNodes() {
+        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.
+     */
+    getNode(id) {
+        return this.nodes.get(id);
+    }
+    /**
+     * Updates the document counter for a thematic node.
+     *
+     * @param id - The thematic identifier.
+     * @param count - The updated count.
+     */
+    updateCount(id, count) {
+        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.
+     */
+    subscribe(listener) {
+        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.
+     */
+    setFacetFilter(axis, values) {
+        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.
+     */
+    getFacetFilter(axis) {
+        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.
+     */
+    getAllFacetFilters() {
+        const res = {};
+        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.
+     */
+    clearFacetFilters() {
+        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.
+     */
+    matchesFilters(itemFacets) {
+        // 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) => filterSet.has(v));
+            if (!hasMatch)
+                return false;
+        }
+        return true;
+    }
+    notify() {
+        const tree = this.getTree();
+        const selected = this.getSelected();
+        for (const listener of this.listeners) {
+            listener(tree, selected);
+        }
+    }
+}
+exports.TaxonomyController = TaxonomyController;

package/dist/ThematicBadgeGroup.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import type { TaxonomyNode } from './TaxonomyController';
+export interface ThematicBadgeGroupProps {
+    /** Available taxonomy nodes / thematics */
+    nodes: TaxonomyNode[];
+    /** Array of currently selected thematic slugs/ids */
+    value: string[];
+    /** Callback fired when the selection changes */
+    onChange: (selectedIds: string[]) => void;
+    /** Label displayed above the badges */
+    label?: string;
+    /** Description or subtext */
+    description?: string;
+    /** Custom CSS class */
+    className?: string;
+    /** Custom styles */
+    style?: React.CSSProperties;
+}
+/**
+ * Interactive badge group component allowing multi-selection of transversal thematics.
+ */
+export declare const ThematicBadgeGroup: React.FC<ThematicBadgeGroupProps>;

package/dist/ThematicBadgeGroup.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ThematicBadgeGroup = void 0;
+const react_1 = __importDefault(require("react"));
+const core_1 = require("@mantine/core");
+/**
+ * Interactive badge group component allowing multi-selection of transversal thematics.
+ */
+const ThematicBadgeGroup = ({ nodes, value = [], onChange, label, description, className = '', style }) => {
+    const handleToggle = (id) => {
+        if (value.includes(id)) {
+            onChange(value.filter((v) => v !== id));
+        }
+        else {
+            onChange([...value, id]);
+        }
+    };
+    return (react_1.default.createElement(core_1.Box, { className: `q-thematic-badge-group ${className}`, style: style },
+        label && (react_1.default.createElement(core_1.Text, { size: "sm", fw: 500, mb: 2 }, label)),
+        description && (react_1.default.createElement(core_1.Text, { size: "xs", c: "dimmed", mb: "xs" }, description)),
+        react_1.default.createElement(core_1.Group, { gap: "xs" }, nodes.map((node) => {
+            const isSelected = value.includes(node.id);
+            return (react_1.default.createElement(core_1.Badge, { key: node.id, size: "md", variant: isSelected ? 'filled' : 'outline', color: node.color || (isSelected ? 'blue' : 'gray'), style: { cursor: 'pointer', userSelect: 'none' }, onClick: () => handleToggle(node.id) }, node.label));
+        }))));
+};
+exports.ThematicBadgeGroup = ThematicBadgeGroup;

package/dist/ThematicTree.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+import { TaxonomyController, type TaxonomyNode } from './TaxonomyController';
+/**
+ * Properties for rendering the ThematicTree component.
+ */
+export interface ThematicTreeProps {
+    /** The taxonomy controller managing state */
+    controller: TaxonomyController;
+    /** Optional callback fired when a node is selected */
+    onSelect?: (node: TaxonomyNode) => void;
+    /** Optional callback fired when the 'Add Sub-thematic' button is clicked */
+    onAddSubThematic?: (parentNode?: TaxonomyNode) => void;
+    /** Whether to show a live search filter input on top */
+    searchable?: boolean;
+    /** Custom CSS class */
+    className?: string;
+    /** Custom styles */
+    style?: React.CSSProperties;
+}
+/**
+ * Tree component rendering interactive taxonomic hierarchies with Mantine styling.
+ */
+export declare const ThematicTree: React.FC<ThematicTreeProps>;