reflex-icd11ect 0.1.0__py3-none-any.whl

reflex_icd11ect/__init__.py

@@ -0,0 +1,105 @@
+"""Reflex custom component for the WHO ICD-11 Embedded Classification Tools.
+
+Wraps `@whoicd/icd11ect <https://www.npmjs.com/package/@whoicd/icd11ect>`_,
+the WHO's Embedded Coding Tool and Embedded Browser, powered by the ICD-API.
+
+Quick start::
+
+    import reflex as rx
+    from reflex_icd11ect import icd11ect
+
+    class State(rx.State):
+        code: str = ""
+
+        @rx.event
+        def on_select(self, entity: dict[str, str]):
+            self.code = entity["code"]
+
+    def index():
+        return rx.vstack(
+            rx.text(State.code),
+            icd11ect.coding_tool(
+                api_server_url="https://id.who.int",
+                api_secured=True,
+                token=State.token,
+                on_select=State.on_select,
+            ),
+        )
+"""
+
+from reflex_icd11ect import constants, handler, token
+from reflex_icd11ect.constants import (
+    ALL_SETTINGS,
+    BROWSER_SETTINGS,
+    CODING_TOOL_SETTINGS,
+    COMMON_SETTINGS,
+    ECT_PACKAGE,
+    ECT_STYLESHEET,
+    ECT_VERSION,
+    ICD_TOKEN_ENDPOINT,
+    ICD_TOKEN_SCOPE,
+    LANGUAGES,
+    MMS_CHAPTERS,
+    OVERWRITABLE_SETTINGS,
+    RTL_LANGUAGES,
+    SELECT_BUTTON_MODES,
+    SOURCES,
+    WHO_CLOUD_API,
+    WHO_DEVELOPER_TEST_API,
+)
+from reflex_icd11ect.icd11ect import (
+    Icd11ectBrowser,
+    Icd11ectCodingTool,
+    Icd11ectController,
+    browser_window,
+    icd11ect_browser,
+    icd11ect_coding_tool,
+    icd11ect_controller,
+    icd11ect_provider,
+    result_window,
+    search_input,
+)
+from reflex_icd11ect.namespace import icd11ect
+from reflex_icd11ect.token import IcdTokenError, IcdTokenProvider
+from reflex_icd11ect.types import BrowserContent, SelectedEntity
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ALL_SETTINGS",
+    "BROWSER_SETTINGS",
+    "CODING_TOOL_SETTINGS",
+    "COMMON_SETTINGS",
+    "ECT_PACKAGE",
+    "ECT_STYLESHEET",
+    "ECT_VERSION",
+    "ICD_TOKEN_ENDPOINT",
+    "ICD_TOKEN_SCOPE",
+    "LANGUAGES",
+    "MMS_CHAPTERS",
+    "OVERWRITABLE_SETTINGS",
+    "RTL_LANGUAGES",
+    "SELECT_BUTTON_MODES",
+    "SOURCES",
+    "WHO_CLOUD_API",
+    "WHO_DEVELOPER_TEST_API",
+    "BrowserContent",
+    "Icd11ectBrowser",
+    "Icd11ectCodingTool",
+    "Icd11ectController",
+    "IcdTokenError",
+    "IcdTokenProvider",
+    "SelectedEntity",
+    "__version__",
+    "browser_window",
+    "constants",
+    "handler",
+    "icd11ect",
+    "icd11ect_browser",
+    "icd11ect_coding_tool",
+    "icd11ect_controller",
+    "icd11ect_provider",
+    "result_window",
+    "search_input",
+    "token",
+]

reflex_icd11ect/_runtime.py

