@equinor/fusion-framework-module-context 7.0.4-next.0 → 8.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/CHANGELOG.md +36 -15
  2. package/README.md +168 -16
  3. package/dist/esm/ContextConfigBuilder.js +24 -6
  4. package/dist/esm/ContextConfigBuilder.js.map +1 -1
  5. package/dist/esm/ContextProvider.js +71 -15
  6. package/dist/esm/ContextProvider.js.map +1 -1
  7. package/dist/esm/client/ContextClient.js +13 -3
  8. package/dist/esm/client/ContextClient.js.map +1 -1
  9. package/dist/esm/configurator.js +40 -5
  10. package/dist/esm/configurator.js.map +1 -1
  11. package/dist/esm/{errors.js → errors/FusionContextSearchError.js} +3 -1
  12. package/dist/esm/errors/FusionContextSearchError.js.map +1 -0
  13. package/dist/esm/errors/index.js +2 -0
  14. package/dist/esm/errors/index.js.map +1 -0
  15. package/dist/esm/get-context-selector.js +14 -0
  16. package/dist/esm/get-context-selector.js.map +1 -0
  17. package/dist/esm/index.js +12 -0
  18. package/dist/esm/index.js.map +1 -1
  19. package/dist/esm/module.js +6 -0
  20. package/dist/esm/module.js.map +1 -1
  21. package/dist/esm/parse-context-item.js +31 -0
  22. package/dist/esm/parse-context-item.js.map +1 -0
  23. package/dist/esm/query-context-selector.js +12 -0
  24. package/dist/esm/query-context-selector.js.map +1 -0
  25. package/dist/esm/related-context-selector.js +12 -0
  26. package/dist/esm/related-context-selector.js.map +1 -0
  27. package/dist/esm/utils/extract-context-id-from-path.js +25 -0
  28. package/dist/esm/utils/extract-context-id-from-path.js.map +1 -0
  29. package/dist/esm/utils/index.js +10 -0
  30. package/dist/esm/utils/index.js.map +1 -1
  31. package/dist/esm/utils/resolve-context-from-path.js +11 -22
  32. package/dist/esm/utils/resolve-context-from-path.js.map +1 -1
  33. package/dist/esm/utils/resolve-initial-context.js +2 -0
  34. package/dist/esm/utils/resolve-initial-context.js.map +1 -1
  35. package/dist/esm/version.js +1 -1
  36. package/dist/esm/version.js.map +1 -1
  37. package/dist/tsconfig.tsbuildinfo +1 -1
  38. package/dist/types/ContextConfigBuilder.d.ts +31 -1
  39. package/dist/types/ContextProvider.d.ts +74 -3
  40. package/dist/types/client/ContextClient.d.ts +8 -1
  41. package/dist/types/configurator.d.ts +134 -4
  42. package/dist/types/{errors.d.ts → errors/FusionContextSearchError.d.ts} +2 -0
  43. package/dist/types/errors/index.d.ts +1 -0
  44. package/dist/types/get-context-selector.d.ts +9 -0
  45. package/dist/types/index.d.ts +12 -0
  46. package/dist/types/module.d.ts +11 -0
  47. package/dist/types/parse-context-item.d.ts +8 -0
  48. package/dist/types/query-context-selector.d.ts +7 -0
  49. package/dist/types/related-context-selector.d.ts +7 -0
  50. package/dist/types/types.d.ts +23 -1
  51. package/dist/types/utils/extract-context-id-from-path.d.ts +16 -0
  52. package/dist/types/utils/index.d.ts +10 -0
  53. package/dist/types/utils/resolve-context-from-path.d.ts +1 -16
  54. package/dist/types/utils/resolve-initial-context.d.ts +1 -1
  55. package/dist/types/version.d.ts +1 -1
  56. package/package.json +12 -12
  57. package/src/ContextConfigBuilder.ts +47 -7
  58. package/src/ContextProvider.ts +115 -28
  59. package/src/client/ContextClient.ts +13 -3
  60. package/src/configurator.ts +152 -10
  61. package/src/{errors.ts → errors/FusionContextSearchError.ts} +2 -0
  62. package/src/errors/index.ts +1 -0
  63. package/src/get-context-selector.ts +18 -0
  64. package/src/index.ts +13 -0
  65. package/src/module.ts +11 -0
  66. package/src/parse-context-item.ts +39 -0
  67. package/src/query-context-selector.ts +15 -0
  68. package/src/related-context-selector.ts +15 -0
  69. package/src/types.ts +23 -1
  70. package/src/utils/extract-context-id-from-path.ts +30 -0
  71. package/src/utils/index.ts +10 -0
  72. package/src/utils/resolve-context-from-path.ts +13 -28
  73. package/src/utils/resolve-initial-context.ts +2 -0
  74. package/src/version.ts +1 -1
  75. package/dist/esm/errors.js.map +0 -1
  76. package/dist/esm/selectors.js +0 -58
  77. package/dist/esm/selectors.js.map +0 -1
  78. package/dist/types/selectors.d.ts +0 -19
  79. package/src/selectors.ts +0 -70
