@openmrs/esm-framework 10.0.1-pre.5263 → 10.0.1-pre.5299

package/docs/interfaces/ExtensionStore.md

@@ -2,7 +2,7 @@
 
 # Interface: ExtensionStore
 
-Defined in: [packages/framework/esm-extensions/src/store.ts:67](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-extensions/src/store.ts#L67)
+Defined in: [packages/framework/esm-extensions/src/store.ts:99](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-extensions/src/store.ts#L99)
 
 ## Properties
 
@@ -10,4 +10,4 @@ Defined in: [packages/framework/esm-extensions/src/store.ts:67](https://github.c
 
 > **slots**: `Record`\<`string`, [`ExtensionSlotState`](ExtensionSlotState.md)\>
 
-Defined in: [packages/framework/esm-extensions/src/store.ts:68](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-extensions/src/store.ts#L68)
+Defined in: [packages/framework/esm-extensions/src/store.ts:100](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-extensions/src/store.ts#L100)

package/docs/type-aliases/ExtensionSlotCustomState.md

@@ -0,0 +1,11 @@
+[O3 Framework](../API.md) / ExtensionSlotCustomState
+
+# Type Alias: ExtensionSlotCustomState
+
+> **ExtensionSlotCustomState** = `Record`\<`string`, `unknown`\> \| `undefined`
+
+Defined in: [packages/framework/esm-extensions/src/store.ts:80](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-extensions/src/store.ts#L80)
+
+The state one rendering of a slot is displaying, which its extensions' display conditions are
+evaluated against. Each key becomes a variable of that name in the expression, so only string
+keys are reachable from a condition.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-framework",
-  "version": "10.0.1-pre.5263",
+  "version": "10.0.1-pre.5299",
   "license": "MPL-2.0",
   "type": "module",
   "module": "dist/index.js",
@@ -60,24 +60,24 @@
     "access": "public"
   },
   "dependencies": {
-    "@openmrs/esm-api": "10.0.1-pre.5263",
-    "@openmrs/esm-config": "10.0.1-pre.5263",
-    "@openmrs/esm-context": "10.0.1-pre.5263",
-    "@openmrs/esm-dynamic-loading": "10.0.1-pre.5263",
-    "@openmrs/esm-emr-api": "10.0.1-pre.5263",
-    "@openmrs/esm-error-handling": "10.0.1-pre.5263",
-    "@openmrs/esm-expression-evaluator": "10.0.1-pre.5263",
-    "@openmrs/esm-extensions": "10.0.1-pre.5263",
-    "@openmrs/esm-feature-flags": "10.0.1-pre.5263",
-    "@openmrs/esm-globals": "10.0.1-pre.5263",
-    "@openmrs/esm-navigation": "10.0.1-pre.5263",
-    "@openmrs/esm-offline": "10.0.1-pre.5263",
-    "@openmrs/esm-react-utils": "10.0.1-pre.5263",
-    "@openmrs/esm-routes": "10.0.1-pre.5263",
-    "@openmrs/esm-state": "10.0.1-pre.5263",
-    "@openmrs/esm-styleguide": "10.0.1-pre.5263",
-    "@openmrs/esm-translations": "10.0.1-pre.5263",
-    "@openmrs/esm-utils": "10.0.1-pre.5263"
+    "@openmrs/esm-api": "10.0.1-pre.5299",
+    "@openmrs/esm-config": "10.0.1-pre.5299",
+    "@openmrs/esm-context": "10.0.1-pre.5299",
+    "@openmrs/esm-dynamic-loading": "10.0.1-pre.5299",
+    "@openmrs/esm-emr-api": "10.0.1-pre.5299",
+    "@openmrs/esm-error-handling": "10.0.1-pre.5299",
+    "@openmrs/esm-expression-evaluator": "10.0.1-pre.5299",
+    "@openmrs/esm-extensions": "10.0.1-pre.5299",
+    "@openmrs/esm-feature-flags": "10.0.1-pre.5299",
+    "@openmrs/esm-globals": "10.0.1-pre.5299",
+    "@openmrs/esm-navigation": "10.0.1-pre.5299",
+    "@openmrs/esm-offline": "10.0.1-pre.5299",
+    "@openmrs/esm-react-utils": "10.0.1-pre.5299",
+    "@openmrs/esm-routes": "10.0.1-pre.5299",
+    "@openmrs/esm-state": "10.0.1-pre.5299",
+    "@openmrs/esm-styleguide": "10.0.1-pre.5299",
+    "@openmrs/esm-translations": "10.0.1-pre.5299",
+    "@openmrs/esm-utils": "10.0.1-pre.5299"
   },
   "peerDependencies": {
     "dayjs": "1.x",
@@ -90,7 +90,7 @@
     "swr": "2.x"
   },
   "devDependencies": {
-    "@openmrs/typedoc-plugin-file-categories": "10.0.1-pre.5263",
+    "@openmrs/typedoc-plugin-file-categories": "10.0.1-pre.5299",
     "@swc/cli": "0.8.1",
     "@swc/core": "1.15.21",
     "@vitest/coverage-v8": "^4.1.2",

package/src/integration-tests/extension-config-expressions.test.tsx

@@ -2,10 +2,15 @@
 import React from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import '@testing-library/jest-dom/vitest';
-import { act, cleanup, render, screen, waitFor } from '@testing-library/react';
+import { act, cleanup, render, screen, waitFor, within } from '@testing-library/react';
 import { type Person } from '@openmrs/esm-api';
 import { mockSessionStore } from '@openmrs/esm-api/mock';
-import { attach, registerExtension, updateInternalExtensionStore } from '../../../esm-extensions/src';
+import {
+  attach,
+  getExtensionRenderingsStore,
+  registerExtension,
+  updateInternalExtensionStore,
+} from '../../../esm-extensions/src';
 import { ExtensionSlot, getSyncLifecycle, openmrsComponentDecorator, useConfig } from '../../../esm-react-utils/src';
 import {
   configInternalStore,
@@ -41,6 +46,10 @@ vi.mock('@openmrs/esm-api', async () => {
  */
 describe('Expression evaluation in extension display conditions', () => {
   beforeEach(() => {
+    // A rendering outliving its module's schema makes the config system derive a config for an
+    // extension this test never registered.
+    // eslint-disable-next-line testing-library/no-render-in-lifecycle -- not a render; the rule matches any callee name containing "render"
+    getExtensionRenderingsStore().setState({ renderings: new Map() });
     temporaryConfigStore.setState({ config: {} });
     configInternalStore.setState({ providedConfigs: [], schemas: {}, moduleLoaded: {} });
     mockSessionStore.setState({});
@@ -224,6 +233,59 @@ describe('Expression evaluation in extension display conditions', () => {
       expect(slot.firstChild).toBeNull();
     });
   }, 10000);
+
+  it('evaluates a display condition against each rendering of a slot', async () => {
+    registerExtension({
+      name: 'Always',
+      moduleName: 'esm-bedrock',
+      load: getSyncLifecycle(() => <div>Always</div>, {
+        moduleName: 'esm-bedrock',
+        featureName: 'Bedrock',
+        disableTranslations: true,
+      }),
+      meta: {},
+    });
+    registerExtension({
+      name: 'Flagged',
+      moduleName: 'esm-bedrock',
+      load: getSyncLifecycle(() => <div>Flagged</div>, {
+        moduleName: 'esm-bedrock',
+        featureName: 'Bedrock',
+        disableTranslations: true,
+      }),
+      meta: {},
+      displayExpression: 'patient.flagged',
+    });
+    attach('rows-slot', 'Always');
+    attach('rows-slot', 'Flagged');
+
+    // A virtualized list renders the same slot once per row, each with its own patient. The slot
+    // is not "a place on the screen" here, so the condition has to be evaluated per rendering.
+    const Rows = openmrsComponentDecorator({
+      moduleName: 'esm-bedrock',
+      featureName: 'Bedrock',
+      disableTranslations: true,
+    })(() => (
+      <div>
+        <div data-testid="row-flagged">
+          <ExtensionSlot name="rows-slot" state={{ patient: { flagged: true } }} />
+        </div>
+        <div data-testid="row-plain">
+          <ExtensionSlot name="rows-slot" state={{ patient: { flagged: false } }} />
+        </div>
+      </div>
+    ));
+
+    await act(async () => {
+      render(<Rows />);
+    });
+
+    await waitFor(() => expect(within(screen.getByTestId('row-flagged')).getByText('Always')).toBeInTheDocument());
+
+    expect(within(screen.getByTestId('row-flagged')).getByText('Flagged')).toBeInTheDocument();
+    expect(within(screen.getByTestId('row-plain')).getByText('Always')).toBeInTheDocument();
+    expect(within(screen.getByTestId('row-plain')).queryByText('Flagged')).not.toBeInTheDocument();
+  }, 10000);
 });
 
 async function registerSimpleExtension(

package/src/integration-tests/extension-config-propagation.test.tsx

@@ -0,0 +1,185 @@
+/* eslint-disable testing-library/no-unnecessary-act, testing-library/no-manual-cleanup */
+import React from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { act, cleanup, render, screen, waitFor } from '@testing-library/react';
+import { mockSessionStore } from '@openmrs/esm-api/mock';
+import {
+  attach,
+  getExtensionRenderingsStore,
+  registerExtension,
+  updateInternalExtensionStore,
+} from '../../../esm-extensions/src';
+import { ExtensionSlot, getSyncLifecycle, openmrsComponentDecorator } from '../../../esm-react-utils/src';
+import {
+  configExtensionStore,
+  configInternalStore,
+  defineConfigSchema,
+  getExtensionSlotsConfigStore,
+  getExtensionsConfigStore,
+  provide,
+  registerModuleLoad,
+  resetConfigSystem,
+  temporaryConfigStore,
+} from '../../../esm-config/src';
+
+vi.mock('@openmrs/esm-api', async () => {
+  const original = await import('@openmrs/esm-api');
+  return { ...original, sessionStore: mockSessionStore, refetchCurrentUser: vi.fn() };
+});
+
+const moduleName = 'esm-flintstone';
+
+function reg(name: string) {
+  registerExtension({
+    name,
+    moduleName,
+    load: getSyncLifecycle(() => <div>{name}</div>, { moduleName, featureName: name }),
+    meta: {},
+    online: true,
+    offline: true,
+  });
+}
+
+/**
+ * Slots are recomputed only when an input that affects them changes, so a slot's configuration
+ * changing has to invalidate that slot. These cover the case the pre-existing config tests don't:
+ * the configuration changing *after* the slot has already rendered, which is what an implementer
+ * does from the implementer tools.
+ */
+describe('runtime slot config changes', () => {
+  beforeEach(() => {
+    // eslint-disable-next-line testing-library/no-render-in-lifecycle -- not a render; the rule matches any callee name containing "render"
+    getExtensionRenderingsStore().setState({ renderings: new Map() });
+    temporaryConfigStore.setState({ config: {} });
+    configInternalStore.setState({ providedConfigs: [], schemas: {}, moduleLoaded: {} });
+    mockSessionStore.setState({});
+    getExtensionSlotsConfigStore().setState({ slots: {} });
+    getExtensionsConfigStore().setState({ configs: {} });
+    configExtensionStore.setState({ mountedExtensions: [] });
+    updateInternalExtensionStore(() => ({ slots: {}, extensions: {} }));
+    resetConfigSystem();
+    defineConfigSchema(moduleName, {});
+    registerModuleLoad(moduleName);
+    cleanup();
+  });
+
+  async function renderSlot() {
+    const App = openmrsComponentDecorator({ moduleName, featureName: 'f', disableTranslations: true })(() => (
+      <ExtensionSlot data-testid="slot" name="cfg-slot" />
+    ));
+    await act(async () => {
+      render(<App />);
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 20));
+    });
+  }
+
+  function rendered() {
+    return Array.from(screen.getByTestId('slot').childNodes).map((n) => (n as HTMLElement).textContent);
+  }
+
+  // Polls rather than sleeping: the cascade from a config write to the DOM runs across several
+  // store updates and a parcel mount, which is not a fixed amount of wall-clock time.
+  async function expectRendered(expected: Array<string | null>) {
+    await waitFor(() => expect(rendered()).toEqual(expected));
+  }
+
+  it('ADD: config adding an extension after the slot is mounted shows it', async () => {
+    reg('Fred');
+    reg('Barney');
+    attach('cfg-slot', 'Fred');
+    await renderSlot();
+    await expectRendered(['Fred']);
+
+    await act(async () => {
+      provide({ [moduleName]: { extensionSlots: { 'cfg-slot': { add: ['Barney'] } } } });
+    });
+    await expectRendered(['Fred', 'Barney']);
+  });
+
+  it('REMOVE: config removing an extension after the slot is mounted hides it', async () => {
+    reg('Fred');
+    reg('Wilma');
+    attach('cfg-slot', 'Fred');
+    attach('cfg-slot', 'Wilma');
+    await renderSlot();
+    await expectRendered(['Fred', 'Wilma']);
+
+    await act(async () => {
+      provide({ [moduleName]: { extensionSlots: { 'cfg-slot': { remove: ['Fred'] } } } });
+    });
+    await expectRendered(['Wilma']);
+  });
+
+  it('ORDER: config reordering after the slot is mounted reorders the DOM', async () => {
+    reg('Fred');
+    reg('Wilma');
+    attach('cfg-slot', 'Fred');
+    attach('cfg-slot', 'Wilma');
+    await renderSlot();
+    await expectRendered(['Fred', 'Wilma']);
+
+    await act(async () => {
+      provide({ [moduleName]: { extensionSlots: { 'cfg-slot': { order: ['Wilma', 'Fred'] } } } });
+    });
+    await expectRendered(['Wilma', 'Fred']);
+  });
+
+  it('TEMPORARY CONFIG: implementer-tools style change propagates', async () => {
+    reg('Fred');
+    reg('Barney');
+    attach('cfg-slot', 'Fred');
+    await renderSlot();
+    await expectRendered(['Fred']);
+
+    await act(async () => {
+      temporaryConfigStore.setState({
+        config: { [moduleName]: { extensionSlots: { 'cfg-slot': { add: ['Barney'] } } } },
+      });
+    });
+    await expectRendered(['Fred', 'Barney']);
+  });
+
+  it('CLEARED: clearing the temporary config reverts the slot to its unconfigured state', async () => {
+    reg('Fred');
+    reg('Barney');
+    attach('cfg-slot', 'Fred');
+    await renderSlot();
+
+    await act(async () => {
+      temporaryConfigStore.setState({
+        config: { [moduleName]: { extensionSlots: { 'cfg-slot': { add: ['Barney'] } } } },
+      });
+    });
+    await expectRendered(['Fred', 'Barney']);
+
+    // What the implementer tools' "clear temporary config" does. The slot loses its config
+    // entry entirely, which has to take effect without a page reload.
+    await act(async () => {
+      temporaryConfigStore.setState({ config: {} });
+    });
+    await expectRendered(['Fred']);
+  });
+
+  it('REPEATED: a second config change after the first still propagates', async () => {
+    reg('Fred');
+    reg('Barney');
+    reg('Betty');
+    attach('cfg-slot', 'Fred');
+    await renderSlot();
+
+    await act(async () => {
+      provide({ [moduleName]: { extensionSlots: { 'cfg-slot': { add: ['Barney'] } } } });
+    });
+    await expectRendered(['Fred', 'Barney']);
+
+    await act(async () => {
+      provide({ [moduleName]: { extensionSlots: { 'cfg-slot': { add: ['Barney', 'Betty'] } } } });
+    });
+    // Two config-`add`ed extensions with no explicit order come out in the order the
+    // configuration lists them.
+    await expectRendered(['Fred', 'Barney', 'Betty']);
+  });
+});

package/src/integration-tests/extension-config.test.tsx

@@ -5,7 +5,12 @@ import '@testing-library/jest-dom/vitest';
 import { act, cleanup, render, screen, waitFor } from '@testing-library/react';
 import { type Person } from '@openmrs/esm-api';
 import { mockSessionStore } from '@openmrs/esm-api/mock';
-import { attach, registerExtension, updateInternalExtensionStore } from '../../../esm-extensions/src';
+import {
+  attach,
+  getExtensionRenderingsStore,
+  registerExtension,
+  updateInternalExtensionStore,
+} from '../../../esm-extensions/src';
 import {
   ExtensionSlot,
   getSyncLifecycle,
@@ -36,6 +41,10 @@ vi.mock('@openmrs/esm-api', async () => {
 
 describe('Interaction between configuration and extension systems', () => {
   beforeEach(() => {
+    // A rendering outliving its module's schema makes the config system derive a config for an
+    // extension this test never registered.
+    // eslint-disable-next-line testing-library/no-render-in-lifecycle -- not a render; the rule matches any callee name containing "render"
+    getExtensionRenderingsStore().setState({ renderings: new Map() });
     temporaryConfigStore.setState({ config: {} });
     configInternalStore.setState({ providedConfigs: [], schemas: {}, moduleLoaded: {} });
     mockSessionStore.setState({});
@@ -187,6 +196,52 @@ describe('Interaction between configuration and extension systems', () => {
     });
   });
 
+  it('Should give each extension instance its own config in every rendering of the slot', async () => {
+    registerSimpleExtension('obs', 'esm-widgets', true);
+    defineConfigSchema('esm-widgets', {
+      concept: { _type: Type.String, _default: '(none)' },
+    });
+    registerModuleLoad('esm-widgets');
+
+    attach('Vitals slot', 'obs#weight');
+    attach('Vitals slot', 'obs#height');
+    provide({
+      'esm-chart': {
+        extensionSlots: {
+          'Vitals slot': {
+            configure: {
+              'obs#weight': { concept: 'Weight (kg)' },
+              'obs#height': { concept: 'Height (cm)' },
+            },
+          },
+        },
+      },
+    });
+
+    const App = openmrsComponentDecorator({
+      moduleName: 'esm-chart',
+      featureName: 'The chart',
+      disableTranslations: true,
+    })(() => (
+      <>
+        <ExtensionSlot data-testid="row-1" name="Vitals slot" />
+        <ExtensionSlot data-testid="row-2" name="Vitals slot" />
+      </>
+    ));
+
+    act(() => {
+      render(<App />);
+    });
+
+    await waitFor(() => {
+      for (const testId of ['row-1', 'row-2']) {
+        const slot = screen.getByTestId(testId);
+        expect(slot.firstChild).toHaveTextContent(/Weight \(kg\)/);
+        expect(slot.lastChild).toHaveTextContent(/Height \(cm\)/);
+      }
+    });
+  });
+
   it('Slot config should update with temporary config', async () => {
     registerSimpleExtension('Pearl', 'esm-slaghoople');
     attach('A slot', 'Pearl');
@@ -272,7 +327,7 @@ describe('Interaction between configuration and extension systems', () => {
       return (
         <div>
           <ExtensionSlot data-testid="slot" name="A slot" />
-          {store.slots['A slot'].assignedExtensions.map((e) => (
+          {store.slots['A slot'].candidateExtensions.map((e) => (
             <div key={e.name}>{JSON.stringify(e.config)}</div>
           ))}
         </div>