@viengut/vgq-sdk 0.1.0 → 0.2.0

package/dist/engine.d.ts

@@ -11,12 +11,15 @@ export declare function topoOrder(def: FormDefinition): {
 export interface ActiveState {
     /** Id các Question đang hoạt động. */
     activeIds: Set<string>;
+    /** Id các Category đang hiện (điều kiện của chính nó và mọi tổ tiên đều đúng). */
+    activeCategoryIds: Set<string>;
     /** Giá trị hiệu lực theo slug: chỉ gồm giá trị của Question đang hoạt động. */
     effectiveValues: ResponseValues;
 }
 /**
  * Đánh giá Enable Condition toàn Form theo thứ tự topo. Giá trị của Question
  * không hoạt động bị loại khỏi giá trị hiệu lực nên chuỗi phụ thuộc tắt theo.
+ * Question trong Category tắt cũng không hoạt động.
  */
 export declare function computeActive(def: FormDefinition, values: ResponseValues): ActiveState;
 export declare function isAnswered(value: JsonValue | undefined): boolean;

package/dist/engine.js

@@ -12,8 +12,27 @@ export function allQuestions(def) {
     walk(def.categories);
     return out;
 }
-function conditionRefs(question) {
-    return (question.enable_condition?.any ?? []).flatMap((group) => group.all.map((condition) => condition.question_id));
+function conditionRefs(cond) {
+    return (cond?.any ?? []).flatMap((group) => group.all.map((condition) => condition.question_id));
+}
+/**
+ * Phụ thuộc Enable Condition của từng Question: refs của chính nó cộng refs
+ * điều kiện của mọi Category tổ tiên (Category tắt kéo Question tắt theo,
+ * nên thứ tự topo và phát hiện chu trình phủ luôn điều kiện cấp Category).
+ */
+function dependencyMap(def) {
+    const out = new Map();
+    const walk = (categories, inherited) => {
+        for (const category of categories) {
+            const refs = [...inherited, ...conditionRefs(category.enable_condition)];
+            for (const q of category.questions) {
+                out.set(q.id, [...refs, ...conditionRefs(q.enable_condition)]);
+            }
+            walk(category.children ?? [], refs);
+        }
+    };
+    walk(def.categories, []);
+    return out;
 }
 /**
  * Sắp xếp topo theo phụ thuộc Enable Condition (Kahn).
@@ -22,10 +41,11 @@ function conditionRefs(question) {
 export function topoOrder(def) {
     const questions = allQuestions(def);
     const known = new Set(questions.map((q) => q.id));
+    const deps = dependencyMap(def);
     const inDegree = new Map();
     const dependents = new Map();
     for (const q of questions) {
-        const valid = conditionRefs(q).filter((ref) => known.has(ref));
+        const valid = (deps.get(q.id) ?? []).filter((ref) => known.has(ref));
         inDegree.set(q.id, valid.length);
         for (const ref of valid) {
             const list = dependents.get(ref) ?? [];
@@ -49,13 +69,35 @@ export function topoOrder(def) {
     const stuck = [...known].filter((id) => !done.has(id)).sort();
     return { order, stuck };
 }
+function indexCategories(def) {
+    const idx = {
+        condition: new Map(),
+        parent: new Map(),
+        categoryOf: new Map(),
+        ordered: [],
+    };
+    const walk = (categories, parent) => {
+        for (const c of categories) {
+            idx.condition.set(c.id, c.enable_condition);
+            idx.parent.set(c.id, parent);
+            idx.ordered.push(c.id);
+            for (const q of c.questions)
+                idx.categoryOf.set(q.id, c.id);
+            walk(c.children ?? [], c.id);
+        }
+    };
+    walk(def.categories, null);
+    return idx;
+}
 /**
  * Đánh giá Enable Condition toàn Form theo thứ tự topo. Giá trị của Question
  * không hoạt động bị loại khỏi giá trị hiệu lực nên chuỗi phụ thuộc tắt theo.
+ * Question trong Category tắt cũng không hoạt động.
  */
 export function computeActive(def, values) {
     const questions = allQuestions(def);
     const byId = new Map(questions.map((q) => [q.id, q]));
+    const idx = indexCategories(def);
     const { order, stuck } = topoOrder(def);
     const evaluationOrder = stuck.length === 0 ? order : questions.map((q) => q.id);
     const effectiveValues = {};
@@ -64,16 +106,37 @@ export function computeActive(def, values) {
         if (v !== undefined && v !== null)
             effectiveValues[q.slug] = v;
     }
+    // Category hiện khi điều kiện của nó và mọi tổ tiên đều đúng. Memo an toàn
+    // vì thứ tự topo bảo đảm các Question được tham chiếu đã chốt giá trị
+    // trước khi bất kỳ Question nào bên trong Category được đánh giá.
+    const catMemo = new Map();
+    const categoryActive = (id) => {
+        const memoized = catMemo.get(id);
+        if (memoized !== undefined)
+            return memoized;
+        const parent = idx.parent.get(id) ?? null;
+        const cond = idx.condition.get(id);
+        const active = (parent === null || categoryActive(parent)) &&
+            (!cond || evalCondition(cond, effectiveValues, byId));
+        catMemo.set(id, active);
+        return active;
+    };
     const activeIds = new Set();
     for (const id of evaluationOrder) {
         const q = byId.get(id);
-        const active = !q.enable_condition || evalCondition(q.enable_condition, effectiveValues, byId);
+        const cat = idx.categoryOf.get(id);
+        const active = (cat === undefined || categoryActive(cat)) &&
+            (!q.enable_condition ||
+                evalCondition(q.enable_condition, effectiveValues, byId));
         if (active)
             activeIds.add(id);
         else
             delete effectiveValues[q.slug];
     }
-    return { activeIds, effectiveValues };
+    // Category không chứa Question nào chưa được đánh giá trong vòng trên;
+    // giá trị hiệu lực đã chốt nên đánh giá nốt tại đây.
+    const activeCategoryIds = new Set(idx.ordered.filter(categoryActive));
+    return { activeIds, activeCategoryIds, effectiveValues };
 }
 function evalCondition(condition, effective, byId) {
     return condition.any.some((group) => group.all.every((c) => evalSingle(c, effective, byId)));

package/dist/types.d.ts

@@ -54,12 +54,39 @@ export interface BodyMapSpot {
     /** Metadata lâm sàng tuỳ ý; VGQ không diễn giải. */
     metadata?: JsonValue;
 }
+/**
+ * Hướng dẫn bằng audio/video kèm lời dẫn, đặt ở Form, Category hoặc dùng làm
+ * audio phát khi chọn Option. Ứng dụng phát media (nếu có) và/hoặc đọc `text`.
+ */
+export interface Guidance {
+    /** Media Asset dạng audio hoặc video; vắng mặt nghĩa là chỉ có lời dẫn. */
+    media_asset_id?: string;
+    text?: string;
+}
+/** Thang đau VAS: các khoảng điểm liên tiếp kèm mô tả để tự đối chiếu. */
+export interface PainScale {
+    enabled: boolean;
+    ranges: PainRange[];
+}
+export interface PainRange {
+    start: number;
+    end: number;
+    label?: string;
+}
 export interface OptionDef {
     id: string;
     slug: string;
     label: string;
     /** Chỉ có mặt khi Question có data type body_map. */
     body_map?: BodyMapSpot | null;
+    /**
+     * Option cha trong cùng Question, theo id nội bộ. Body Map nhiều tầng: vùng
+     * lớn là Option cha, điểm chi tiết là Option con. Response Value vẫn phẳng.
+     */
+    parent_id?: string | null;
+    /** Audio phát khi Respondent chọn Option. */
+    audio?: Guidance | null;
+    pain_scale?: PainScale | null;
 }
 export interface MediaAssetDto {
     id: string;
@@ -88,11 +115,21 @@ export interface CategoryDef {
     label: string;
     children?: CategoryDef[];
     questions: QuestionDef[];
+    /** Hướng dẫn mở đầu cho riêng Category này. */
+    guidance?: Guidance | null;
+    /**
+     * Điều kiện hiện cả Category (ví dụ tab bệnh hiện theo lý do đến khám).
+     * Category tắt thì mọi Question bên trong — kể cả trong Category con —
+     * tắt theo và giá trị của chúng bị loại khỏi official values.
+     */
+    enable_condition?: EnableCondition | null;
 }
 export interface FormDefinition {
     title: string;
     form_type: FormType;
     categories: CategoryDef[];
+    /** Hướng dẫn mở đầu cho cả Form. */
+    guidance?: Guidance | null;
 }
 export interface ValidationIssue {
     path: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viengut/vgq-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Headless TypeScript SDK for the VGQ clinical form platform: load published Forms, manage Response state, evaluate Enable Conditions and validate Response Values without any UI components.",
   "repository": {
     "type": "git",