@@ -3,6 +3,14 @@ import type { QueryCtorOptions, QueryFn } from '@equinor/fusion-query';
3
3
  import type { GetContextParameters } from './client/ContextClient';
4
4
  import type { ContextModuleConfig, ContextModuleConfigurator, IContextModuleConfigurator } from './configurator';
5
5
  import type { ContextItem, QueryContextParameters, RelatedContextParameters } from './types';
6
+ /**
7
+ * Callback passed to {@link IContextModuleConfigurator.addConfigBuilder}.
8
+ *
9
+ * Receives a {@link ContextConfigBuilder} and may use its setter methods
10
+ * to populate the context module configuration. The callback may be async.
11
+ *
12
+ * @typeParam TDeps - Module dependency array inferred from the configurator.
13
+ */
6
14
  export type ContextConfigBuilderCallback = <TDeps extends Array<AnyModule> = []>(builder: ContextConfigBuilder<TDeps, ModuleInitializerArgs<IContextModuleConfigurator, TDeps>>) => void | Promise<void>;
7
15
  /**
8
16
  * A builder class for configuring and customizing context module behavior within the Fusion Framework.
@@ -27,7 +35,7 @@ export type ContextConfigBuilderCallback = <TDeps extends Array<AnyModule> = []>
27
35
  * - The builder pattern allows chaining configuration methods for clarity and convenience.
28
36
  * - The `requireInstance` method enables asynchronous retrieval of module instances by name.
29
37
  *
30
- * @todo - this should extend the BaseConfigBuilder
38
+ * @todo(#5120) - this should extend the BaseConfigBuilder
31
39
  *
32
40
  * @see ContextModuleConfig
33
41
  * @see ModuleInitializerArgs
@@ -35,8 +43,23 @@ export type ContextConfigBuilderCallback = <TDeps extends Array<AnyModule> = []>
35
43
  export declare class ContextConfigBuilder<TModules extends Array<AnyModule> = [], TInit extends ModuleInitializerArgs<any, any> = ModuleInitializerArgs<ContextModuleConfigurator, TModules>> {
36
44
  #private;
37
45
  config: Partial<ContextModuleConfig>;
46
+ /**
47
+ * Creates a new `ContextConfigBuilder`.
48
+ * @param init - Module initializer arguments used to resolve module instances.
49
+ * @param config - The partial context module config to build upon.
50
+ */
38
51
  constructor(init: TInit, config?: Partial<ContextModuleConfig>);
52
+ /**
53
+ * Requires a module instance by its registered key.
54
+ * @param module - The key of the module to resolve.
55
+ * @returns A promise that resolves to the requested module instance.
56
+ */
39
57
  requireInstance<TKey extends string = Extract<keyof Modules, string>>(module: TKey): Promise<ModuleType<Modules[TKey]>>;
58
+ /**
59
+ * Requires a module instance by name.
60
+ * @param module - The name of the module to resolve.
61
+ * @returns A promise that resolves to the requested module instance.
62
+ */
40
63
  requireInstance<T>(module: string): Promise<T>;
41
64
  /**
42
65
  * Sets the context type for the current configuration.
@@ -87,6 +110,13 @@ export declare class ContextConfigBuilder<TModules extends Array<AnyModule> = []
87
110
  * @param fn - A function that takes a context and generates a corresponding path.
88
111
  */
89
112
  setContextPathGenerator(fn: ContextModuleConfig['generatePathFromContext']): void;
113
+ /**
114
+ * Sets the function used to resolve the initial context during module post-initialization.
115
+ *
116
+ * @param fn - A function that returns an observable input emitting the initial context item.
117
+ * The default resolver extracts a context ID from the navigation path, falling
118
+ * back to the parent provider's current context.
119
+ */
90
120
  setResolveInitialContext(fn: ContextModuleConfig['resolveInitialContext']): void;
