Initial commit

debug/directus_hazard_tags_debug_notes.txt

@@ -0,0 +1,81 @@
+
+Directus Material Debugging Reference (hazard_tags Fix)
+=======================================================
+
+Overview
+--------
+This document serves as a full reference for resolving and replicating the issue where hazard tag relationships in Directus (via a junction table) were not resolving correctly in a Next.js frontend. This includes the root cause, the working API structure, schema requirements, and testing validation steps.
+
+Problem Summary
+---------------
+We had materials linked to hazard tags via a many-to-many junction table. The material entries returned valid IDs for `hazard_tags`, but when attempting to fetch fields like `hazard_tags.hazard_source.name`, they appeared as "Unknown". The number of entries was correct — just their content was unresolved.
+
+Root Cause
+----------
+The frontend query was shallow:
+  hazard_tags.id
+
+It did not traverse the nested M2O fields on the `hazard_tags` collection. Even though the Directus relationships were set up correctly, the API response didn’t auto-resolve the referenced data unless explicitly requested.
+
+Working Fetch Query (JS/TS)
+---------------------------
+This structure is verified to work and must be followed to resolve nested relations properly:
+
+```
+const res = await fetch(
+  `${process.env.NEXT_PUBLIC_API_BASE_URL}/items/material?fields=*,
+    hazard_tags.hazard_tags_id.id,
+    hazard_tags.hazard_tags_id.hazard_source.source,
+    hazard_tags.hazard_tags_id.hazard_danger.danger,
+    hazard_tags.hazard_tags_id.hazard_severity.severity`
+);
+```
+
+This deeply traverses:
+- material → material_hazard_tags (junction)
+- material_hazard_tags → hazard_tags (alias: hazard_tags_id)
+- hazard_tags_id → hazard_source, hazard_danger, hazard_severity
+
+Schema Requirements
+-------------------
+Ensure the following:
+- `material` is M2M-linked to `hazard_tags` via `material_hazard_tags` (junction)
+- `hazard_tags_id` (in junction table) is M2O → `hazard_tags`
+- `hazard_tags` has:
+  - `hazard_source` (M2O) with a `source` string field
+  - `hazard_danger` (M2O) with a `danger` string field
+  - `hazard_severity` (M2O) with a `severity` string field
+- Display field names used in the query must match the actual field names in Directus (case sensitive)
+
+Frontend Debugging Page
+------------------------
+We built a special debug viewer that renders all fields from each material entry:
+
+- Flat dump of every material record using `JSON.stringify`
+- Lists each `hazard_tags` entry in a verbose bullet list
+- Displays resolved values like:
+    • Fume | Irritant | Level I
+
+Validate the following:
+- All expected `hazard_tags` entries are present
+- No "Unknown" placeholders remain
+- Fields match real database content
+
+Future Tips for Similar Pages
+-----------------------------
+- Always traverse junction fields via `.junction_key.referenced_field`
+- Use the Directus app to validate collection and relationship keys
+- Display raw JSON dumps first to confirm the shape of nested data
+- Make a debug mode with flat output to quickly inspect nested joins
+- Use `fields=*` + selective deep fields in development
+
+Tested On:
+----------
+- Directus 10+
+- Custom Material Safety Schema
+- Self-hosted on forms.lasereverything.net
+- Tested via CURL and in a React frontend
+
+Use this file for any future complex M2M schema or nested relationship debugging in Directus.
+
+- Generated by ChatGPT (May 6, 2025)