@africanies/angular-web-sdk 0.1.11 → 0.1.13

package/libs/africanies-core/src/lib/auth/auth-token.service.ts

@@ -30,6 +30,9 @@ import { asString } from '../http/wire';
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Holds the bearer access token used by {@link authInterceptor}.
+ */
 export class AuthTokenService {
   private readonly storage = inject(STORAGE_TOKEN);
   private readonly api = inject(ApiClient);

package/libs/africanies-core/src/lib/auth/auth.service.ts

@@ -40,6 +40,9 @@ import { AUTH_FORGOT_PASSWORD_PATH } from './auth.paths';
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Unauthenticated auth endpoints (`POST /auth/…`).
+ */
 export class AuthService {
   private readonly api = inject(ApiClient);
 

package/libs/africanies-core/src/lib/country/country.service.ts

@@ -46,6 +46,9 @@ const COUNTRY_CACHE_TTL_MS = 5 * 60_000;
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Public country utility reads (`GET /public/country/read/{id?}`).
+ */
 export class CountryService {
   private readonly api = inject(ApiClient);
 

package/libs/africanies-core/src/lib/currency/currency.service.ts

@@ -60,6 +60,9 @@ const CURRENCY_CACHE_TTL_MS = 5 * 60_000;
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Currency App Settings API (`GET /currency/read/{id?}` plus create / update / delete).
+ */
 export class CurrencyService {
   private readonly api = inject(ApiClient);
 

package/libs/africanies-core/src/lib/document/document.service.ts

@@ -46,6 +46,9 @@ const DOCUMENT_CACHE_TTL_MS = 5 * 60_000;
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Public document catalog reads (`GET /public/document/read/{id?}`).
+ */
 export class DocumentService {
   private readonly api = inject(ApiClient);
 

package/libs/africanies-core/src/lib/file/file.service.ts

@@ -41,6 +41,9 @@ import {
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * File utility reads (`POST /file/read`).
+ */
 export class FileService {
   private readonly api = inject(ApiClient);
 

package/libs/africanies-core/src/lib/filters/filter-options.resolver.ts

@@ -46,6 +46,9 @@ const SDK_FILTER_OPTIONS_SOURCES = new Set<FilterOptionsSource>([
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Resolves filter drawer select options from built-in SDK catalog services.
+ */
 export class FilterOptionsResolver {
   private readonly warehouses = inject(WarehouseService);
   private readonly shipmentMethods = inject(ShipmentMethodService);

package/libs/africanies-core/src/lib/http/api-client.ts

@@ -116,6 +116,9 @@ type ResponseMode = NonNullable<ApiRequestOptions['responseMode']>;
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Endpoint-agnostic HTTP façade over Angular {@link HttpClient}.
+ */
 export class ApiClient {
   private readonly http = inject(HttpClient);
   private readonly config = inject(AFRICANIES_SDK_CONFIG);

package/libs/africanies-core/src/lib/mode/mode-config.service.ts

@@ -45,6 +45,9 @@ import {
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Source of truth for region currency and measurement units (STN / SFN).
+ */
 export class ModeConfigService {
   private readonly api = inject(ApiClient);
   private readonly storage = inject(STORAGE_TOKEN);

package/libs/africanies-core/src/lib/notification/notification.service.ts

@@ -43,6 +43,9 @@ import {
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Authenticated user notifications (`GET /user/notifications/read/{id?}`).
+ */
 export class NotificationService {
   private readonly api = inject(ApiClient);
 

package/libs/africanies-core/src/lib/overlay/route-overlay.service.ts

@@ -37,6 +37,9 @@ interface OpenOverlayState {
  * {@link MODAL_SERVICE} / {@link DRAWER_SERVICE} to avoid a circular dependency.
  */
 @Injectable()
+/**
+ * Keeps query-param state in sync with modal/drawer overlays.
+ */
 export class RouteOverlayService {
   private readonly route = inject(ActivatedRoute);
   private readonly router = inject(Router);

package/libs/africanies-core/src/lib/payment-method/payment-method.service.ts

@@ -65,6 +65,9 @@ const PAYMENT_METHOD_CACHE_TTL_MS = 5 * 60_000;
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Payment-method App Settings API (`GET /payment_method/read/{id?}` plus update).
+ */
 export class PaymentMethodService {
   private readonly api = inject(ApiClient);
 

package/libs/africanies-core/src/lib/plan/plan.service.ts

@@ -42,6 +42,9 @@ const PLAN_CACHE_TTL_MS = 5 * 60_000;
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Public subscription-plan reads (`GET /public/plan/read/{id?}`).
+ */
 export class PlanService {
   private readonly api = inject(ApiClient);
 

package/libs/africanies-core/src/lib/product/product.service.ts

@@ -41,6 +41,9 @@ const PRODUCT_CACHE_TTL_MS = 5 * 60_000;
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Product utility reads (`GET /product/read/{id?}`).
+ */
 export class ProductService {
   private readonly api = inject(ApiClient);
 

package/libs/africanies-core/src/lib/service/service.service.ts

@@ -45,6 +45,9 @@ const SERVICE_CACHE_TTL_MS = 5 * 60_000;
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Public subscription-service reads (`GET /public/service/read/{id?}`).
+ */
 export class ServiceService {
   private readonly api = inject(ApiClient);
 

package/libs/africanies-core/src/lib/shipment-method/shipment-method.service.ts

@@ -45,6 +45,9 @@ const SHIPMENT_METHOD_CACHE_TTL_MS = 5 * 60_000;
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Shipment method / carrier utility reads (`GET /shipment_method/read/{id?}`).
+ */
 export class ShipmentMethodService {
   private readonly api = inject(ApiClient);
 

package/libs/africanies-core/src/lib/shipping/shipping-mode.service.ts

@@ -62,6 +62,9 @@ export type ShippingModeChangeGuard = (
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Signal-based holder for the active {@link ShippingMode}.
+ */
 export class ShippingModeService {
   private readonly storage = inject(SessionStorageService);
   private readonly injector = inject(Injector);

package/libs/africanies-core/src/lib/user/user.service.ts

@@ -44,6 +44,9 @@ import {
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Current authenticated user (`GET /user`).
+ */
 export class UserService {
   private readonly api = inject(ApiClient);
 

package/libs/africanies-core/src/lib/warehouse/warehouse.service.ts

@@ -45,6 +45,9 @@ const WAREHOUSE_CACHE_TTL_MS = 5 * 60_000;
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Warehouse utility reads (`GET /warehouse/read/{id?}`).
+ */
 export class WarehouseService {
   private readonly api = inject(ApiClient);
 

package/libs/africanies-core/src/lib/zone/zone.service.ts

@@ -41,6 +41,9 @@ const ZONE_CACHE_TTL_MS = 5 * 60_000;
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Zone utility reads (`GET /zone/read/records/{id?}`).
+ */
 export class ZoneService {
   private readonly api = inject(ApiClient);
 

package/libs/africanies-icons/src/lib/africanies-icon.component.ts

@@ -59,6 +59,9 @@ import { IconRegistryService } from './icon-registry.service';
     '[attr.data-icon]': 'name()',
   },
 })
+/**
+ * Renders a single icon from the shared SVG sprite.
+ */
 export class AfricaniesIconComponent {
   private readonly registry = inject(IconRegistryService);
 

package/libs/africanies-icons/src/lib/icon-registry.service.ts

@@ -34,6 +34,9 @@ export const AFRICANIES_ICON_SPRITE_URL = new InjectionToken<string>(
  * to invoke repeatedly — concurrent callers share one in-flight promise.
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Fetches and inlines the icon sprite once into `document.body`.
+ */
 export class IconRegistryService {
   private readonly document = inject(DOCUMENT);
   private readonly spriteUrl = inject(AFRICANIES_ICON_SPRITE_URL);

package/libs/africanies-storage/src/lib/local-storage.service.ts

@@ -21,6 +21,9 @@ import { readJson, writeJson } from './storage-json';
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * `localStorage`-backed {@link StorageService}.
+ */
 export class LocalStorageService extends StorageService {
   /**
    * @inheritdoc

package/libs/africanies-storage/src/lib/session-storage.service.ts

@@ -25,6 +25,9 @@ import { readJson, writeJson } from './storage-json';
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * `sessionStorage`-backed {@link StorageService}.
+ */
 export class SessionStorageService extends StorageService {
   /**
    * @inheritdoc

package/libs/africanies-theme/src/lib/mode-color.service.ts

@@ -72,6 +72,9 @@ export interface ModeColorClasses {
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Maps {@link ShippingModeService} to mode-accent Tailwind classes.
+ */
 export class ModeColorService {
   private readonly shippingMode = inject(ShippingModeService);
 

package/libs/africanies-theme/src/lib/theme.service.ts

@@ -40,6 +40,9 @@ import type { Theme } from './theme.types';
  * ```
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Application light/dark theme preference.
+ */
 export class ThemeService {
   private readonly storage = inject(STORAGE_TOKEN);
   private readonly document = inject(DOCUMENT);

package/libs/africanies-ui/src/index.ts

@@ -163,22 +163,40 @@ export {
   AddressInputComponent,
   type AddressPlace,
   type AddressPrediction,
+  buildPhoneNumberValue,
   CheckboxComponent,
   DatePickerComponent,
+  dialCodeForIso2,
   fileExtensionLabel,
   fileMatchesAccept,
   FileUploadComponent,
   type FileUploadResult,
   type FileUploadVariant,
+  formatNationalDigits,
   GOOGLE_PLACES_CONFIG,
   type GooglePlacesConfig,
   GooglePlacesService,
+  isPhoneNumberComplete,
+  matchDialCode,
+  normalizePhoneIso2,
   NumberInputComponent,
   OtpInputComponent,
   type OtpInputVariant,
+  parsePhoneControlValue,
+  PHONE_DIAL_CODES,
+  PHONE_MAX_NATIONAL_DIGITS,
+  PHONE_MIN_NATIONAL_DIGITS,
+  phoneCountryName,
+  type PhoneCountryOption,
+  phoneCountryOptions,
+  phoneDigitsOnly,
+  PhoneInputComponent,
+  type PhoneNumberValue,
+  phoneToE164,
   provideGooglePlaces,
   RadioComponent,
   type RadioOption,
+  removeDialCode,
   type SearchComboboxBadge,
   type SearchComboboxBadgeFn,
   SearchComboboxComponent,

package/libs/africanies-ui/src/lib/accordion/accordion.component.ts

@@ -97,6 +97,9 @@ export type AccordionSize = 'md' | 'sm';
     </div>
   `,
 })
+/**
+ * Bordered expandable panel with animated fold — the pattern used on Manifest detail and Make Payment review.
+ */
 export class AccordionComponent {
   /** Plain-text header. Prefer projected `[africaniesAccordionTitle]` for rich titles. */
   readonly title = input('');

package/libs/africanies-ui/src/lib/action-menu/action-menu-trigger.directive.ts

@@ -16,4 +16,7 @@ import { Directive } from '@angular/core';
   selector: '[africaniesActionMenuTrigger]',
   standalone: true,
 })
+/**
+ * Marks projected content as the custom trigger for {@link ActionMenuComponent}.
+ */
 export class ActionMenuTriggerDirective {}

package/libs/africanies-ui/src/lib/action-menu/action-menu.component.ts

@@ -211,6 +211,9 @@ const MENU_PANEL_POSITIONS: ConnectedPosition[] = [
     </ng-template>
   `,
 })
+/**
+ * Compact overflow menu for row and toolbar actions.
+ */
 export class ActionMenuComponent {
   private readonly router = inject(Router);
 

package/libs/africanies-ui/src/lib/alert/alert.component.ts

@@ -90,6 +90,9 @@ const DEFAULT_ICONS: Record<AlertVariant, IconName> = {
     </div>
   `,
 })
+/**
+ * Inline page/section banner — distinct from {@link ErrorStateComponent} (full-section async failure + Retry).
+ */
 export class AlertComponent {
   /** Semantic tone. Defaults to `info`. */
   readonly variant = input<AlertVariant>('info');

package/libs/africanies-ui/src/lib/avatar/avatar-menu.component.ts

@@ -65,6 +65,9 @@ import { AvatarComponent, type AvatarSize } from './avatar.component';
     }
   `,
 })
+/**
+ * Avatar trigger with an attached overflow menu — profile / account actions.
+ */
 export class AvatarMenuComponent {
   readonly name = input.required<string>();
   readonly src = input<string | null>(null);

package/libs/africanies-ui/src/lib/avatar/avatar.component.ts

@@ -44,6 +44,9 @@ export type AvatarSize = 'sm' | 'md' | 'lg';
     </span>
   `,
 })
+/**
+ * Circular avatar with image or initials fallback.
+ */
 export class AvatarComponent {
   /** Display name — used for initials when no image loads. */
   readonly name = input('');

package/libs/africanies-ui/src/lib/brand/brand-logo.component.ts

@@ -57,6 +57,9 @@ export type BrandLogoSize = 'sm' | 'md' | 'lg';
     </svg>
   `,
 })
+/**
+ * Default AFRICANIES wordmark — inlined so it works without copying static assets.
+ */
 export class BrandLogoComponent {
   readonly size = input<BrandLogoSize>('md');
 

package/libs/africanies-ui/src/lib/button/button.component.ts

@@ -102,6 +102,9 @@ export type ButtonSize = 'sm' | 'md' | 'lg';
     '(click)': 'blockWhenDisabled($event)',
   },
 })
+/**
+ * Theme-token button used across AFRICANIES surfaces.
+ */
 export class ButtonComponent {
   private readonly modeColor = inject(ModeColorService);
 

package/libs/africanies-ui/src/lib/carrier/carrier-logo.component.ts

@@ -78,6 +78,9 @@ export function normalizeCarrierLogoSlug(
     }
   `,
 })
+/**
+ * Inline carrier marks for delivery vendor cells.
+ */
 export class CarrierLogoComponent {
   /** Raw carrier slug or label from the API. */
   readonly carrier = input('');

package/libs/africanies-ui/src/lib/chip/chip.component.ts

@@ -114,6 +114,9 @@ export type ChipSize = 'sm' | 'md';
     }
   `,
 })
+/**
+ * Compact status / category label.
+ */
 export class ChipComponent {
   /** Semantic tone. Defaults to `neutral`. Ignored when {@link color} is set. */
   readonly variant = input<ChipVariant>('neutral');

package/libs/africanies-ui/src/lib/content-stack/content-stack.component.ts

@@ -42,6 +42,9 @@ import { ChangeDetectionStrategy, Component, input } from '@angular/core';
     </div>
   `,
 })
+/**
+ * Compact stacked text for table cells and detail panels.
+ */
 export class ContentStackComponent {
   /** Primary line — usually a person or entity name. */
   readonly title = input('');

package/libs/africanies-ui/src/lib/copy-button/copy-button.component.ts

@@ -53,6 +53,9 @@ import { ToastService } from '../toast/toast.service';
     </button>
   `,
 })
+/**
+ * Icon button that copies {@link value} to the clipboard.
+ */
 export class CopyButtonComponent {
   private readonly toastService = inject(ToastService, { optional: true });
 

package/libs/africanies-ui/src/lib/feedback/async-state.component.ts

@@ -111,6 +111,9 @@ type AsyncView =
     }
   `,
 })
+/**
+ * Async query wrapper that maps {@link AsyncQueryStateModel} into loading / error / empty / success with non-blocking badges for background activity.
+ */
 export class AsyncStateComponent<T = unknown> {
   /**
    * Snapshot from the app's query layer (e.g. mapped `injectQuery()` signals).

package/libs/africanies-ui/src/lib/feedback/empty-state.component.ts

@@ -54,6 +54,9 @@ import { ButtonComponent } from '../button/button.component';
     </div>
   `,
 })
+/**
+ * Blocking empty state when a fetch succeeded but produced no rows / value.
+ */
 export class EmptyStateComponent {
   /**
    * Empty-copy. Defaults to a generic phrase; override for filter-specific help.

package/libs/africanies-ui/src/lib/feedback/error-indicator.component.ts

@@ -161,6 +161,9 @@ import { ButtonComponent } from '../button/button.component';
     }
   `,
 })
+/**
+ * Compact error pill for non-blocking failures while stale data stays visible — distinct from {@link ErrorStateComponent} (full-section blocking).
+ */
 export class ErrorIndicatorComponent {
   /**
    * Error copy. When empty, the indicator is not shown.

package/libs/africanies-ui/src/lib/feedback/error-state.component.ts

@@ -54,6 +54,9 @@ import { ButtonComponent } from '../button/button.component';
     </div>
   `,
 })
+/**
+ * Blocking error state for failed async fetches (not field validation).
+ */
 export class ErrorStateComponent {
   /**
    * Human-readable failure reason. Required so the alert is never an empty

package/libs/africanies-ui/src/lib/feedback/loading-state.component.ts

@@ -58,6 +58,9 @@ export type LoadingStateMode = 'inline' | 'block';
     </div>
   `,
 })
+/**
+ * Blocking / inline loading indicator for async surfaces.
+ */
 export class LoadingStateComponent {
   protected readonly modeColor = inject(ModeColorService);
 

package/libs/africanies-ui/src/lib/filters/filter-drawer.panel.ts

@@ -338,6 +338,9 @@ import { FilterQueryService } from './filter-query.service';
     </div>
   `,
 })
+/**
+ * Schema-driven filter drawer body.
+ */
 export class FilterDrawerPanel {
   protected readonly data = inject<FilterDrawerData>(OVERLAY_DATA);
   protected readonly ref = inject(AfricaniesOverlayRef<FilterDrawerResult>);

package/libs/africanies-ui/src/lib/filters/filter-drawer.service.ts

@@ -43,6 +43,9 @@ import { FilterQueryService } from './filter-query.service';
  * ```
  */
 @Injectable()
+/**
+ * Opens the schema-driven {@link FilterDrawerPanel} via {@link DrawerService}.
+ */
 export class FilterDrawerService {
   private readonly drawer = inject(DrawerService);
   private readonly filterQuery = inject(FilterQueryService);

package/libs/africanies-ui/src/lib/filters/filter-query.service.ts

@@ -24,6 +24,9 @@ import {
  * `provideRouter`).
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Bidirectional list-query sync with the browser URL.
+ */
 export class FilterQueryService {
   private readonly route = inject(ActivatedRoute, { optional: true });
   private readonly router = inject(Router, { optional: true });

package/libs/africanies-ui/src/lib/forms/address-input/address-input.component.ts

@@ -209,6 +209,9 @@ const ADDRESS_PANEL_POSITIONS: ConnectedPosition[] = [
     }
   `,
 })
+/**
+ * Google Places address field with suggestion dropdown.
+ */
 export class AddressInputComponent implements ControlValueAccessor {
   private readonly places = inject(GooglePlacesService);
   private readonly destroyRef = inject(DestroyRef);

package/libs/africanies-ui/src/lib/forms/address-input/google-places.service.ts

@@ -55,6 +55,9 @@ interface PlaceDetailsApiResponse {
  * Register {@link provideGooglePlaces} with a key that has Places API (New).
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Places API (New) over REST — same contract as the working React autocomplete (`POST …/places:autocomplete`, `GET …/places/{id}`).
+ */
 export class GooglePlacesService {
   private readonly config = inject(GOOGLE_PLACES_CONFIG, { optional: true });
 

package/libs/africanies-ui/src/lib/forms/checkbox/checkbox.component.ts

@@ -97,6 +97,9 @@ let nextCheckboxId = 0;
     </div>
   `,
 })
+/**
+ * Boolean checkbox following the shared AFRICANIES form field pattern.
+ */
 export class CheckboxComponent implements ControlValueAccessor {
   private readonly modeColor = inject(ModeColorService);
 

package/libs/africanies-ui/src/lib/forms/date-picker/date-picker.component.ts

@@ -98,6 +98,9 @@ let nextDatePickerId = 0;
     }
   `,
 })
+/**
+ * Date field wrapping native `input[type=date]`, following shared AFRICANIES form field pattern.
+ */
 export class DatePickerComponent implements ControlValueAccessor {
   private readonly theme = inject(ThemeService, { optional: true });
 

package/libs/africanies-ui/src/lib/forms/file-upload/camera-capture.dialog.ts

@@ -114,6 +114,9 @@ type CameraFacing = 'environment' | 'user';
     </div>
   `,
 })
+/**
+ * Live webcam capture dialog for {@link FileUploadComponent}.
+ */
 export class CameraCaptureDialogComponent {
   private readonly destroyRef = inject(DestroyRef);
   private readonly ref = inject(AfricaniesOverlayRef<File>);

package/libs/africanies-ui/src/lib/forms/file-upload/file-preview.dialog.ts

@@ -97,6 +97,9 @@ type PreviewKind = 'image' | 'unavailable';
     </div>
   `,
 })
+/**
+ * Large-file preview modal for {@link FileUploadComponent}.
+ */
 export class FilePreviewDialogComponent {
   protected readonly data = inject<FilePreviewData>(OVERLAY_DATA);
   private readonly ref = inject(AfricaniesOverlayRef<void>);

package/libs/africanies-ui/src/lib/forms/file-upload/file-upload.component.ts

@@ -386,6 +386,9 @@ let nextFileUploadId = 0;
     />
   `,
 })
+/**
+ * File / camera / drag-and-drop picker following the shared AFRICANIES form field pattern.
+ */
 export class FileUploadComponent implements ControlValueAccessor, OnDestroy {
   private readonly destroyRef = inject(DestroyRef);
   /** Optional so the control still works when overlays are not registered. */