|
| 1 | +## Purpose |
| 2 | + |
| 3 | +Defines requirements for reactive API key resolution in the Maps widget via MobX computed atoms with caching. |
| 4 | + |
| 5 | +## Requirements |
| 6 | + |
| 7 | +### Requirement: API key resolved via computed atom |
| 8 | + |
| 9 | +The Maps container SHALL provide a `ComputedAtom<string | null>` that reactively resolves the API key from widget props. |
| 10 | + |
| 11 | +#### Scenario: Expression value takes priority |
| 12 | + |
| 13 | +- **WHEN** `apiKeyExp.value` is a non-empty string |
| 14 | +- **THEN** the atom returns that value |
| 15 | + |
| 16 | +#### Scenario: Falls back to static apiKey |
| 17 | + |
| 18 | +- **WHEN** `apiKeyExp.value` is undefined or empty |
| 19 | +- **AND** `apiKey` is a non-empty string |
| 20 | +- **THEN** the atom returns the static `apiKey` value |
| 21 | + |
| 22 | +#### Scenario: Returns null when no key available |
| 23 | + |
| 24 | +- **WHEN** both `apiKeyExp.value` and `apiKey` are empty or undefined |
| 25 | +- **THEN** the atom returns `null` |
| 26 | + |
| 27 | +### Requirement: API key cached once resolved |
| 28 | + |
| 29 | +Once the atom returns a non-null value, it SHALL cache that value permanently and never revert to `null`. |
| 30 | + |
| 31 | +#### Scenario: Key remains after expression becomes unavailable |
| 32 | + |
| 33 | +- **WHEN** the atom has previously returned a non-null value |
| 34 | +- **AND** `apiKeyExp.value` subsequently becomes undefined |
| 35 | +- **THEN** the atom still returns the previously cached value |
| 36 | + |
| 37 | +### Requirement: API key atom registered in DI container |
| 38 | + |
| 39 | +The atom SHALL be registered as a `CORE_TOKENS.apiKey` token in the Maps container and injectable into services. |
| 40 | + |
| 41 | +#### Scenario: LocationResolverService uses atom |
| 42 | + |
| 43 | +- **WHEN** `LocationResolverService` needs the API key for geocoding |
| 44 | +- **THEN** it reads from the injected `ComputedAtom<string | null>` via `.get()` |
| 45 | + |
| 46 | +### Requirement: Geodecode API key resolved via computed atom |
| 47 | + |
| 48 | +The Maps container SHALL provide a `ComputedAtom<string | null>` that reactively resolves the geodecode API key from widget props, following the same pattern as the main API key atom. |
| 49 | + |
| 50 | +#### Scenario: Expression value takes priority |
| 51 | + |
| 52 | +- **WHEN** `geodecodeApiKeyExp.value` is a non-empty string |
| 53 | +- **THEN** the atom returns that value |
| 54 | + |
| 55 | +#### Scenario: Falls back to static geodecodeApiKey |
| 56 | + |
| 57 | +- **WHEN** `geodecodeApiKeyExp.value` is undefined or empty |
| 58 | +- **AND** `geodecodeApiKey` is a non-empty string |
| 59 | +- **THEN** the atom returns the static `geodecodeApiKey` value |
| 60 | + |
| 61 | +#### Scenario: Returns null when no key available |
| 62 | + |
| 63 | +- **WHEN** both `geodecodeApiKeyExp.value` and `geodecodeApiKey` are empty or undefined |
| 64 | +- **THEN** the atom returns `null` |
| 65 | + |
| 66 | +### Requirement: Geodecode API key cached once resolved |
| 67 | + |
| 68 | +Once the geodecode atom returns a non-null value, it SHALL cache that value permanently and never revert to `null`. |
| 69 | + |
| 70 | +#### Scenario: Key remains after expression becomes unavailable |
| 71 | + |
| 72 | +- **WHEN** the atom has previously returned a non-null value |
| 73 | +- **AND** `geodecodeApiKeyExp.value` subsequently becomes undefined |
| 74 | +- **THEN** the atom still returns the previously cached value |
| 75 | + |
| 76 | +### Requirement: apiKey and geodecodeApiKey removed from MapsConfig |
| 77 | + |
| 78 | +The static `MapsConfig` interface SHALL NOT contain `apiKey` or `geodecodeApiKey` fields. Both keys are resolved reactively via atoms. |
| 79 | + |
| 80 | +#### Scenario: MapsConfig only contains static fields |
| 81 | + |
| 82 | +- **WHEN** `mapsConfig()` is called |
| 83 | +- **THEN** the returned object contains `id`, `name`, and `showCurrentLocation` only |
0 commit comments