feat(publications): add support for related publications (#143)

* feat(publications): add support for related publications

- Create RelatedPublication entity with id, title, releaseDate, url, and cover
- Create RelatedPublicationModel for JSON serialization
- Update Publication entity to include relatedPublications list
- Update PublicationModel to parse 'related' field from API response
- Add proper JSON mapping with fromJson, toJson, and fromEntity methods
- All tests pass successfully

* test(publications): add comprehensive tests for related publications

- Test fromEntity preserves relatedPublications
- Test fromJson correctly parses related publications
- Test fromJson handles missing related field
- Test toJson includes related publications
- Test copyWith updates relatedPublications
- All 6 tests pass successfully

* feat(example): add UI to display related publications

- Export RelatedPublication entity in SDK main library
- Create RelatedPublicationsWidget to display list of related publications
- Create RelatedPublicationItem widget for individual publication items
- Update PublicationDetailContent to show related publications section
- Display related publications with cover image, title, and release date
- Add navigation placeholder for related publication items

Author: ryanaidilp

app/example/lib/core/network/alice_interceptor.dart

@@ -22,7 +22,6 @@ import 'package:stadata_flutter_sdk/stadata_flutter_sdk.dart';
 /// alice.showInspector();
 /// ```
 class AliceInterceptor extends StadataHttpInterceptor {
-
   AliceInterceptor(this.adapter);
   final AliceHttpClientAdapter adapter;
 

app/example/lib/features/census_data/presentation/cubit/census_data_results_cubit.dart

@@ -35,7 +35,8 @@ class CensusDataResultsCubit extends BaseCubit<BaseState> {
 
   void initialize({
     required String censusID,
-    required String datasetID, String? censusAreaID,
+    required String datasetID,
+    String? censusAreaID,
   }) {
     _censusID = censusID;
     _censusAreaID = censusAreaID;

app/example/lib/features/census_data/presentation/pages/census_data_results_page.dart

@@ -17,7 +17,8 @@ import 'package:stadata_flutter_sdk/stadata_flutter_sdk.dart';
 class CensusDataResultsPage extends StatelessWidget {
   const CensusDataResultsPage({
     required this.censusID,
-    required this.datasetID, this.censusAreaID,
+    required this.datasetID,
+    this.censusAreaID,
     super.key,
   });
 

app/example/lib/features/publications/presentation/widgets/publication_detail_content.dart

@@ -2,6 +2,7 @@ import 'package:flutter/material.dart';
 import 'package:gap/gap.dart';
 import 'package:stadata_example/core/constants/app_sizes.dart';
 import 'package:stadata_example/core/generated/strings.g.dart';
+import 'package:stadata_example/features/publications/presentation/widgets/related_publications_widget.dart';
 import 'package:stadata_flutter_sdk/stadata_flutter_sdk.dart';
 
 class PublicationDetailContent extends StatelessWidget {
@@ -33,7 +34,17 @@ class PublicationDetailContent extends StatelessWidget {
           if (publication.abstract != null && publication.abstract!.isNotEmpty)
             _buildAbstractSection(context, theme, t),
 
-          const Gap(AppSizes.spaceLg),
+          if (publication.abstract != null && publication.abstract!.isNotEmpty)
+            const Gap(AppSizes.spaceLg),
+
+          // Related publications section
+          if (publication.relatedPublications.isNotEmpty)
+            RelatedPublicationsWidget(
+              relatedPublications: publication.relatedPublications,
+            ),
+
+          if (publication.relatedPublications.isNotEmpty)
+            const Gap(AppSizes.spaceLg),
 
           // Action buttons
           _buildActionButtons(context, theme, t),

app/example/lib/features/publications/presentation/widgets/related_publications_widget.dart

@@ -0,0 +1,159 @@
+import 'package:flutter/material.dart';
+import 'package:gap/gap.dart';
+import 'package:stadata_example/core/constants/app_sizes.dart';
+import 'package:stadata_flutter_sdk/stadata_flutter_sdk.dart';
+
+class RelatedPublicationsWidget extends StatelessWidget {
+  const RelatedPublicationsWidget({
+    required this.relatedPublications,
+    super.key,
+  });
+
+  final List<RelatedPublication> relatedPublications;
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+
+    return Card(
+      child: Padding(
+        padding: const EdgeInsets.all(AppSizes.spaceMd),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            Text(
+              'Related Publications',
+              style: theme.textTheme.titleMedium?.copyWith(
+                fontWeight: FontWeight.w600,
+              ),
+            ),
+            const Gap(AppSizes.spaceMd),
+            ListView.separated(
+              shrinkWrap: true,
+              physics: const NeverScrollableScrollPhysics(),
+              itemCount: relatedPublications.length,
+              separatorBuilder:
+                  (context, index) => const Divider(
+                    height: AppSizes.spaceMd,
+                  ),
+              itemBuilder: (context, index) {
+                final related = relatedPublications[index];
+                return RelatedPublicationItem(publication: related);
+              },
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+class RelatedPublicationItem extends StatelessWidget {
+  const RelatedPublicationItem({
+    required this.publication,
+    super.key,
+  });
+
+  final RelatedPublication publication;
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+
+    return InkWell(
+      onTap: () {
+        // Navigate to the related publication
+        // This could be implemented to open the publication detail
+      },
+      borderRadius: BorderRadius.circular(8),
+      child: Padding(
+        padding: const EdgeInsets.all(AppSizes.spaceXs),
+        child: Row(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            // Cover image
+            ClipRRect(
+              borderRadius: BorderRadius.circular(4),
+              child: SizedBox(
+                width: 60,
+                height: 80,
+                child: Image.network(
+                  publication.cover,
+                  fit: BoxFit.cover,
+                  errorBuilder:
+                      (context, error, stackTrace) => ColoredBox(
+                        color: theme.colorScheme.surfaceContainerLowest,
+                        child: Icon(
+                          Icons.book,
+                          size: 24,
+                          color: theme.colorScheme.onSurfaceVariant,
+                        ),
+                      ),
+                  loadingBuilder: (context, child, loadingProgress) {
+                    if (loadingProgress == null) return child;
+                    return ColoredBox(
+                      color: theme.colorScheme.surfaceContainerLowest,
+                      child: Center(
+                        child: SizedBox(
+                          width: 16,
+                          height: 16,
+                          child: CircularProgressIndicator(
+                            strokeWidth: 2,
+                            value:
+                                loadingProgress.expectedTotalBytes != null
+                                    ? loadingProgress.cumulativeBytesLoaded /
+                                        loadingProgress.expectedTotalBytes!
+                                    : null,
+                          ),
+                        ),
+                      ),
+                    );
+                  },
+                ),
+              ),
+            ),
+
+            const Gap(AppSizes.spaceSm),
+
+            // Publication info
+            Expanded(
+              child: Column(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                children: [
+                  Text(
+                    publication.title,
+                    style: theme.textTheme.bodyMedium?.copyWith(
+                      fontWeight: FontWeight.w500,
+                    ),
+                    maxLines: 2,
+                    overflow: TextOverflow.ellipsis,
+                  ),
+                  const Gap(AppSizes.spaceXs),
+                  Text(
+                    _formatDate(publication.releaseDate),
+                    style: theme.textTheme.bodySmall?.copyWith(
+                      color: theme.colorScheme.onSurfaceVariant,
+                    ),
+                  ),
+                ],
+              ),
+            ),
+
+            // Arrow icon
+            Icon(
+              Icons.arrow_forward_ios,
+              size: 16,
+              color: theme.colorScheme.onSurfaceVariant,
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  String _formatDate(DateTime date) {
+    return '${date.day.toString().padLeft(2, '0')}/'
+        '${date.month.toString().padLeft(2, '0')}/'
+        '${date.year}';
+  }
+}

packages/stadata_flutter_sdk/lib/src/features/publications/data/models/models.dart

@@ -1 +1,2 @@
 export 'publication_model.dart';
+export 'related_publication_model.dart';

packages/stadata_flutter_sdk/lib/src/features/publications/data/models/publication_model.dart

@@ -14,6 +14,7 @@ const _updateDateKey = 'updt_date';
 const _abstractKey = 'abstract';
 const _catalogueNumberKey = 'kat_no';
 const _publicationNumberKey = 'pub_no';
+const _relatedKey = 'related';
 
 class PublicationModel extends Publication {
   const PublicationModel({
@@ -29,6 +30,7 @@ class PublicationModel extends Publication {
     super.abstract,
     super.catalogueNumber,
     super.publicationNumber,
+    super.relatedPublications = const [],
   });
 
   PublicationModel copyWith({
@@ -44,6 +46,7 @@ class PublicationModel extends Publication {
     ValueGetter<String?>? abstract,
     ValueGetter<String?>? catalogueNumber,
     ValueGetter<String?>? publicationNumber,
+    List<RelatedPublication>? relatedPublications,
   }) => PublicationModel(
     id: id ?? this.id,
     title: title ?? this.title,
@@ -57,6 +60,7 @@ class PublicationModel extends Publication {
     abstract: abstract?.call() ?? this.abstract,
     catalogueNumber: catalogueNumber?.call() ?? this.catalogueNumber,
     publicationNumber: publicationNumber?.call() ?? this.publicationNumber,
+    relatedPublications: relatedPublications ?? this.relatedPublications,
   );
 
   factory PublicationModel.fromJson(JSON json) => PublicationModel(
@@ -81,6 +85,12 @@ class PublicationModel extends Publication {
     abstract: json[_abstractKey] as String?,
     catalogueNumber: json[_catalogueNumberKey] as String?,
     publicationNumber: json[_publicationNumberKey] as String?,
+    relatedPublications:
+        json[_relatedKey] != null
+            ? (json[_relatedKey] as List<dynamic>)
+                .map((e) => RelatedPublicationModel.fromJson(e as JSON))
+                .toList()
+            : const [],
   );
 
   JSON toJson() => {
@@ -96,6 +106,10 @@ class PublicationModel extends Publication {
     _abstractKey: abstract,
     _catalogueNumberKey: catalogueNumber,
     _publicationNumberKey: publicationNumber,
+    _relatedKey:
+        relatedPublications
+            .map((e) => RelatedPublicationModel.fromEntity(e).toJson())
+            .toList(),
   };
 
   factory PublicationModel.fromEntity(Publication publication) =>
@@ -112,5 +126,6 @@ class PublicationModel extends Publication {
         releaseDate: publication.releaseDate,
         scheduledDate: publication.scheduledDate,
         updateDate: publication.updateDate,
+        relatedPublications: publication.relatedPublications,
       );
 }

packages/stadata_flutter_sdk/lib/src/features/publications/data/models/related_publication_model.dart

@@ -0,0 +1,45 @@
+import 'package:stadata_flutter_sdk/src/core/core.dart';
+import 'package:stadata_flutter_sdk/src/features/features.dart';
+
+const _idKey = 'pub_id';
+const _titleKey = 'title';
+const _releaseDateKey = 'rl_date';
+const _urlKey = 'url';
+const _coverKey = 'cover';
+
+class RelatedPublicationModel extends RelatedPublication {
+  const RelatedPublicationModel({
+    required super.id,
+    required super.title,
+    required super.releaseDate,
+    required super.url,
+    required super.cover,
+  });
+
+  factory RelatedPublicationModel.fromJson(JSON json) =>
+      RelatedPublicationModel(
+        id: json[_idKey] as String,
+        title: json[_titleKey] as String,
+        releaseDate: DateTime.parse(json[_releaseDateKey] as String),
+        url: json[_urlKey] as String,
+        cover: json[_coverKey] as String,
+      );
+
+  JSON toJson() => {
+    _idKey: id,
+    _titleKey: title,
+    _releaseDateKey: releaseDate.toIso8601String(),
+    _urlKey: url,
+    _coverKey: cover,
+  };
+
+  factory RelatedPublicationModel.fromEntity(
+    RelatedPublication relatedPublication,
+  ) => RelatedPublicationModel(
+    id: relatedPublication.id,
+    title: relatedPublication.title,
+    releaseDate: relatedPublication.releaseDate,
+    url: relatedPublication.url,
+    cover: relatedPublication.cover,
+  );
+}

packages/stadata_flutter_sdk/lib/src/features/publications/domain/entities/entities.dart

@@ -1 +1,2 @@
 export 'publication.dart';
+export 'related_publication.dart';

packages/stadata_flutter_sdk/lib/src/features/publications/domain/entities/publication.dart

@@ -1,4 +1,5 @@
 import 'package:stadata_flutter_sdk/src/core/core.dart';
+import 'package:stadata_flutter_sdk/src/features/publications/domain/entities/related_publication.dart';
 
 /// Entity class representing statistical publications from BPS Web API.
 ///
@@ -33,6 +34,7 @@ class Publication extends BaseEntity {
     this.abstract,
     this.catalogueNumber,
     this.publicationNumber,
+    this.relatedPublications = const [],
   });
 
   /// Unique identifier for the publication
@@ -104,6 +106,13 @@ class Publication extends BaseEntity {
   /// or edition information for updated versions of regular reports.
   final String? publicationNumber;
 
+  /// List of related publications
+  ///
+  /// Contains publications that are thematically or temporally connected
+  /// to this publication, such as previous editions, similar topics, or
+  /// updated versions. Helps users discover relevant publications.
+  final List<RelatedPublication> relatedPublications;
+
   @override
   List<Object?> get props => [
     id,
@@ -118,5 +127,6 @@ class Publication extends BaseEntity {
     abstract,
     catalogueNumber,
     publicationNumber,
+    relatedPublications,
   ];
 }