@@ -0,0 +1,291 @@
+"""The JavaScript runtime that bridges ECT to Reflex.
+
+``@whoicd/icd11ect`` is not a React component: it is an imperative library
+that renders itself into DOM nodes carrying ``data-ctw-ino`` attributes, and
+it keeps a single global configuration plus a single set of callbacks for the
+whole page.
+
+This module holds the JavaScript that reconciles that model with Reflex:
+
+* a page level singleton (``window.__reflexIcd11ect``) that owns the ECT
+  configuration and routes ECT's global callbacks to the right component
+  instance, keyed by ``iNo``;
+* ``useIcd11ect``, the hook each component emits, which registers the
+  instance, configures ECT once, applies the per instance overrides and binds
+  the tool after the DOM has been committed (``autoBind`` is always disabled,
+  because ECT's auto binding listens for ``window.onload``, an event that has
+  long fired by the time a single page app renders a route);
+* OAUTH 2.0 token plumbing: either a token endpoint fetched from the browser,
+  or a round trip to the Reflex backend through the ``on_token_request``
+  event.
+"""
+
+from __future__ import annotations
+
+import json
+
+from reflex_icd11ect.constants import OVERWRITABLE_SETTINGS
+
+_RUNTIME_TEMPLATE = r"""
+/* reflex-icd11ect runtime. Bridges the imperative @whoicd/icd11ect API to Reflex. */
+const ICD11ECT_OVERWRITABLE = __OVERWRITABLE__;
+
+const icd11ectRuntime = () => {
+  if (typeof window === "undefined") return null;
+  let rt = window.__reflexIcd11ect;
+  if (!rt) {
+    rt = window.__reflexIcd11ect = {
+      instances: {},
+      globalSettings: {},
+      globalSettingsKey: "",
+      configured: false,
+      verbose: false,
+      token: null,
+      tokenVersion: 0,
+      tokenAsks: 0,
+      tokenConfig: {},
+      tokenWaiters: [],
+      lastIno: null,
+    };
+  }
+  rt.ECT = ECT;
+  /* Exposed on the singleton so `rx.call_script` helpers can reach them. */
+  rt.setToken = icd11ectSetToken;
+  rt.callbacks = icd11ectCallbacks;
+  return rt;
+};
+
+const icd11ectLog = (...args) => {
+  const rt = icd11ectRuntime();
+  if (rt && rt.verbose) console.log("[reflex-icd11ect]", ...args);
+};
+
+const icd11ectSetToken = (token) => {
+  const rt = icd11ectRuntime();
+  if (!rt || !token || token === rt.token) return;
+  rt.token = token;
+  rt.tokenVersion += 1;
+  const waiters = rt.tokenWaiters;
+  rt.tokenWaiters = [];
+  waiters.forEach((resolve) => resolve(token));
+  icd11ectLog("token updated, version", rt.tokenVersion);
+};
+
+const icd11ectWaitForToken = (rt, timeoutMs) =>
+  new Promise((resolve) => {
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value || "");
+    };
+    const timer = setTimeout(() => finish(rt.token), timeoutMs);
+    rt.tokenWaiters.push((token) => {
+      clearTimeout(timer);
+      finish(token);
+    });
+  });
+
+const icd11ectDispatch = (iNo, name, ...args) => {
+  const rt = icd11ectRuntime();
+  if (!rt) return;
+  if (iNo === null || iNo === undefined || iNo === "") {
+    Object.keys(rt.instances).forEach((key) => icd11ectDispatch(key, name, ...args));
+    return;
+  }
+  const instance = rt.instances[String(iNo)];
+  const handler =
+    instance && instance.callbacks && instance.callbacks.current
+      ? instance.callbacks.current[name]
+      : undefined;
+  if (handler) handler(...args);
+};
+
+/* ECT does not tell us which instance started or ended a search, so fall back
+   to the focused search box, then to the instance that last emitted. */
+const icd11ectActiveIno = () => {
+  const rt = icd11ectRuntime();
+  if (!rt) return null;
+  if (typeof document !== "undefined") {
+    const active = document.activeElement;
+    if (active && active.classList && active.classList.contains("ctw-input")) {
+      const iNo = active.getAttribute("data-ctw-ino");
+      if (iNo) return iNo;
+    }
+  }
+  return rt.lastIno;
+};
+
+const icd11ectCallbacks = {
+  selectedEntityFunction: (selectedEntity) => {
+    const rt = icd11ectRuntime();
+    if (rt && selectedEntity) rt.lastIno = String(selectedEntity.iNo);
+    icd11ectDispatch(selectedEntity && selectedEntity.iNo, "onSelect", selectedEntity);
+  },
+  browserChangedFunction: (browserContent) => {
+    icd11ectDispatch(
+      browserContent && browserContent.iNo,
+      "onBrowserChange",
+      browserContent,
+    );
+  },
+  browserLoadedFunction: () => icd11ectDispatch(null, "onBrowserLoad"),
+  searchStartedFunction: () => icd11ectDispatch(icd11ectActiveIno(), "onSearchStart"),
+  searchEndedFunction: () => icd11ectDispatch(icd11ectActiveIno(), "onSearchEnd"),
+  getNewTokenFunction: async () => {
+    const rt = icd11ectRuntime();
+    if (!rt) return "";
+    const config = rt.tokenConfig || {};
+    rt.tokenAsks += 1;
+    if (config.endpoint) {
+      try {
+        const response = await fetch(config.endpoint, config.fetchOptions || {});
+        const payload = await response.json();
+        const token =
+          typeof payload === "string"
+            ? payload
+            : payload[config.field || "token"] || payload.access_token;
+        icd11ectSetToken(token);
+        return token || "";
+      } catch (error) {
+        console.error(
+          "[reflex-icd11ect] could not fetch an ICD-API token from " + config.endpoint,
+          error,
+        );
+        return rt.token || "";
+      }
+    }
+    /* The token handed over by the backend is still the fresh one on the
+       first request, ECT only asks again once it has expired. */
+    if (rt.token && rt.tokenAsks === 1) return rt.token;
+    const known = rt.tokenVersion;
+    icd11ectDispatch(null, "onTokenRequest");
+    if (rt.tokenVersion !== known) return rt.token || "";
+    const token = await icd11ectWaitForToken(rt, config.timeoutMs || 15000);
+    if (!token) {
+      console.error(
+        "[reflex-icd11ect] the ICD-API is configured with api_secured=True but no " +
+          "token was provided. Set the `token` prop, handle `on_token_request`, " +
+          "or set `token_endpoint`.",
+      );
+    }
+    return token;
+  },
+};
+
+/* A prop bound to state can legitimately be empty; treat that as "not set" so
+   ECT keeps its own default instead of receiving an empty setting. */
+const icd11ectClean = (settings) =>
+  Object.fromEntries(
+    Object.entries(settings || {}).filter(
+      ([, value]) => value !== undefined && value !== null && value !== "",
+    ),
+  );
+
+const icd11ectConfigure = (rt) => {
+  const settings = rt.globalSettings || {};
+  if (!settings.apiServerUrl) {
+    icd11ectLog("waiting for api_server_url before configuring ECT");
+    return false;
+  }
+  const key = JSON.stringify(settings);
+  if (rt.configured && rt.globalSettingsKey === key) return true;
+  rt.ECT.Handler.configure({ ...settings, autoBind: false }, icd11ectCallbacks);
+  rt.configured = true;
+  rt.globalSettingsKey = key;
+  icd11ectLog("ECT configured", settings);
+  return true;
+};
+
+/* Only the settings ECT can override per instance are worth sending, and only
+   when they differ from the page wide configuration. */
+const icd11ectApplyInstance = (rt, iNo, settings) => {
+  const overrides = {};
+  ICD11ECT_OVERWRITABLE.forEach((key) => {
+    const value = settings[key];
+    if (value !== undefined && JSON.stringify(value) !== JSON.stringify(rt.globalSettings[key])) {
+      overrides[key] = value;
+    }
+  });
+  if (Object.keys(overrides).length === 0) return;
+  icd11ectLog("overwriteConfiguration", iNo, overrides);
+  rt.ECT.Handler.overwriteConfiguration(String(iNo), overrides, true);
+};
+
+const icd11ectBind = (rt, iNo) => {
+  icd11ectLog("bind", iNo);
+  rt.ECT.Handler.bind(String(iNo));
+};
+
+const icd11ectBindAll = (rt) => {
+  Object.keys(rt.instances).forEach((iNo) => {
+    icd11ectApplyInstance(rt, iNo, rt.instances[iNo].settings || {});
+    icd11ectBind(rt, iNo);
+  });
+};
+
+/* Registers one Coding Tool / Embedded Browser instance and keeps ECT in sync
+   with its props. */
+const useIcd11ect = (iNo, settings, callbacks, options) => {
+  const key = String(iNo);
+  const opts = options || {};
+  const callbacksRef = useRef(callbacks);
+  callbacksRef.current = callbacks;
+  const cleanSettings = icd11ectClean(settings);
+  const settingsKey = JSON.stringify(cleanSettings);
+  const token = opts.token;
+  const tokenEndpoint = opts.tokenEndpoint;
+  const tokenField = opts.tokenField;
+  const tokenTimeout = opts.tokenTimeoutMs;
+  const verbose = opts.verbose;
+
+  useEffect(() => {
+    const rt = icd11ectRuntime();
+    if (!rt) return;
+    if (verbose) rt.verbose = true;
+    if (tokenEndpoint || tokenField || tokenTimeout) {
+      rt.tokenConfig = {
+        ...rt.tokenConfig,
+        endpoint: tokenEndpoint,
+        field: tokenField,
+        timeoutMs: tokenTimeout,
+      };
+    }
+  }, [tokenEndpoint, tokenField, tokenTimeout, verbose]);
+
+  useEffect(() => {
+    if (token) icd11ectSetToken(token);
+  }, [token]);
+
+  useEffect(() => {
+    const rt = icd11ectRuntime();
+    if (!rt) return undefined;
+    rt.instances[key] = { callbacks: callbacksRef, settings: cleanSettings, kind: opts.kind };
+    /* Page wide configuration is the merge of every mounted instance, so an
+       unmounted one stops contributing. */
+    rt.globalSettings = Object.keys(rt.instances).reduce(
+      (merged, instanceKey) => ({ ...merged, ...(rt.instances[instanceKey].settings || {}) }),
+      {},
+    );
+    const needsConfigure =
+      !rt.configured || rt.globalSettingsKey !== JSON.stringify(rt.globalSettings);
+    const cleanup = () => {
+      delete rt.instances[key];
+    };
+    if (!icd11ectConfigure(rt)) return cleanup;
+    if (needsConfigure) {
+      /* configure() resets every search box on the page, rebind them all. */
+      icd11ectBindAll(rt);
+    } else {
+      icd11ectApplyInstance(rt, key, cleanSettings);
+      icd11ectBind(rt, key);
+    }
+    return cleanup;
+  }, [key, settingsKey]);
+};
+"""
+
+#: The JavaScript emitted once per page by every ICD-11 ECT component.
+ICD11ECT_RUNTIME_JS: str = _RUNTIME_TEMPLATE.replace(
+    "__OVERWRITABLE__", json.dumps(list(OVERWRITABLE_SETTINGS))
+).strip()

