@smartsoft001-mobilems/models 2.98.0 → 2.99.0

package/README.md

@@ -15,7 +15,7 @@ import { Config, Page, MsFile, ArticleWidgetType } from '@smartsoft001-mobilems/
 | `ConfigPageType` | Page-type enum used by the config menu                            |
 | `ConfigMenuItem` | Union of menu-item shapes                                          |
 | `ITheme`         | Theme block of `Config` (colours, fonts, per-area flags)           |
-| `Page`           | CMS page — `IEntity<number>`; optional `slug`, `seo: PageSeo \| null`, `sections: PageSection[] \| null` |
+| `Page`           | CMS page — `IEntity<number>`; optional `slug`, `seo: PageSeo \| null`, `sections: PageSectionRaw[] \| null` (raw API shape — normalize before use) |
 | `PageSlide`      | Slide of a CMS page                                                |
 | `MsFile`         | Multimedia file — `IEntity<number>`                                |
 | `MsFileFromFeature` | Enum of file feature sources (image, audio, video, 3d, …)       |
@@ -24,22 +24,41 @@ import { Config, Page, MsFile, ArticleWidgetType } from '@smartsoft001-mobilems/
 
 Dynamic CMS page sections — `Page.sections`, returned by `GET page/<id>` / `GET page/slug/<slug>` and
 rendered by `PageSectionsComponent` (`smart-mobilems-page-sections`) in
-[`@smartsoft001-mobilems/angular`](../angular/README.md). Fields the API may send as `null` are typed
-as such; `grid`, `margin` and `padding` are `unknown` (not interpreted yet).
+[`@smartsoft001-mobilems/angular`](../angular/README.md). Shapes follow the real API response
+(`GET page/slug/test-sekcje`, the `TEST_SECTIONS` fixture of the angular package). Fields the API may
+send as `null` are typed as such. `PageSectionRaw` is what the API sends and what `Page.sections`
+holds (positions and lists may be missing/`null`, lists may hold `null` items);
+`normalizePageSections` turns it into `PageSection` — the shape variants receive (lists always
+arrays without `null`s, everything sorted by `position`, `position` always a number). Every
+`PageSection` is a valid `PageSectionRaw`.
 
 | Export                          | Shape                                                                                   |
 | ------------------------------- | --------------------------------------------------------------------------------------- |
-| `PageSection`                   | `type`, `theme` (component key `type/theme`), `position`, `appearance`, `content`, `blocks`, `cta`, `grid?` |
-| `PageSectionContent`            | `title?`, `lead?` (HTML), `description?` (HTML)                                         |
-| `PageSectionBlock`              | `position`, `content`, `media: { background: PageSectionMedia \| null } \| null`, `target`, `grid?` |
+| `PageSection`                   | `type`, `theme` (component key `type/theme`), `position`, `appearance`, `content`, `blocks`, `cta`, `grid?` (container children only), `widget?` (banner), `children?` (`grid_container`) |
+| `PageSectionRaw`                | `PageSection` as sent by the API: `position?`, `blocks?`, `cta?`, `children?`, `widget.search?`/`counter?` may be missing or `null`, list items may be `null` |
+| `PageSectionBlockRaw` / `PageSectionCtaRaw` / `PageSectionSearchWidgetRaw` / `PageSectionCounterWidgetRaw` | API shapes of blocks, CTAs and widgets — `position?: number \| null` |
+| `PageSectionWidgetRaw`          | `search?`/`counter?`: lists of raw widgets (or `null` items), or `null`                  |
+| `PageSectionContent`            | `title?`, `lead?` (HTML), `description?` (HTML) — already in the requested language     |
+| `PageSectionBlock`              | `position`, `content`, `media: PageSectionBlockMedia \| null`, `target`, `grid?: PageSectionGrid \| null` |
+| `PageSectionBlockMedia`         | `background: PageSectionMedia \| null`, `audiovisual?: PageSectionMedia \| null`        |
+| `PageSectionGrid`               | `{ x, y, w, h }` on the CMS 12-column grid (0-based `x`/`y`)                              |
 | `PageSectionCta`                | `position`, `target`                                                                    |
