[DURACOM-507] add inline documentation

Author: FrancescoMolinaro

src/app/core/layout/models/box.model.ts

@@ -1,96 +1,170 @@
+/**
+ * Defines a metadata group within a layout field, grouping related metadata entries.
+ */
 export interface MetadataGroup {
+  /** The leading metadata key that acts as the group heading. */
   leading: string;
+  /** Array of layout fields within this group. */
   elements: LayoutField[];
 }
 
+/**
+ * Configuration for bitstream-related rendering in a layout field.
+ */
 export interface LayoutBitstream {
+  /** The bundle name to filter bitstreams from. */
   bundle: string;
+  /** The metadata field used to identify the bitstream. */
   metadataField: string;
+  /** The metadata value to match for selecting the bitstream. */
   metadataValue: string;
 }
 
+/**
+ * Enum of layout field types that determine how a field is rendered.
+ */
 export enum LayoutFieldType {
   METADATA = 'METADATA',
   METADATAGROUP = 'METADATAGROUP',
   BITSTREAM = 'BITSTREAM'
 }
 
+/**
+ * Describes a single renderable field within a metadata box row.
+ * Contains the metadata key, rendering type, and styling options.
+ */
 export interface LayoutField {
+  /** The metadata key to display (e.g., 'dc.title', 'dc.contributor.author'). */
   metadata?: string;
+  /** Bitstream configuration if this field renders a bitstream. */
   bitstream?: LayoutBitstream;
+  /** i18n label key for the field. */
   label?: string;
+  /** The rendering type identifier (e.g., 'text', 'link', 'date', 'thumbnail'). */
   rendering: string;
+  /** The field type discriminator. */
   fieldType: LayoutFieldType | string;
+  /** CSS classes for the overall field container. */
   style?: string;
+  /** CSS classes for the label column. */
   styleLabel?: string;
+  /** CSS classes for the value column. */
   styleValue?: string;
+  /** Nested metadata group configuration if fieldType is METADATAGROUP. */
   metadataGroup?: MetadataGroup;
+  /** Whether to render the label as a heading element. */
   labelAsHeading: boolean;
+  /** Whether to render multiple values inline (comma-separated) rather than stacked. */
   valuesInline: boolean;
 }
 
+/**
+ * Configuration for a metadata-type box containing rows of metadata fields.
+ */
 export interface MetadataBoxConfiguration extends BoxConfiguration {
+  /** Unique identifier for this box configuration. */
   id: string;
+  /** Array of rows within the metadata box. */
   rows: MetadataBoxRow[];
 }
 
+/**
+ * Base interface for all box configurations.
+ */
 export interface BoxConfiguration {
+  /** The box type discriminator. */
   type: string;
 }
 
+/**
+ * Configuration for a relation-type box that displays related items via a discovery search.
+ */
 export interface RelationBoxConfiguration extends BoxConfiguration {
+  /** The discovery configuration name used to find related items. */
   'discovery-configuration': string;
 }
 
+/**
+ * Configuration for a metrics-type box displaying item-level metrics.
+ */
 export interface MetricsBoxConfiguration extends BoxConfiguration {
+  /** Maximum number of columns for metrics display (null for unlimited). */
   maxColumns: null;
+  /** Array of metric type identifiers to display. */
   metrics: string[];
 }
 
+/**
+ * A cell within a metadata box row, containing layout fields.
+ */
 export interface MetadataBoxCell {
+  /** CSS classes applied to the cell element. */
   style: string;
+  /** Array of fields rendered within this cell. */
   fields: LayoutField[];
 }
 