reflex_icd11ect/constants.py

@@ -0,0 +1,194 @@
+"""Constants and setting maps for the ICD-11 Embedded Classification Tools.
+
+Every entry of the ``*_SETTINGS`` maps below is ``python_prop_name ->
+ECT setting name``. They are the single source of truth used to build the
+JavaScript settings object handed to ``ECT.Handler.configure`` and
+``ECT.Handler.overwriteConfiguration``.
+
+The names were verified against the ``@whoicd/icd11ect`` 1.8.0 bundle
+(the ``Handler.configure`` implementation) and the WHO documentation for
+ECT 1.5 through 1.8.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+#: Public WHO ICD-API cloud server. Requires OAUTH 2.0 (``api_secured=True``).
+WHO_CLOUD_API: Final[str] = "https://id.who.int"
+
+#: WHO test server for software development only. No authentication needed.
+#: Do not use it in production; it is rate limited and may go away.
+WHO_DEVELOPER_TEST_API: Final[str] = (
+    "https://icd11restapi-developer-test.azurewebsites.net"
+)
+
+#: OAUTH 2.0 token endpoint of the ICD-API access management service.
+ICD_TOKEN_ENDPOINT: Final[str] = "https://icdaccessmanagement.who.int/connect/token"
+
+#: OAUTH 2.0 scope required by the ICD-API.
+ICD_TOKEN_SCOPE: Final[str] = "icdapi_access"
+
+#: npm package wrapped by this component.
+ECT_PACKAGE: Final[str] = "@whoicd/icd11ect"
+
+#: npm version range installed in the frontend. ECT is released as
+#: ``1.x`` with occasional breaking changes in the minor, so it is pinned
+#: to the tested minor version.
+ECT_VERSION: Final[str] = "1.8"
+
+#: Stylesheet shipped by the npm package; required for the tools to look right.
+ECT_STYLESHEET: Final[str] = f"{ECT_PACKAGE}/style.css"
+
+# --------------------------------------------------------------------------- #
+# Settings
+# --------------------------------------------------------------------------- #
+
+#: Settings shared by the Embedded Coding Tool and the Embedded Browser.
+COMMON_SETTINGS: Final[dict[str, str]] = {
+    "api_server_url": "apiServerUrl",
+    "api_secured": "apiSecured",
+    "source": "source",
+    "minor_version": "minorVersion",
+    "language": "language",
+    "source_app": "sourceApp",
+    "height": "height",
+    "hierarchy_title": "hierarchyTitle",
+    "hierarchy_resizable": "hierarchyResizable",
+    "other_postcoordination": "otherPostcoordination",
+    "enable_keyboard": "enableKeyboard",
+    "include_diagnostic_criteria": "includeDiagnosticCriteria",
+    "verbose": "verbose",
+}
+
+#: Settings that only affect the Embedded Coding Tool.
+CODING_TOOL_SETTINGS: Final[dict[str, str]] = {
+    "popup_mode": "popupMode",
+    "simplified_mode": "simplifiedMode",
+    "disable_hierarchy": "disableHierarchy",
+    "words_available": "wordsAvailable",
+    "chapters_available": "chaptersAvailable",
+    "chapters_filter": "chaptersFilter",
+    "subtrees_filter": "subtreesFilter",
+    "flexisearch_available": "flexisearchAvailable",
+    "search_by_code_or_uri": "searchByCodeOrURI",
+    "medical_coding_mode": "medicalCodingMode",
+    "view_selected_uri": "viewSelectedURI",
+}
+
+#: Settings that only affect the Embedded Browser.
+BROWSER_SETTINGS: Final[dict[str, str]] = {
+    "enable_select_button": "enableSelectButton",
+    "browser_search_available": "browserSearchAvailable",
+    "browser_advanced_search_available": "browserAdvancedSearchAvailable",
+    "browser_hierarchy_available": "browserHierarchyAvailable",
+    "browser_hierarchy_root_uris": "browserHierarchyRootURIs",
+    "browser_uri": "browserURI",
+    "display_other_foundation_children": "displayOtherFoundationChildren",
+}
+
+#: Every setting understood by ECT, python name -> ECT name.
+ALL_SETTINGS: Final[dict[str, str]] = {
+    **COMMON_SETTINGS,
+    **CODING_TOOL_SETTINGS,
+    **BROWSER_SETTINGS,
+}
+
+#: Settings that ``ECT.Handler.overwriteConfiguration`` can change for a
+#: single instance. Anything else is global to the page and is applied
+#: through ``ECT.Handler.configure``.
+OVERWRITABLE_SETTINGS: Final[tuple[str, ...]] = (
+    "apiServerUrl",
+    "apiSecured",
+    "source",
+    "minorVersion",
+    "language",
+    "popupMode",
+    "simplifiedMode",
+    "disableHierarchy",
+    "wordsAvailable",
+    "chaptersAvailable",
+    "chaptersFilter",
+    "subtreesFilter",
+    "flexisearchAvailable",
+    "searchByCodeOrURI",
+    "hierarchyTitle",
+    "height",
+)
+
+# --------------------------------------------------------------------------- #
+# Enumerations (plain strings, so they stay usable from rx.Var)
+# --------------------------------------------------------------------------- #
+
+#: ``source`` values. ``mms`` is the ICD-11 MMS linearization, ``icf`` the
+#: International Classification of Functioning (ECT >= 1.7), ``foundation``
+#: the ICD-11 Foundation (Embedded Browser only).
+SOURCE_MMS: Final[str] = "mms"
+SOURCE_ICF: Final[str] = "icf"
+SOURCE_FOUNDATION: Final[str] = "foundation"
+SOURCES: Final[tuple[str, ...]] = (SOURCE_MMS, SOURCE_ICF, SOURCE_FOUNDATION)
+
+#: ``enable_select_button`` values for the Embedded Browser.
+SELECT_BUTTON_NONE: Final[str] = "none"
+SELECT_BUTTON_CATEGORIES: Final[str] = "categories"
+SELECT_BUTTON_ALL: Final[str] = "all"
+SELECT_BUTTON_ALL_BUT_ROOT: Final[str] = "allButRoot"
+SELECT_BUTTON_MODES: Final[tuple[str, ...]] = (
+    SELECT_BUTTON_NONE,
+    SELECT_BUTTON_CATEGORIES,
+    SELECT_BUTTON_ALL,
+    SELECT_BUTTON_ALL_BUT_ROOT,
+)
+
+#: Languages the ICD-11 API serves, ISO 639-1 code -> English name.
+#: Availability depends on the release and on the server deployment.
+LANGUAGES: Final[dict[str, str]] = {
+    "ar": "Arabic",
+    "cs": "Czech",
+    "en": "English",
+    "es": "Spanish",
+    "fr": "French",
+    "it": "Italian",
+    "ja": "Japanese",
+    "ko": "Korean",
+    "pt": "Portuguese",
+    "ru": "Russian",
+    "tr": "Turkish",
+    "uz": "Uzbek",
+    "zh": "Chinese",
+}
+
+#: Languages written right to left. ECT adds the ``rtl`` class for these.
+RTL_LANGUAGES: Final[tuple[str, ...]] = ("ar", "he")
+
+#: ICD-11 MMS chapters, code -> title. Use the keys with ``chapters_filter``.
+MMS_CHAPTERS: Final[dict[str, str]] = {
+    "01": "Certain infectious or parasitic diseases",
+    "02": "Neoplasms",
+    "03": "Diseases of the blood or blood-forming organs",
+    "04": "Diseases of the immune system",
+    "05": "Endocrine, nutritional or metabolic diseases",
+    "06": "Mental, behavioural or neurodevelopmental disorders",
+    "07": "Sleep-wake disorders",
+    "08": "Diseases of the nervous system",
+    "09": "Diseases of the visual system",
+    "10": "Diseases of the ear or mastoid process",
+    "11": "Diseases of the circulatory system",
+    "12": "Diseases of the respiratory system",
+    "13": "Diseases of the digestive system",
+    "14": "Diseases of the skin",
+    "15": "Diseases of the musculoskeletal system or connective tissue",
+    "16": "Diseases of the genitourinary system",
+    "17": "Conditions related to sexual health",
+    "18": "Pregnancy, childbirth or the puerperium",
+    "19": "Certain conditions originating in the perinatal period",
+    "20": "Developmental anomalies",
+    "21": "Symptoms, signs or clinical findings, not elsewhere classified",
+    "22": "Injury, poisoning or certain other consequences of external causes",
+    "23": "External causes of morbidity or mortality",
+    "24": "Factors influencing health status or contact with health services",
+    "25": "Codes for special purposes",
+    "26": "Supplementary Chapter Traditional Medicine Conditions - Module I",
+    "V": "Supplementary section for functioning assessment",
+    "X": "Extension Codes",
+}