-| `PageSectionAppearance`         | `background: { color, file?, type? } \| null`, `margin?`, `padding?`                     |
+| `PageSectionAppearance`         | `margin?`/`padding?: PageSectionSpacing \| null`, `background: PageSectionBackground \| null` |
+| `PageSectionSpacing`            | `top?`, `right?`, `bottom?`, `left?` — each `number` (CMS scale 0–12) or `null`          |
+| `PageSectionBackground`         | `color: string \| null`, `file?: PageSectionFile \| null`, `type?: 'image' \| 'video' \| string \| null` |
 | `PageSectionMedia`              | `position?`, `file: PageSectionFile \| null`, `type: 'image' \| 'video' \| null`         |
-| `PageSectionFile`               | `filePath` (relative to the API host), `id?`, `extension?`, `altText?`, `fileName?`     |
-| `PageSectionTarget`             | Union of the three targets below, discriminated by `targetType`                         |
-| `PageSectionLinkTarget`         | `targetType: 'link'`, `url` (`http(s)://`, `#anchor` or internal path), `targetLabel?`  |
-| `PageSectionDictionaryTarget`   | `targetType: 'dictionary'`, `dictionaryType` (e.g. `creator`), `dictionary` (id), `targetLabel?` |
-| `PageSectionMuseumObjectTarget` | `targetType: 'museum_object'`, `object` (id), `targetLabel?`                            |
+| `PageSectionFile`               | `filePath` (relative to the multimedia host, or an absolute CDN URL), `id?`, `extension?`, `altText?`, `fileName?` |
+| `PageSectionWidget`             | banner widgets: `search: PageSectionSearchWidget[]`, `counter: PageSectionCounterWidget[]` |
+| `PageSectionSearchWidget`       | `position`, `placeholder: string \| null`                                               |
+| `PageSectionCounterWidget`      | `position`, `source` (`'creators' \| 'museum_objects' \| string`), `value` (computed by the API) |
+| `PageSectionTarget`             | Union of the targets below, discriminated by `targetType`; every target has `targetLabel?` |
+| `PageSectionLinkTarget`         | `targetType: 'link'`, `url` (`http(s)://`, `mailto:`, `tel:`, `#anchor` or internal path) |
+| `PageSectionPageTarget`         | `targetType: 'page'`, `page` (CMS page id)                                               |
+| `PageSectionDictionaryTarget`   | `targetType: 'dictionary'`, `dictionaryType: PageSectionDictionaryType`, `dictionary` (id) |
+| `PageSectionDictionaryType`     | `'creator' \| 'department' \| 'tag' \| string`                                           |
+| `PageSectionMuseumObjectTarget` | `targetType: 'museum_object'`, `object` (id)                                             |
+| `PageSectionCardTypeCodeTarget` | `targetType: 'card_type_code'`, `cardTypeCodes: number[]` (any matches)                  |
+| `PageSectionModuleTarget`       | `targetType: 'module'` — exists in the CMS, fields not sent by the API yet (never clickable) |
 | `PageSeo`                       | `title?`, `description?` — SEO fields of a `Page`                                       |
 
 ## User

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartsoft001-mobilems/models",
-  "version": "2.98.0",
+  "version": "2.99.0",
   "types": "./src/index.d.ts",
   "main": "./src/index.js",
   "type": "commonjs"

package/src/lib/entities/page-section.entity.d.ts

@@ -2,9 +2,15 @@
  * Dynamic CMS page sections — `sections` of a `Page` returned by
  * `GET page/<id>` / `GET page/slug/<slug>`.
  *
- * Every field the API may send as `null` is typed as such. `grid`, `margin`
- * and `padding` are not interpreted by the framework yet, hence `unknown`.
+ * Every field the API may send as `null` is typed as such. Shapes follow the
+ * real API response (`GET page/slug/test-sekcje`, every CMS setting in use).
+ * `PageSection` is the normalized shape section components receive;
+ * `PageSectionRaw` is what the API sends (`Page.sections`) —
+ * `normalizePageSections` (`@smartsoft001-mobilems/angular`) turns missing
+ * lists into `[]`, drops `null` items and sorts everything by `position`
+ * before rendering.
  */
