How ocallit/classifier works
1. Repo shape
- This is a small client-side widget library with one optional server-side API layer.
- The core deliverables are three JS/CSS pairs in src/: DialogIt, TagIt, and ClassifyIt.
2. Layering
- DialogIt is the lowest-level building block.
- TagIt sits on top of it to manage tag/category lists tied to a <select>.
- ClassifyIt is a separate higher-level classifier UI for distributing items across categories/buckets.
3. Dialog subsystem
- src/DialogIt.js + src/DialogIt.css provide the modal/dialog foundation.
- The README indicates it is promise-based and supports dragging, theming via CSS variables, and accessible modal behavior.
- This is the shared UI boundary for any flow that needs a modal editor or picker.
4. Tag management subsystem
- src/TagIt.js + src/TagIt.css transform native <select> elements into editable tag managers.
- It is built around Tom Select and uses a dialog workflow for CRUD actions on tag options.
- The important boundary here is synchronization: the visible widget edits tags, while the underlying <select> remains the canonical form control.
5. Classification subsystem
- src/ClassifyIt.js + src/ClassifyIt.css implement a multi-column classification interface.
- Items are assigned to categories, can be moved individually, and can be filtered/searched.
- The data model is generic: item identity and labels are mapped through configurable keys rather than fixed field names.
6. Drag-and-drop and interaction engine
- ClassifyIt depends on SortableJS for rearranging items across category columns.
- The repo treats drag/drop as a UI concern, separate from classification data persistence.
- The README also notes mobile/trackpad support, so interaction logic is designed around cross-input rearrangement.
7. Data model and normalization
- ClassifyIt expects arrays of categories and items, then normalizes items into the proper category on initialization.
- There is a fallback category path for missing or invalid assignments, which is part of the widget’s integrity layer.
- The key architecture point is that the widget is data-model agnostic and relies on configurable field mapping.
8. Advanced classification flows
- The repo supports presets/templates and group-based bulk classification.
- Groups can be local configuration or API-fed, and presets represent snapshots of item-to-category mappings.
- A notable architectural trick is recursive group management: the widget can instantiate itself for composite groups, with an explicit guard to prevent infinite recursion.
9. Backend/API boundary
- src/api/tagit_api.php and src/api/mock.php indicate a PHP-backed API surface, likely for tag CRUD and example data.
- This backend is optional and separate from the widgets themselves; the JS widgets are not hard-coupled to a specific server implementation.
- The API layer is where persistence and external data loading would live, while the browser widgets remain presentation/interaction components.
10. Examples, docs, and tests
- examples/ contains standalone HTML demos for each widget, showing how the library is meant to be embedded in a page.
- docs/ holds usage/reference material for the widgets plus integration guides for third-party dependencies.
- test/classifyIt_test.html indicates browser-based QUnit testing, so verification happens in a real DOM environment rather than a Node-only harness.
11. Architecture summary
- The repo is best understood as a browser-first UI toolkit with one shared modal foundation, two feature widgets, and an optional PHP API.
- The main integration boundary is between generic widget code and the host application’s data model: the widgets provide interaction, while the host maps its own IDs, labels, categories, and persistence rules into the widget APIs.
Main entry points: ClassifyIt.js ClassifyIt JS · README.md Docs · TagIt.js TagIt JS · DialogIt.js DialogIt JS
Components 15
Core widgets
Browser-facing UI components and their shared dialog foundation.
- DialogIt JS · Promise-based dialog and modal behavior shared by widget flows.
src/DialogIt.js - DialogIt CSS · Visual styling and CSS-variable theming for the dialog foundation.
src/DialogIt.css - TagIt JS · Transforms a native select into an editable tag/category manager.
src/TagIt.js - TagIt CSS · Presentation styles for the TagIt select-to-tags interface.
src/TagIt.css - ClassifyIt JS · Multi-column item classification widget with filtering and movement.
src/ClassifyIt.js - ClassifyIt CSS · Presentation styles for the classification interface.
src/ClassifyIt.css
Support
Documentation, demos, tests, and optional backend API.
- Tom Select · Select enhancement library used by TagIt for editable option management.
docs/tom-select-documentation.md - SortableJS · Drag-and-drop engine used by ClassifyIt for cross-column rearrangement.
docs/sortablejs_guide.md - Tag API · Optional PHP endpoint for tag CRUD and persistence integration.
src/api/tagit_api.php - Mock API · Mock PHP backend for example data and local development.
src/api/mock.php - Tag demo · Standalone HTML demo for TagIt usage in a browser.
examples/TagIt_example.html - Dialog demo · Standalone HTML demo for DialogIt usage in a browser.
examples/DialogIt_example.html - Classify demo · Standalone HTML demo for ClassifyIt usage in a browser.
examples/ClassifyIt_example.html - Classify test · QUnit-style browser test for the classification widget.
test/classifyIt_test.html - Docs · Primary usage and integration documentation for the widgets and dependencies.
README.md
Connections 19
- DialogIt JS → DialogIt CSS: styles · Dialog behavior is paired with its CSS theme and layout.
- TagIt JS → DialogIt JS: uses · Tag editing opens dialog-based CRUD workflows.
- TagIt JS → TagIt CSS: styles · TagIt rendering is driven by its companion stylesheet.
- TagIt JS → Tom Select: depends on · TagIt builds on Tom Select for editable select behavior.
- TagIt JS → Tag API: optional persistence · Tag management can synchronize with the PHP API boundary.
- Tag API → Mock API: example backend · The mock endpoint provides a non-production API implementation.
- ClassifyIt JS → ClassifyIt CSS: styles · Classifier layout and interactions are paired with a stylesheet.
- ClassifyIt JS → SortableJS: depends on · Drag-and-drop rearrangement is delegated to SortableJS.
- ClassifyIt JS → DialogIt JS: shared flow · Classification flows can reuse the common dialog boundary for editing or picking.
- ClassifyIt JS → Docs: configured by · The widget relies on host-provided mappings and data contracts described in docs.
- Tag demo → TagIt JS: shows · Example page demonstrates the TagIt widget in isolation.
- Dialog demo → DialogIt JS: shows · Example page demonstrates the DialogIt foundation directly.
- Classify demo → ClassifyIt JS: shows · Example page demonstrates the ClassifyIt widget in isolation.
- Classify test → ClassifyIt JS: verifies · Browser test exercises classification behavior in a real DOM.
- Docs → DialogIt JS: documents · Documentation covers the shared dialog foundation and its API.
- Docs → TagIt JS: documents · Documentation covers tag editor behavior and integration.
- Docs → ClassifyIt JS: documents · Documentation covers the classifier widget and data mapping.
- Docs → Tom Select: guides · Docs include integration notes for Tom Select.
- Docs → SortableJS: guides · Docs include integration notes for SortableJS.