+/**
+ * A row within a metadata box configuration.
+ */
 export interface MetadataBoxRow {
+  /** CSS classes applied to the row element. */
   style: string;
+  /** Array of cells within this row. */
   cells: MetadataBoxCell[];
 }
 
 /**
- * Describes the DynamicLayoutBox model
+ * Model representing a box in the dynamic layout system.
+ *
+ * A box is a configurable content container within a tab's cell. It defines what type of
+ * content to render (metadata, relations, metrics, collections, IIIF viewer, versioning)
+ * and provides styling, security, and collapsibility settings.
  */
 export class DynamicLayoutBox {
 
   /**
-   * The identifier of this DynamicLayoutBox
+   * The numeric identifier of this box.
    */
   id: number;
 
+  /** Short identifier name for this box. */
   shortname: string;
 
+  /** i18n key or plain text for the box header. */
   header: string;
 
+  /** The entity type this box belongs to. */
   entityType: string;
 
+  /** Whether the box starts collapsed. */
   collapsed: boolean;
 
+  /** Whether this box is a minor box (can be filtered out by TabDataService). */
   minor: boolean;
 
+  /** CSS classes applied to the box container. */
   style: string;
 
+  /** Whether to insert a clear element after this box. */
   clear: boolean;
 
+  /** Maximum number of columns for this box's content. */
   maxColumn: number;
 
+  /** Whether this box acts as a container for other elements. */
   container: boolean;
 
+  /** Metadata fields that have security restrictions. */
   metadataSecurityFields?: string[];
 
+  /** Security level required to view this box. */
   security: number;
 
+  /** The box type discriminator (METADATA, RELATION, METRICS, etc.). */
   boxType: string;
 
+  /** Type-specific configuration for the box content. */
   configuration?: RelationBoxConfiguration | MetadataBoxConfiguration | MetricsBoxConfiguration;
 
 }

src/app/core/layout/models/tab.model.ts

