@equinor/fusion-framework-module-bookmark 3.0.6 → 4.0.0

package/src/BookmarkProvider.store.ts

@@ -8,7 +8,12 @@ import type { IBookmarkClient } from './BookmarkClient.interface';
 import type { Bookmark, BookmarkWithoutData } from './types';
 
 /**
- * Represents the state of the BookmarkProvider store.
+ * Internal state shape managed by the bookmark store.
+ *
+ * @property status - Set of base action types currently in-flight (used for loading indicators).
+ * @property errors - Map from base action type to the most recent error for that action.
+ * @property currentBookmark - The active bookmark, `null` when explicitly cleared, `undefined` before first set.
+ * @property bookmarks - Normalised record of bookmarks keyed by ID.
  */
 export type BookmarkState = {
   // current actions performed on the store
@@ -24,17 +29,21 @@ export type BookmarkState = {
 // export type BookmarkStoreFunctions = ActionCalls<typeof bookmarkActions>;
 
 /**
- * Represents the store for bookmarks, which is a flow subject that manages the state and actions for bookmarks.
+ * A {@link FlowSubject} specialised for bookmark state and actions.
+ *
+ * Combines a Redux-style reducer with RxJS side-effect flows to manage
+ * bookmark CRUD operations, favourites, and current-bookmark selection.
  */
 export type BookmarkStore = FlowSubject<BookmarkState, BookmarkActions>;
 
 /**
- * Creates a new BookmarkStore instance with the provided initial state and client.
+ * Creates and returns a new {@link BookmarkStore} wired with the bookmark
+ * reducer and all API side-effect flows.
  *
- * @param args - An object containing the initial state and client for the bookmark store.
- * @param args.initial - The initial state for the bookmark store.
- * @param args.client - The IBookmarkClient instance to bookmark store flows.
- * @returns A new BookmarkStore instance.
+ * @param args - Initialisation options.
+ * @param args.initial - Optional partial state merged over the reducer defaults.
+ * @param args.client - The {@link IBookmarkClient} used by store flows for API calls.
+ * @returns A fully configured bookmark store.
  */
 export const createBookmarkStore = (args: {
   initial?: Partial<BookmarkState>;

package/src/bookmark-config.schema.ts

@@ -10,6 +10,12 @@ import type { IBookmarkClient } from './BookmarkClient.interface';
 import { bookmarkSourceSystemSchema } from './bookmark.schemas';
 import type { BookmarkModuleConfig } from './types';
 
+/**
+ * Zod schema that validates the full {@link BookmarkModuleConfig} object.
+ *
+ * Used internally by {@link BookmarkModuleConfigurator} to verify the resolved
+ * configuration before the bookmark module is initialised.
+ */
 export const bookmarkConfigSchema = z.object({
   log: z.custom<ILogger>().optional(),
   logLevel: z.nativeEnum(LogLevel).optional(),
@@ -35,6 +41,13 @@ export const bookmarkConfigSchema = z.object({
     .default({ context: false, application: false }),
 });
 
+/**
+ * Parses an unknown configuration object against {@link bookmarkConfigSchema}.
+ *
+ * @param config - The raw config value to validate.
+ * @returns A validated {@link BookmarkModuleConfig}.
+ * @throws {ZodError} When validation fails.
+ */
 export const parseBookmarkConfig = (config: unknown): BookmarkModuleConfig => {
   return bookmarkConfigSchema.parse(config) as BookmarkModuleConfig;
 };

package/src/bookmark-module.ts

@@ -14,10 +14,18 @@ import { lastValueFrom } from 'rxjs';
 import { version } from './version';
 import type { IBookmarkProvider } from './BookmarkProvider.interface';
 
+/** String literal key used to register the bookmark module in the framework. */
 export type BookmarkModuleKey = 'bookmark';
 
+/** The module key constant used to identify the bookmark module at runtime. */
 export const moduleKey: BookmarkModuleKey = 'bookmark';
 
+/**
+ * Type definition for the bookmark framework module.
+ *
+ * Declares the module key, provider interface, configurator class,
+ * and optional peer dependencies (event, services, app, context modules).
+ */
 export type BookmarkModule = Module<
   BookmarkModuleKey,
   IBookmarkProvider,
@@ -28,6 +36,21 @@ export type BookmarkModule = Module<
 // TODO - remove when all framework uses log
 const fallbackLogger: ILogger = new ConsoleLogger('BookmarkModule');
 
+/**
+ * Bookmark module definition for the Fusion Framework.
+ *
+ * Handles configuration, initialization (creating a {@link BookmarkProvider}),
+ * and disposal of the bookmark module lifecycle.
+ *
+ * @example
+ * ```ts
+ * import { enableBookmark } from '@equinor/fusion-framework-module-bookmark';
+ *
+ * const configure = (configurator) => {
+ *   enableBookmark(configurator);
+ * };
+ * ```
+ */
 export const module: BookmarkModule = {
   name: moduleKey,
   version: new SemanticVersion(version),

package/src/bookmark.schemas.ts

@@ -1,12 +1,14 @@
 import * as z from 'zod';
 import type { Bookmark, BookmarkData } from './types';
 
+/** Zod schema for validating {@link BookmarkUser} objects. */
 export const bookmarkUserSchema = z.object({
   id: z.string(),
   name: z.string(),
   mail: z.string().optional(),
 });
 
+/** Zod schema for validating {@link SourceSystem} objects on a bookmark. */
 export const bookmarkSourceSystemSchema = z.object(
   {
     identifier: z.string(),
@@ -16,12 +18,14 @@ export const bookmarkSourceSystemSchema = z.object(
   { message: 'invalid source system' },
 );
 
+/** Zod schema for validating {@link BookmarkContext} objects. */
 export const bookmarkContextSchema = z.object({
   id: z.string(),
   name: z.string().optional(),
   type: z.string().optional(),
 });
 
+/** Zod schema for validating a {@link BookmarkWithoutData} (no payload). */
 export const bookmarkSchema = z.object({
   id: z.string(),
   name: z.string(),
@@ -36,8 +40,18 @@ export const bookmarkSchema = z.object({
   sourceSystem: bookmarkSourceSystemSchema.nullish(),
 });
 
+/** Zod schema for validating an array of bookmarks. */
 export const bookmarksSchema = z.array(bookmarkSchema);
 
+/**
+ * Creates a Zod schema for a {@link Bookmark} that includes a typed payload field.
+ *
+ * @template T - The bookmark payload data shape.
+ * @template S - Zod schema type for the payload.
+ * @param schema - Optional Zod schema to validate the payload. Defaults to
+ *   `z.record(z.string(), z.unknown()).or(z.string()).optional()`.
+ * @returns A Zod object schema extending {@link bookmarkSchema} with a `payload` property.
+ */
 export const bookmarkWithDataSchema = <
   T extends BookmarkData = BookmarkData,
   S extends z.ZodSchema<T> = z.ZodSchema<T>,
@@ -48,6 +62,14 @@ export const bookmarkWithDataSchema = <
     payload: schema,
   });
 
+/**
+ * Parses an unknown value into a typed {@link Bookmark} using {@link bookmarkWithDataSchema}.
+ *
+ * @template T - The bookmark payload data shape.
+ * @param value - The raw value to parse.
+ * @returns The parsed bookmark object.
+ * @throws {ZodError} When validation fails.
+ */
 export const parseBookmark = <T extends BookmarkData>(value: unknown): Bookmark<T> => {
   return bookmarkWithDataSchema().parse(value) as Bookmark<T>;
 };

package/src/enable-bookmark.ts

@@ -4,10 +4,28 @@ import { module } from './bookmark-module';
 import type { BookmarkModuleConfigurator } from './BookmarkConfigurator';
 
 /**
- * Enables the Bookmark module
+ * Enables the bookmark module on a Fusion Framework module configurator.
  *
- * @param configurator - The configuration object for the modules.
- * @param callback - An optional callback function that receives the `BookmarkModuleConfigurator` instance, allowing for further configuration.
+ * This is the primary entry point for adding bookmark support to an application.
+ * Call it during the application’s configure phase to register the module.
+ * An optional callback allows further customisation of the bookmark configurator
+ * (source system, filters, custom client, etc.).
+ *
+ * @param configurator - The application’s module configurator instance.
+ * @param callback - Optional callback that receives the {@link BookmarkModuleConfigurator}
+ *   for additional setup such as setting source system, filters, or a custom client.
+ *
+ * @example
+ * ```ts
+ * import { enableBookmark } from '@equinor/fusion-framework-module-bookmark';
+ *
+ * const configure = (configurator) => {
+ *   enableBookmark(configurator, (builder) => {
+ *     builder.setSourceSystem({ identifier: 'my-app', name: 'My App' });
+ *     builder.setFilter('application', true);
+ *   });
+ * };
+ * ```
  */
 export const enableBookmark = (
   // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '3.0.6';
+export const version = '4.0.0';