91
121
  /**
92
122
  * Sets the context client configuration for fetching context items.
@@ -290,12 +290,40 @@ export interface IContextProvider {
290
290
  */
291
291
  export declare class ContextProvider extends BaseModuleProvider<ContextModuleConfig> implements IContextProvider {
292
292
  #private;
293
+ /**
294
+ * The underlying context client used to resolve and hold the current context item.
295
+ * @returns The internal {@link ContextClient} instance.
296
+ */
293
297
  get contextClient(): ContextClient;
298
+ /**
299
+ * The query client used to search for context items.
300
+ * @returns The internal `Query` instance used by {@link queryContext}.
301
+ */
294
302
  get queryClient(): Query<ContextItem[], QueryContextParameters>;
303
+ /**
304
+ * Observable stream emitting the current context item.
305
+ * @returns Observable that emits the current `ContextItem`, `null`, or `undefined`.
306
+ */
295
307
  get currentContext$(): Observable<ContextItem | null | undefined>;
308
+ /**
309
+ * Snapshot of the current context item.
310
+ * @returns The current `ContextItem`, or `null`/`undefined` if not set.
311
+ */
296
312
  get currentContext(): ContextItem | undefined | null;
297
- /** @deprecated do not use, will be removed */
313
+ /**
314
+ * Sets the current context item.
315
+ * @deprecated do not use, will be removed
316
+ * @param context - The context item to set as current. Must not be `undefined`.
317
+ * @throws Error if `context` is `undefined`.
318
+ */
298
319
  set currentContext(context: ContextItem | null | undefined);
320
+ /**
321
+ * Creates a new instance of `ContextProvider`.
322
+ * @param args - Constructor arguments.
323
+ * @param args.config - The context module configuration.
324
+ * @param args.event - Optional event module instance for dispatching context change events.
325
+ * @param args.parentContext - Optional parent context provider. Deprecated, use {@link connectParentContext}.
326
+ */
299
327
  constructor(args: {
300
328
  config: ContextModuleConfig;
301
329
  event?: ModuleType<EventModule>;
@@ -357,6 +385,11 @@ export declare class ContextProvider extends BaseModuleProvider<ContextModuleCon
357
385
  * If the observable is subscribe, unsubscribing __WILL__ abort the task and remove it from queue
358
386
  *
359
387
  * @param context context item which would be queue to set as current
388
+ * @param opt Optional settings.
389
+ * @param opt.validate Whether to validate the context item before setting it.
390
+ * @param opt.resolve Whether to attempt to resolve the context item if validation fails.
391
+ * @template T The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
392
+ * @returns An observable that emits the context item once the queued task completes.
360
393
  */
361
394
  setCurrentContext<T extends ContextItem<Record<string, unknown>> | null>(context: T, opt?: {
362
395
  validate?: boolean;
@@ -391,7 +424,7 @@ export declare class ContextProvider extends BaseModuleProvider<ContextModuleCon
391
424
  * - Emit the context and complete the observable.
392
425
  *
393
426
  * @protected
394
- * @typeParam T - The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
427
+ * @template T - The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
395
428
  * @param context - The new context to set.
396
429
  * @param opt - Optional settings:
397
430
  * - `validate`: Whether to validate the context before setting.
@@ -412,7 +445,7 @@ export declare class ContextProvider extends BaseModuleProvider<ContextModuleCon
412
445
  *
413
446
  * @see {@link setCurrentContext} for more details.
414
447
  *
415
- * @typeParam T - The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
448
+ * @template T - The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
416
449
  * @param context - The context item to set as the current context, or `null` to clear it.
417
450
  * @param opt - Optional settings for context handling.
418
451
  * @param opt.validate - If `true`, validates the context before setting it.
@@ -433,6 +466,7 @@ export declare class ContextProvider extends BaseModuleProvider<ContextModuleCon
433
466
  *
434
467
  * @param search - The search string to filter context items.
435
468
  * @returns An Observable that emits an array of `ContextItem` objects matching the search criteria.
469
+ * @throws Re-throws the underlying cause of a `QueryClientError`, otherwise re-throws the original error.
436
470
  */
437
471
  queryContext(search: string): Observable<Array<ContextItem>>;
438
472
  /**
@@ -514,26 +548,63 @@ export declare class ContextProvider extends BaseModuleProvider<ContextModuleCon
514
548
  export default ContextProvider;
515
549
  declare module '@equinor/fusion-framework-module-event' {
516
550
  interface FrameworkEventMap {
551
+ /**
552
+ * Dispatched **before** the current context is changed.
553
+ *
554
+ * The event is cancelable — calling `event.preventDefault()` in a
555
+ * listener will abort the context change.
556
+ */
517
557
  onCurrentContextChange: FrameworkEvent<FrameworkEventInit<{
518
558
  context: ContextItem | null;
519
559
  }, IContextProvider>>;
560
+ /**
561
+ * Dispatched **after** the current context has changed.
562
+ *
563
+ * Contains both the previous and next context items, enabling
564
+ * listeners to react to transitions.
565
+ */
520
566
  onCurrentContextChanged: FrameworkEvent<FrameworkEventInit<{
521
567
  next: ContextItem | null;
522
568
  previous?: ContextItem | null;
523
569
  }, IContextProvider>>;
570
+ /**
571
+ * Dispatched **before** a parent context change is applied locally.
572
+ *
573
+ * Cancelable — prevents the parent context from being mirrored into
574
+ * this provider.
575
+ */
524
576
  onParentContextChanged: FrameworkEvent<FrameworkEventInit<{
525
577
  context: ContextItem | null;
526
578
  }, IContextProvider>>;
579
+ /**
580
+ * Dispatched **before** context resolution begins (when validation
581
+ * fails and the caller requested resolution).
582
+ *
583
+ * Cancelable — aborting prevents the resolution attempt.
584
+ */
527
585
  onSetContextResolve: FrameworkEvent<FrameworkEventInit<{
528
586
  context: ContextItem;
529
587
  }, IContextProvider>>;
588
+ /**
589
+ * Dispatched **after** the context has been resolved to a new item.
590
+ *
591
+ * Cancelable — aborting prevents the resolved item from being
592
+ * set as the current context.
593
+ */
530
594
  onSetContextResolved: FrameworkEvent<FrameworkEventInit<{
531
595
  context: ContextItem;
532
596
  resolved?: ContextItem | null;
533
597
  }, IContextProvider>>;
598
+ /**
599
+ * Dispatched when context validation fails and resolution is not
600
+ * enabled.
601
+ */
534
602
  onSetContextValidationFailed: FrameworkEvent<FrameworkEventInit<{
535
603
  context: ContextItem;
536
604
  }, IContextProvider>>;
605
+ /**
606
+ * Dispatched when context resolution fails with an error.
607
+ */
537
608
  onSetContextResolveFailed: FrameworkEvent<FrameworkEventInit<{
538
609
  context: ContextItem;
539
610
  error: unknown;
@@ -20,7 +20,7 @@ export type GetContextParameters = {
20
20
  * @template ContextItem The type of the context item managed by the client.
21
21
  * @extends Observable<ContextItem | null | undefined>
22
22
  *
23
- * @todo - should this have `undefined` as a valid value?
23
+ * @todo(#5116) - should this have `undefined` as a valid value?
24
24
  *
25
25
  * @example
26
26
  * ```typescript
@@ -55,6 +55,10 @@ export declare class ContextClient extends Observable<ContextItem | null | undef
55
55
  get client(): Query<ContextItem, {
56
56
  id: string;
57
57
  }>;
58
+ /**
59
+ * Creates a new `ContextClient`.
60
+ * @param options - Query constructor options used to fetch a `ContextItem` by its ID.
61
+ */
58
62
  constructor(options: QueryCtorOptions<ContextItem, GetContextParameters>);
59
63
  /**
60
64
  * Sets the current context based on the provided identifier or context item.
@@ -85,6 +89,9 @@ export declare class ContextClient extends Observable<ContextItem | null | undef
85
89
  resolveContextAsync(id: string, opt?: {
86
90
  awaitResolve: boolean;
87
91
  }): Promise<ContextItem>;
92
+ /**
93
+ * Disposes of the client, completing the internal current-context subject.
94
+ */
88
95
  dispose(): void;
89
96
  }
90
97
  export default ContextClient;
@@ -7,46 +7,176 @@ import type { ContextFilterFn, ContextItem, QueryContextParameters, RelatedConte
7
7
  import type { GetContextParameters } from './client/ContextClient';
8
8
  import { type ContextConfigBuilderCallback } from './ContextConfigBuilder';
9
9
  import type { IContextProvider } from './ContextProvider';
10
+ /**
11
+ * Resolved configuration for the context module.
12
+ *
13
+ * Holds query clients, type filters, parent-connection settings, and
14
+ * optional callbacks for validation, resolution, and path integration.
15
+ * Produced by {@link ContextModuleConfigurator.createConfig} after all
16
+ * {@link ContextConfigBuilder} callbacks have run.
17
+ *
18
+ * @see ContextConfigBuilder — fluent API for populating this config.
19
+ * @see ContextProvider — runtime consumer of this config.
20
+ */
10
21
  export interface ContextModuleConfig {
22
+ /**
23
+ * Query client options used to fetch, search, and resolve related context items.
24
+ *
25
+ * - `get` — retrieves a single context item by ID.
26
+ * - `query` — searches context items by text and optional type filter.
27
+ * - `related` — fetches context items related to a given item (used during resolution).
28
+ */
11
29
  client: {
12
30
  get: QueryCtorOptions<ContextItem, GetContextParameters>;
13
31
  query: QueryCtorOptions<ContextItem[], QueryContextParameters>;
14
32
  related?: QueryCtorOptions<ContextItem[], RelatedContextParameters>;
15
33
  };
34
+ /**
35
+ * Allowed context type IDs (e.g. `['ProjectMaster', 'Facility']`).
36
+ *
37
+ * When set, {@link ContextProvider.validateContext} only accepts items
38
+ * whose `type.id` matches one of these values (case-insensitive).
39
+ */
16
40
  contextType?: string[];
41
+ /**
42
+ * Optional post-query filter applied to the result set returned by
43
+ * {@link ContextProvider.queryContext}.
44
+ */
17
45
  contextFilter?: ContextFilterFn;
18
46
  /**
19
- * connect context module to paren context module.
47
+ * Whether to connect the context module to a parent context module.
48
+ *
49
+ * When `true` (the default), the provider subscribes to the parent's
50
+ * `currentContext$` and mirrors changes into its own state.
20
51
  *
21
- * _default: `true`_
52
+ * @defaultValue `true`
22
53
  */
23
54
  connectParentContext?: boolean;
24
- /** set initial context from parent, will await resolve */
55
+ /**
56
+ * When `true`, skips resolving an initial context from the path or parent
57
+ * during module post-initialization.
58
+ */
25
59
  skipInitialContext?: boolean;
60
+ /**
61
+ * Extracts a context ID from a URL path segment.
62
+ *
63
+ * Used during initial context resolution and deep-link support.
64
+ * If not provided, the default GUID-based extractor is used.
65
+ *
66
+ * @param path - The URL path to inspect.
67
+ * @returns The extracted context ID, or `undefined` if none is found.
68
+ */
26
69
  extractContextIdFromPath?: (path: string) => string | undefined;
70
+ /**
71
+ * Generates a URL path that embeds the given context item's ID.
72
+ *
73
+ * Used by navigation integrations to update the browser URL when
74
+ * the context changes.
75
+ *
76
+ * @param context - The active context item.
77
+ * @param path - The current URL path.
78
+ * @returns The updated path, or `undefined` to leave it unchanged.
79
+ */
27
80
  generatePathFromContext?: (context: ContextItem, path: string) => string | undefined;
28
81
  /**
29
- * Method for generating context query parameters.
82
+ * Transforms a user search string and the configured context type into
83
+ * the query parameters sent to the context API.
84
+ *
85
+ * Override this to customise how free-text searches are mapped to the
86
+ * backend query contract.
30
87
  */
31
88
  contextParameterFn?: (args: {
32
89
  search: string;
33
90
  type: ContextModuleConfig['contextType'];
34
91
  }) => string | QueryContextParameters;
92
+ /**
93
+ * Custom context resolution strategy.
94
+ *
95
+ * Called with `this` bound to the {@link IContextProvider} when a context
96
+ * item fails validation and the caller requests resolution.
97
+ *
98
+ * @param item - The context item to resolve, or `null`.
99
+ * @returns An observable emitting the resolved context item.
100
+ */
35
101
  resolveContext?: (this: IContextProvider, item: ContextItem | null) => ReturnType<IContextProvider['resolveContext']>;
102
+ /**
103
+ * Custom context validation strategy.
104
+ *
105
+ * Called with `this` bound to the {@link IContextProvider} to decide
106
+ * whether a candidate context item is acceptable.
107
+ *
108
+ * @param item - The context item to validate, or `null`.
109
+ * @returns `true` if the item is valid.
110
+ */
36
111
  validateContext?: (this: IContextProvider, item: ContextItem | null) => ReturnType<IContextProvider['validateContext']>;
112
+ /**
113
+ * Resolves the initial context during module post-initialization.
114
+ *
115
+ * The default implementation tries to extract a context ID from the
116
+ * current navigation path, falling back to the parent provider's context.
117
+ *
118
+ * @param args - Module reference and instance map.
119
+ * @returns An observable input emitting the initial context item, or void.
120
+ */
37
121
  resolveInitialContext?: (args: {
38
122
  ref?: AnyModuleInstance | any;
39
123
  modules: ModuleInstance;
40
124
  }) => ObservableInput<ContextItem | void>;
41
125
  }
126
+ /**
127
+ * Public configurator contract for the context module.
128
+ *
129
+ * Consumers call {@link addConfigBuilder} to register one or more
130
+ * {@link ContextConfigBuilderCallback} functions that will run during
131
+ * module initialization to populate the {@link ContextModuleConfig}.
132
+ */
42
133
  export interface IContextModuleConfigurator {
134
+ /**
135
+ * Registers a configuration callback that receives a {@link ContextConfigBuilder}.
136
+ *
137
+ * Multiple builders can be added; they execute sequentially and merge
138
+ * their results into a single {@link ContextModuleConfig}.
139
+ *
140
+ * @param init - Builder callback invoked during module initialization.
141
+ */
43
142
  addConfigBuilder: (init: ContextConfigBuilderCallback) => void;
44
143
  }
144
+ /**
145
+ * Default implementation of {@link IContextModuleConfigurator}.
146
+ *
147
+ * Collects {@link ContextConfigBuilderCallback} registrations and, when
148
+ * {@link createConfig} is called, runs them in order against a
149
+ * {@link ContextConfigBuilder} to produce the final {@link ContextModuleConfig}.
150
+ *
151
+ * If no custom client is configured, the configurator falls back to
152
+ * creating one from the {@link ServicesModule} API provider.
153
+ */
45
154
  export declare class ContextModuleConfigurator implements IContextModuleConfigurator {
46
155
  #private;
156
+ /** Default cache TTL (in ms) for context query results. */
47
157
  defaultExpireTime: number;
158
+ /** @inheritdoc */
48
159
  addConfigBuilder(init: ContextConfigBuilderCallback): void;
160
+ /**
161
+ * Resolves the services API provider, preferring the local module
162
+ * instance and falling back to the parent module.
163
+ *
164
+ * @param init - Module initializer arguments.
165
+ * @returns The resolved API provider.
166
+ * @throws Error if no services module is available.
167
+ */
49
168
  protected _getServiceProvider(init: ModuleInitializerArgs<IContextModuleConfigurator, [ServicesModule]>): Promise<IApiProvider>;
169
+ /**
170
+ * Runs all registered config builders and produces the final
171
+ * {@link ContextModuleConfig}.
172
+ *
173
+ * If no `resolveInitialContext` was set, the default path + parent
174
+ * resolver is used. If no `client` was set, one is created from the
175
+ * {@link ServicesModule} API provider.
176
+ *
177
+ * @param init - Module initializer arguments including dependency instances.
178
+ * @returns The fully resolved context module configuration.
179
+ */
50
180
  createConfig(init: ModuleInitializerArgs<IContextModuleConfigurator, [ServicesModule, NavigationModule]>): Promise<ContextModuleConfig>;
51
181
  }
52
182
  export default ContextModuleConfigurator;
@@ -16,10 +16,12 @@ export declare class FusionContextSearchError extends Error {
16
16
  #private;
17
17
  /**
18
18
  * The title of the error.
19
+ * @returns The error title.
19
20
  */
20
21
  get title(): string;
21
22
  /**
22
23
  * The description of the error, if available.
24
+ * @returns The error description, or `undefined` if none was provided.
23
25
  */
24
26
  get description(): string | undefined;
25
27
  /**
@@ -0,0 +1 @@
1
+ export * from './FusionContextSearchError';
@@ -0,0 +1,9 @@
1
+ import type { ContextItem } from './types';
2
+ /**
3
+ * Parse the response from the GetContext API into a context item.
4
+ * @param response The response object containing the context item.
5
+ * @returns A promise that resolves to the context item.
6
+ */
7
+ export declare const getContextSelector: (response: Response) => Promise<ContextItem>;
8
+ export { queryContextSelector } from './query-context-selector';
9
+ export { relatedContextSelector } from './related-context-selector';
@@ -1,3 +1,15 @@
1
+ /**
2
+ * Context module for the Fusion Framework.
3
+ *
4
+ * Provides context management for Fusion-based applications and portals,
5
+ * including setting, querying, validating, and resolving context items.
6
+ *
7
+ * Use {@link enableContext} to register the module in a configurator,
8
+ * then access the {@link IContextProvider} from the module instance
9
+ * to interact with context state.
10
+ *
11
+ * @packageDocumentation
12
+ */
1
13
  export { ContextModuleConfigurator, IContextModuleConfigurator, ContextModuleConfig, } from './configurator';
2
14
  export { IContextProvider, ContextProvider } from './ContextProvider';
3
15
  export { default, ContextModule, module as contextModule, moduleKey as contextModuleKey, } from './module';
@@ -4,7 +4,18 @@ import type { ServicesModule } from '@equinor/fusion-framework-module-services';
4
4
  import type { NavigationModule } from '@equinor/fusion-framework-module-navigation';
5
5
  import { type IContextModuleConfigurator } from './configurator';
6
6
  import { type IContextProvider } from './ContextProvider';
7
+ /**
8
+ * Literal type identifying the context module within the Fusion Framework module system.
9
+ *
10
+ * Used as the key when registering or looking up the module in a `Modules` map.
11
+ */
7
12
  export type ContextModuleKey = 'context';
13
+ /**
14
+ * Module registration key for the context module.
15
+ *
16
+ * Pass this value—or reference it as `contextModuleKey`—when you need to
17
+ * identify the context module by name at runtime (e.g., `hasModule(contextModuleKey)`).
18
+ */
8
19
  export declare const moduleKey: ContextModuleKey;
9
20
  /**
10
21
  * Represents a module for managing context within the framework.
@@ -0,0 +1,8 @@
1
+ import type { ApiVersion, ApiContextEntity } from '@equinor/fusion-framework-module-services/context';
2
+ import type { ContextItem } from './types';
3
+ /**
4
+ * Parses an ApiContextEntity object into a ContextItem object.
5
+ * @param item The ApiContextEntity object to parse.
6
+ * @returns The parsed ContextItem object.
7
+ */
8
+ export declare const parseContextItem: (item: ApiContextEntity<ApiVersion.v1>) => ContextItem;
@@ -0,0 +1,7 @@
1
+ import type { ContextItem } from './types';
2
+ /**
3
+ * Parse the response from the QueryContext API into an array of context items.
4
+ * @param response The response object.
5
+ * @returns A promise that resolves to an array of context items.
6
+ */
7
+ export declare const queryContextSelector: (response: Response) => Promise<ContextItem[]>;
@@ -0,0 +1,7 @@
1
+ import type { ContextItem } from './types';
2
+ /**
3
+ * Parse the response from the RelatedContext API into an array of context items.
4
+ * @param response The response object containing the related context items.
5
+ * @returns A promise that resolves to an array of ContextItem objects.
6
+ */
7
+ export declare const relatedContextSelector: (response: Response) => Promise<ContextItem[]>;
@@ -16,7 +16,7 @@
16
16
  * @property graphic - Optional graphical representation, either as a string or an object containing type and content.
17
17
  * @property meta - Optional meta information, either as a string or an object containing type and content.
18
18
  *
19
- * @todo - convert to Zod schema for validation and type safety.
19
+ * @todo(#5122) - convert to Zod schema for validation and type safety.
20
20
  */
21
21
  export type ContextItem<TType extends Record<string, unknown> = Record<string, unknown>> = {
22
22
  id: string;
@@ -39,11 +39,33 @@ export type ContextItem<TType extends Record<string, unknown> = Record<string, u
39
39
  content: string;
40
40
  };
41
41
  };
42
+ /**
43
+ * Describes the type classification of a {@link ContextItem}.
44
+ *
45
+ * Every context item carries a `type` that identifies what kind of
46
+ * entity it represents (e.g. `ProjectMaster`, `Facility`, `Contract`).
47
+ * The optional hierarchy fields indicate parent–child relationships
48
+ * between context types.
49
+ */
42
50
  export interface ContextItemType {
51
+ /** Unique identifier for the context type (e.g. `'ProjectMaster'`). */
43
52
  id: string;
53
+ /** Whether this type is a child of another context type. */
44
54
  isChildType?: boolean;
55
+ /** IDs of parent context types, when `isChildType` is `true`. */
45
56
  parentTypeIds?: string[];
46
57
  }
58
+ /**
59
+ * Parameters for querying context items from the context API.
60
+ *
61
+ * Used by {@link ContextProvider.queryContext} and the underlying
62
+ * query client to search and filter context results.
63
+ *
64
+ * @property search - Free-text search term.
65
+ * @property filter - Optional structured filters.
66
+ * @property filter.type - Restrict results to specific context type IDs.
67
+ * @property filter.externalId - Filter by an external system identifier.
68
+ */
47
69
  export type QueryContextParameters = {
48
70
  search?: string;
49
71
  filter?: {
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Method will try to extract a context id from a path.
3
+ * The default matcher is a GUID pattern.
4
+ * Will iterate over the path and return the first match.
5
+ *
6
+ * @example
7
+ * ```ts
8
+ * const path = '/apps/context/7fd97952-7fe6-409b-a6dc-292dbf0e50d7?dsadasdas#example';
9
+ * const contextId = extractContextIdFromPath(path); // '7fd97952-7fe6-409b-a6dc-292dbf0e50d7'
10
+ * ```
11
+ *
12
+ * @param path string - the path to extract the context id from
13
+ * @param matcher RegExp - the pattern to match against
14
+ * @returns string | undefined - the context id or undefined
15
+ */
16
+ export declare const extractContextIdFromPath: (path: string, matcher?: RegExp) => string | undefined;
@@ -1,3 +1,13 @@
1
+ /**
2
+ * Utility functions for context module configuration and initialization.
3
+ *
4
+ * - {@link enableContext} — register the context module on a configurator.
5
+ * - {@link resolveInitialContext} — default initial-context resolver (path → parent fallback).
6
+ * - {@link extractContextIdFromPath} — extract a GUID context ID from a URL path.
7
+ * - {@link resolveContextFromPath} — resolve a context item from a URL path.
8
+ *
9
+ * @packageDocumentation
10
+ */
1
11
  export { enableContext } from './enable-context';
2
12
  export { resolveInitialContext } from './resolve-initial-context';
3
13
  export { extractContextIdFromPath, resolveContextFromPath } from './resolve-context-from-path';
@@ -2,6 +2,7 @@ import { type Observable } from 'rxjs';
2
2
  import type { ModuleType } from '@equinor/fusion-framework-module';
3
3
  import type { ContextModule } from '../module';
4
4
  import type { ContextItem } from '../types';
5
+ export { extractContextIdFromPath } from './extract-context-id-from-path';
5
6
  /**
6
7
  * Arguments for resolving a context from a path.
7
8
  */
@@ -19,22 +20,6 @@ export type ContextPathResolveArgs = {
19
20
  */
20
21
  validate?: (contextId: string) => boolean;
21
22
  };
22
- /**
23
- * Method will try to extract a context id from a path.
24
- * The default matcher is a GUID pattern.
25
- * Will iterate over the path and return the first match.
26
- *
27
- * @example
28
- * ```ts
29
- * const path = '/apps/context/7fd97952-7fe6-409b-a6dc-292dbf0e50d7?dsadasdas#example';
30
- * const contextId = extractContextIdFromPath(path); // '7fd97952-7fe6-409b-a6dc-292dbf0e50d7'
31
- * ```
32
- *
33
- * @param path string - the path to extract the context id from
34
- * @param matcher RegExp - the pattern to match against
35
- * @returns string | undefined - the context id or undefined
36
- */
37
- export declare const extractContextIdFromPath: (path: string, matcher?: RegExp) => string | undefined;
38
23
  /**
39
24
  * Method will try to resolve a context from a path.
40
25
  * The method will return a function that takes a path and returns an observable of the resolved context.
@@ -17,5 +17,5 @@ export declare const resolveContextFromParent: ContextModuleConfig['resolveIniti
17
17
  */
18
18
  export declare const resolveInitialContext: (options?: {
19
19
  path?: ContextPathResolveArgs;
20
- }) => Required<ContextModuleConfig>["resolveInitialContext"];
20
+ }) => Required<ContextModuleConfig>['resolveInitialContext'];
21
21
  export default resolveInitialContext;
@@ -1 +1 @@
1
- export declare const version = "7.0.4-next.0";
1
+ export declare const version = "8.0.1";