@@ -14,7 +14,11 @@ import { DynamicLayoutBox } from './box.model';
 import { TAB } from './tab.resource-type';
 
 /**
- * Describes a type of DynamicLayoutTab
+ * Model representing a layout tab in the dynamic item page system.
+ *
+ * A tab defines a named section of an item's detail page. Tabs contain rows and cells
+ * forming a grid layout, and may be marked as "leading" (rendered above the main content).
+ * Tabs are fetched from the REST API via the `/tabs` endpoint.
  */
 @typedObject
 export class DynamicLayoutTab extends CacheableObject {
@@ -85,13 +89,23 @@ export class DynamicLayoutTab extends CacheableObject {
 }
 
 
+/**
+ * A row within a tab's layout grid. Contains cells arranged horizontally.
+ */
 export interface DynamicLayoutRow {
+  /** CSS classes applied to the row element (e.g., Bootstrap grid row classes). */
   style: string;
+  /** Array of cells within this row. */
   cells: DynamicLayoutCell[];
 }
 
+/**
+ * A cell within a layout row. Contains one or more boxes.
+ */
 export interface DynamicLayoutCell {
+  /** CSS classes applied to the cell element (e.g., Bootstrap column classes). */
   style: string;
+  /** Array of boxes rendered within this cell. */
   boxes: DynamicLayoutBox[];
 }
 

src/app/core/layout/tab-data.service.ts

@@ -25,7 +25,10 @@ import {
 } from './models/tab.model';
 
 /**
- * A service responsible for fetching data from the REST API on the tabs endpoint
+ * A service responsible for fetching layout tabs from the REST API's `/tabs` endpoint.
+ *
+ * Provides methods to find tabs by item UUID or entity type, with support for
+ * filtering out tabs that contain only minor (secondary) boxes.
  */
 @Injectable({ providedIn: 'root' })
 export class TabDataService extends IdentifiableDataService<DynamicLayoutTab> {
@@ -68,16 +71,20 @@ export class TabDataService extends IdentifiableDataService<DynamicLayoutTab> {
   }
 
   /**
-   * @param tabs
-   * @returns Tabs which contains non minor element
+   * Filters out tabs where every box is marked as minor.
+   *
+   * @param tabs the full list of tabs to filter
+   * @returns tabs that contain at least one non-minor box
    */
   filterTabWithOnlyMinor(tabs: DynamicLayoutTab[]): DynamicLayoutTab[] {
     return tabs.filter(tab => !this.hasTabOnlyMinor(tab));
   }
 
   /**
-   * @param tab  Contains a tab data which has rows, cells and boxes
-   * @returns Boolean based on cells has minor or not
+   * Checks whether all boxes within a tab are minor.
+   *
+   * @param tab the tab to inspect
+   * @returns true if every box in every cell in every row is minor
    */
   hasTabOnlyMinor(tab: DynamicLayoutTab): boolean {
     if (hasNoValue(tab?.rows)) {

src/app/dynamic-item-page/dynamic-item-page.component.ts

@@ -18,7 +18,11 @@ import { fadeInOut } from '../shared/animations/fade';
 import { ThemedLoadingComponent } from '../shared/loading/themed-loading.component';
 
 /**
- * This component is the entry point for the page that renders items.
+ * Entry point component for the dynamic item page.
+ *
+ * Resolves the item from route data and passes it to {@link DynamicLayoutComponent},
+ * which handles tab resolution and layout rendering. Also checks admin authorization
+ * for displaying admin-specific UI elements.
  */
 @Component({
   selector: 'ds-dynamic-item-page',

src/app/dynamic-layout/decorators/dynamic-layout-box.decorator.ts

@@ -8,11 +8,20 @@ import { DynamicLayoutMetadataBoxComponent } from '../dynamic-layout-matrix/dyna
 import { DynamicLayoutRelationBoxComponent } from '../dynamic-layout-matrix/dynamic-layout-box-container/boxes/relation/dynamic-layout-relation-box.component';
 import { LayoutBox } from '../enums/layout-box.enum';
 
+/**
+ * Render options for a dynamic layout box component, specifying its Angular component
+ * reference and whether it manages its own accordion container.
+ */
 export interface DynamicLayoutBoxRenderOptions {
+  /** The component class to instantiate for this box type. */
   componentRef: GenericConstructor<Component>;
+  /** If true, the box provides its own container; the parent won't wrap it in an accordion. */
   hasOwnContainer: boolean;
 }
 
+/**
+ * Static registry mapping {@link LayoutBox} types to their rendering component and container options.
+ */
 const layoutBoxesMap = new Map<LayoutBox, DynamicLayoutBoxRenderOptions>([
   [ LayoutBox.COLLECTIONS, { componentRef: DynamicLayoutCollectionBoxComponent, hasOwnContainer: false } as DynamicLayoutBoxRenderOptions ],
   [ LayoutBox.IIIFVIEWER, { componentRef: DynamicLayoutIiifViewerBoxComponent, hasOwnContainer: false } as DynamicLayoutBoxRenderOptions ],
@@ -21,6 +30,12 @@ const layoutBoxesMap = new Map<LayoutBox, DynamicLayoutBoxRenderOptions>([
   [ LayoutBox.VERSIONING, { componentRef: ItemVersionsComponent, hasOwnContainer: false } as DynamicLayoutBoxRenderOptions ],
 ]);
 
+/**
+ * Resolves the rendering options (component + container flag) for a given box type.
+ *
+ * @param boxType the layout box type to look up
+ * @returns the render options for the box type, or undefined if not registered
+ */
 export function getDynamicLayoutBox(boxType: LayoutBox): DynamicLayoutBoxRenderOptions {
   return layoutBoxesMap.get(boxType);
 }

src/app/dynamic-layout/decorators/dynamic-layout-page.decorator.ts

@@ -8,6 +8,9 @@ import {
   LayoutPage,
 } from '../enums/layout-page.enum';
 
+/**
+ * Static registry mapping {@link LayoutPage} orientation types to their page component.
+ */
 const layoutPageMap = new Map<LayoutPage, GenericConstructor<DynamicLayoutHorizontalComponent|DynamicLayoutVerticalComponent>>([
   [ LayoutPage.HORIZONTAL, DynamicLayoutHorizontalComponent ],
   [ LayoutPage.VERTICAL, DynamicLayoutVerticalComponent ],
@@ -16,6 +19,13 @@ const layoutPageMap = new Map<LayoutPage, GenericConstructor<DynamicLayoutHorizo
 layoutPageMap.set(LayoutPage.HORIZONTAL, DynamicLayoutHorizontalComponent);
 layoutPageMap.set(LayoutPage.VERTICAL, DynamicLayoutVerticalComponent);
 
+/**
+ * Resolves the page layout component for the given orientation.
+ * Falls back to {@link DEFAULT_LAYOUT_PAGE} if orientation is null or not registered.
+ *
+ * @param orientation the layout page orientation (horizontal or vertical)
+ * @returns the component constructor for the requested orientation
+ */
 export function getDynamicLayoutPage(orientation: LayoutPage): any {
   let componentLayout;
   if (hasNoValue(orientation) || hasNoValue(layoutPageMap.get(orientation))) {

src/app/dynamic-layout/dynamic-layout-leading/dynamic-layout-leading.component.ts

@@ -9,6 +9,10 @@ import { Item } from '../../core/shared/item.model';
 import { DsoEditMenuComponent } from '../../shared/dso-page/dso-edit-menu/dso-edit-menu.component';
 import { DynamicLayoutMatrixComponent } from '../dynamic-layout-matrix/dynamic-layout-matrix.component';
 
+/**
+ * Component that renders leading tabs (summary/overview panels displayed above the main tabbed content).
+ * Delegates box rendering to {@link DynamicLayoutMatrixComponent} and optionally shows the edit menu.
+ */
 @Component({
   selector: 'ds-dynamic-layout-leading',
   templateUrl: './dynamic-layout-leading.component.html',

src/app/dynamic-layout/dynamic-layout-loader/dynamic-layout-horizontal/dynamic-layout-horizontal.component.ts

@@ -11,6 +11,11 @@ import { DsoEditMenuComponent } from '../../../shared/dso-page/dso-edit-menu/dso
 import { DynamicLayoutMatrixComponent } from '../../dynamic-layout-matrix/dynamic-layout-matrix.component';
 import { DynamicLayoutNavbarComponent } from './dynamic-layout-navbar/dynamic-layout-navbar.component';
 
+/**
+ * Horizontal layout page component for the dynamic item page.
+ * Renders tabs as a horizontal top navbar, with the selected tab's content
+ * displayed below via {@link DynamicLayoutMatrixComponent}.
+ */
 @Component({
   selector: 'ds-dynamic-layout-horizontal',
   templateUrl: './dynamic-layout-horizontal.component.html',

src/app/dynamic-layout/dynamic-layout-loader/dynamic-layout-loader.component.ts

@@ -20,6 +20,13 @@ import { getDynamicLayoutPage } from '../decorators/dynamic-layout-page.decorato
 import { DynamicLayoutLoaderDirective } from '../directives/dynamic-layout-loader.directive';
 import { LayoutPage } from '../enums/layout-page.enum';
 
+/**
+ * Loader component that dynamically instantiates the correct layout page component
+ * (horizontal or vertical) based on the entity type's configuration in the app config.
+ *
+ * Uses the {@link DynamicLayoutLoaderDirective} as a ViewChild anchor to place the
+ * dynamically created component, passing the item, tabs, and context menu settings.
+ */
 @Component({
   selector: 'ds-dynamic-layout-loader',
   templateUrl: './dynamic-layout-loader.component.html',
@@ -46,7 +53,7 @@ export class DynamicLayoutLoaderComponent implements OnInit, OnDestroy {
   @Input() showContextMenu: boolean;
 
   /**
-   * Configuration layout form the environment
+   * Layout type configuration (orientation) resolved from the app config for the item's entity type.
    */
   layoutConfiguration: DynamicLayoutTypeConfig;
 

src/app/dynamic-layout/dynamic-layout-loader/dynamic-layout-vertical/dynamic-layout-vertical.component.ts

@@ -16,6 +16,11 @@ import { DynamicLayoutMatrixComponent } from '../../dynamic-layout-matrix/dynami
 import { DynamicLayoutNavbarComponent } from '../dynamic-layout-horizontal/dynamic-layout-navbar/dynamic-layout-navbar.component';
 import { DynamicLayoutSidebarComponent } from './dynamic-layout-sidebar/dynamic-layout-sidebar.component';
 
+/**
+ * Vertical layout page component for the dynamic item page.
+ * Renders tabs as a vertical sidebar on larger screens (falling back to a horizontal
+ * navbar on small screens), with the selected tab's content displayed alongside.
+ */
 @Component({
   selector: 'ds-dynamic-layout-vertical',
   templateUrl: './dynamic-layout-vertical.component.html',