+/** Section/block texts, already in the requested language. */
 export interface PageSectionContent {
     title?: string | null;
     /** HTML. */
@@ -15,14 +21,25 @@ export interface PageSectionContent {
 export interface PageSectionLinkTarget {
     targetType: 'link';
     targetLabel?: string | null;
-    /** `http(s)://…` (external), `#anchor` or an internal path. */
+    /**
+     * `http(s)://…` (external), `mailto:`/`tel:`, `#anchor` or an internal
+     * path.
+     */
     url: string | null;
 }
+export interface PageSectionPageTarget {
+    targetType: 'page';
+    targetLabel?: string | null;
+    /** CMS page id. */
+    page: number;
+}
+/** Dictionary kinds the CMS offers; others may come later. */
+export type PageSectionDictionaryType = 'creator' | 'department' | 'tag' | (string & {});
 export interface PageSectionDictionaryTarget {
     targetType: 'dictionary';
     targetLabel?: string | null;
     /** Dictionary kind, e.g. `creator`. */
-    dictionaryType: string;
+    dictionaryType: PageSectionDictionaryType;
     /** Dictionary entry id. */
     dictionary: number;
 }
@@ -32,10 +49,29 @@ export interface PageSectionMuseumObjectTarget {
     /** Museum object id. */
     object: number;
 }
-export type PageSectionTarget = PageSectionLinkTarget | PageSectionDictionaryTarget | PageSectionMuseumObjectTarget;
+export interface PageSectionCardTypeCodeTarget {
+    targetType: 'card_type_code';
+    targetLabel?: string | null;
+    /** Object card type codes — any of them matches. */
+    cardTypeCodes: number[];
+}
+/**
+ * `module` target — selectable in the CMS, but the API does not send its
+ * fields yet, so nothing beyond `targetType`/`targetLabel` is known. Never
+ * clickable until the backend defines it.
+ */
+export interface PageSectionModuleTarget {
+    targetType: 'module';
+    targetLabel?: string | null;
+    [field: string]: unknown;
+}
+export type PageSectionTarget = PageSectionLinkTarget | PageSectionPageTarget | PageSectionDictionaryTarget | PageSectionMuseumObjectTarget | PageSectionCardTypeCodeTarget | PageSectionModuleTarget;
 export interface PageSectionFile {
     id?: number;
-    /** Relative to the API host, e.g. `/uploads/media/…`. */
+    /**
+     * Usually relative to the multimedia host (`/uploads/media/…`); object
+     * images may come as an absolute CDN URL.
+     */
     filePath: string;
     extension?: string | null;
     altText?: string | null;
@@ -46,39 +82,124 @@ export interface PageSectionMedia {
     file: PageSectionFile | null;
     type: 'image' | 'video' | null;
 }
+/** `media` of a block: the background and an optional audio/video file. */
+export interface PageSectionBlockMedia {
+    background: PageSectionMedia | null;
+    audiovisual?: PageSectionMedia | null;
+}
+/** Placement on the CMS 12-column grid (0-based `x`/`y`, size `w`×`h`). */
+export interface PageSectionGrid {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
 export interface PageSectionBlock {
     position: number;
-    grid?: unknown;
+    /** Mosaic placement; `null` outside mosaic themes. */
+    grid?: PageSectionGrid | null;
     content: PageSectionContent | null;
-    media: {
-        background: PageSectionMedia | null;
-    } | null;
+    media: PageSectionBlockMedia | null;
     target: PageSectionTarget | null;
 }
 export interface PageSectionCta {
     position: number;
     target: PageSectionTarget | null;
 }
+/**
+ * Margin/padding per side on the CMS 0–12 scale; `null`/missing = not set.
+ * Sides are optional so partial objects (typed `unknown` before 2.103) still
+ * compile.
+ */
+export interface PageSectionSpacing {
+    top?: number | null;
+    right?: number | null;
+    bottom?: number | null;
+    left?: number | null;
+}
+export interface PageSectionBackground {
+    color: string | null;
+    file?: PageSectionFile | null;
+    /** `image`/`video`; any other string is accepted (and treated as image). */
+    type?: 'image' | 'video' | (string & {}) | null;
+}
 export interface PageSectionAppearance {
-    margin?: unknown;
-    padding?: unknown;
-    background: {
-        color: string | null;
-        file?: PageSectionFile | null;
-        type?: string | null;
-    } | null;
+    margin?: PageSectionSpacing | null;
+    padding?: PageSectionSpacing | null;
+    background: PageSectionBackground | null;
+}
+/** Search box of a `banner` — rendered by the museum variant. */
+export interface PageSectionSearchWidget {
+    position: number;
+    placeholder: string | null;
+}
+/** Counter of a `banner`; `value` is computed by the API. */
+export interface PageSectionCounterWidget {
+    position: number;
+    source: 'creators' | 'museum_objects' | (string & {});
+    value: number;
+}
+export interface PageSectionWidget {
+    search: PageSectionSearchWidget[];
+    counter: PageSectionCounterWidget[];
 }
 export interface PageSection {
-    /** Section kind, e.g. `slider`, `tile_collection`, `banner`. */
+    /**
+     * Section kind, e.g. `slider`, `tile_collection`, `banner`,
+     * `grid_container`, `portal_slot`.
+     */
     type: string;
     /** Visual variant of the `type`, e.g. `carousel`, `cards`. */
     theme: string;
     appearance: PageSectionAppearance | null;
     position: number;
-    grid?: unknown;
+    /**
+     * Placement of a `grid_container` child on the 12-column grid; always
+     * `null` for top-level sections.
+     */
+    grid?: PageSectionGrid | null;
     content: PageSectionContent | null;
     blocks: PageSectionBlock[];
     cta: PageSectionCta[];
+    /** `banner` widgets. */
+    widget?: PageSectionWidget | null;
+    /** Sections of a `grid_container` (one level — no nested containers). */
+    children?: PageSection[] | null;
+}
+/** A block as the API sends it — `position` may be missing or `null`. */
+export interface PageSectionBlockRaw extends Omit<PageSectionBlock, 'position'> {
+    position?: number | null;
+}
+/** A CTA as the API sends it — `position` may be missing or `null`. */
+export interface PageSectionCtaRaw extends Omit<PageSectionCta, 'position'> {
+    position?: number | null;
+}
+/** A search widget as the API sends it. */
+export interface PageSectionSearchWidgetRaw extends Omit<PageSectionSearchWidget, 'position'> {
+    position?: number | null;
+}
+/** A counter widget as the API sends it. */
+export interface PageSectionCounterWidgetRaw extends Omit<PageSectionCounterWidget, 'position'> {
+    position?: number | null;
+}
+/** `widget` as the API sends it — lists and their items may be `null`. */
+export interface PageSectionWidgetRaw {
+    search?: (PageSectionSearchWidgetRaw | null)[] | null;
+    counter?: (PageSectionCounterWidgetRaw | null)[] | null;
+}
+/**
+ * A section exactly as the API sends it (`Page.sections`): `position` may be
+ * missing or `null`, lists may be missing or `null` (e.g. `grid_container`
+ * and `portal_slot` come without `blocks`/`cta`) and may hold `null` items.
+ * `normalizePageSections` (`@smartsoft001-mobilems/angular`) turns it into a
+ * `PageSection`. Every `PageSection` is a valid `PageSectionRaw`.
+ */
+export interface PageSectionRaw extends Omit<PageSection, 'position' | 'blocks' | 'cta' | 'widget' | 'children'> {
+    position?: number | null;
+    blocks?: (PageSectionBlockRaw | null)[] | null;
+    cta?: (PageSectionCtaRaw | null)[] | null;
+    widget?: PageSectionWidgetRaw | null;
+    children?: (PageSectionRaw | null)[] | null;
 }
 /** SEO fields of a CMS page; every field may be `null`. */
 export interface PageSeo {

package/src/lib/entities/page-section.entity.js

@@ -3,8 +3,13 @@
  * Dynamic CMS page sections — `sections` of a `Page` returned by
  * `GET page/<id>` / `GET page/slug/<slug>`.
  *
- * Every field the API may send as `null` is typed as such. `grid`, `margin`
- * and `padding` are not interpreted by the framework yet, hence `unknown`.
+ * Every field the API may send as `null` is typed as such. Shapes follow the
+ * real API response (`GET page/slug/test-sekcje`, every CMS setting in use).
+ * `PageSection` is the normalized shape section components receive;
+ * `PageSectionRaw` is what the API sends (`Page.sections`) —
+ * `normalizePageSections` (`@smartsoft001-mobilems/angular`) turns missing
+ * lists into `[]`, drops `null` items and sorts everything by `position`
+ * before rendering.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=page-section.entity.js.map

package/src/lib/entities/page-section.entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"page-section.entity.js","sourceRoot":"","sources":["../../../../../../../packages/shared/models/src/lib/entities/page-section.entity.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}
+{"version":3,"file":"page-section.entity.js","sourceRoot":"","sources":["../../../../../../../packages/shared/models/src/lib/entities/page-section.entity.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG"}

package/src/lib/entities/page.entity.d.ts

@@ -1,5 +1,5 @@
 import { IEntity } from '@smartsoft001/domain-core';
-import { PageSection, PageSeo } from './page-section.entity';
+import { PageSectionRaw, PageSeo } from './page-section.entity';
 export declare class Page implements IEntity<number> {
     id: number;
     title: string;
@@ -7,8 +7,12 @@ export declare class Page implements IEntity<number> {
     slides: Array<PageSlide>;
     slug?: string;
     seo?: PageSeo | null;
-    /** Dynamic sections, rendered by `smart-mobilems-page-sections`. */
-    sections?: PageSection[] | null;
+    /**
+     * Dynamic sections exactly as the API sends them — normalize them
+     * (`normalizePageSections`) before reading lists or positions;
+     * `smart-mobilems-page-sections` does it itself.
+     */
+    sections?: PageSectionRaw[] | null;
 }
 export declare class PageSlide {
     id: number;

package/src/lib/entities/page.entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"page.entity.js","sourceRoot":"","sources":["../../../../../../../packages/shared/models/src/lib/entities/page.entity.ts"],"names":[],"mappings":";;;;AACA,iDAAoD;AAK7C,IAAM,IAAI,GAAV,MAAM,IAAI;CAsBhB,CAAA;AAtBY,oBAAI;AAIf;IADC,IAAA,cAAK,GAAE;;mCACO;AAGf;IADC,IAAA,cAAK,GAAE;;qCACK;AAGb;IADC,IAAA,cAAK,GAAE;sCACC,KAAK;oCAAY;eAVf,IAAI;IADhB,IAAA,cAAK,GAAE;GACK,IAAI,CAsBhB;AAGM,IAAM,SAAS,GAAf,MAAM,SAAS;CAkBrB,CAAA;AAlBY,8BAAS;AAEpB;IADC,IAAA,cAAK,GAAE;;qCACI;AAGZ;IADC,IAAA,cAAK,GAAE;;wCACO;AAGf;IADC,IAAA,cAAK,GAAE;;+CACwB;AAGhC;IADC,IAAA,cAAK,GAAE;;+CACc;AAGtB;IADC,IAAA,cAAK,GAAE;;8CACa;AAGrB;IADC,IAAA,cAAK,GAAE;;8CACa;oBAjBV,SAAS;IADrB,IAAA,cAAK,GAAE;GACK,SAAS,CAkBrB"}
+{"version":3,"file":"page.entity.js","sourceRoot":"","sources":["../../../../../../../packages/shared/models/src/lib/entities/page.entity.ts"],"names":[],"mappings":";;;;AACA,iDAAoD;AAK7C,IAAM,IAAI,GAAV,MAAM,IAAI;CA0BhB,CAAA;AA1BY,oBAAI;AAIf;IADC,IAAA,cAAK,GAAE;;mCACO;AAGf;IADC,IAAA,cAAK,GAAE;;qCACK;AAGb;IADC,IAAA,cAAK,GAAE;sCACC,KAAK;oCAAY;eAVf,IAAI;IADhB,IAAA,cAAK,GAAE;GACK,IAAI,CA0BhB;AAGM,IAAM,SAAS,GAAf,MAAM,SAAS;CAkBrB,CAAA;AAlBY,8BAAS;AAEpB;IADC,IAAA,cAAK,GAAE;;qCACI;AAGZ;IADC,IAAA,cAAK,GAAE;;wCACO;AAGf;IADC,IAAA,cAAK,GAAE;;+CACwB;AAGhC;IADC,IAAA,cAAK,GAAE;;+CACc;AAGtB;IADC,IAAA,cAAK,GAAE;;8CACa;AAGrB;IADC,IAAA,cAAK,GAAE;;8CACa;oBAjBV,SAAS;IADrB,IAAA,cAAK,GAAE;GACK,SAAS,CAkBrB"}