@africanies/angular-web-sdk 0.1.12 → 0.1.13

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

@@ -37,12 +37,12 @@ export {
   PHONE_DIAL_CODES,
   PHONE_MAX_NATIONAL_DIGITS,
   PHONE_MIN_NATIONAL_DIGITS,
-  type PhoneCountryOption,
-  PhoneInputComponent,
-  type PhoneNumberValue,
   phoneCountryName,
+  type PhoneCountryOption,
   phoneCountryOptions,
   phoneDigitsOnly,
+  PhoneInputComponent,
+  type PhoneNumberValue,
   phoneToE164,
   removeDialCode,
 } from './phone-input';

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

@@ -148,6 +148,9 @@ function formatWhileTyping(raw: string): {
     }
   `,
 })
+/**
+ * Numeric field following the shared AFRICANIES form field pattern.
+ */
 export class NumberInputComponent implements ControlValueAccessor {
   protected readonly controlId = `africanies-number-input-${++nextNumberInputId}`;
   protected readonly hintId = `${this.controlId}-hint`;

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

@@ -148,6 +148,9 @@ export type OtpInputVariant = 'default' | 'masked';
     </div>
   `,
 })
+/**
+ * One-time-passcode field — discrete digit cells, single string model.
+ */
 export class OtpInputComponent implements ControlValueAccessor, OnDestroy {
   private readonly destroyRef = inject(DestroyRef);
   private readonly cellInputs =

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

@@ -1,3 +1,8 @@
+import {
+  CdkConnectedOverlay,
+  CdkOverlayOrigin,
+  type ConnectedPosition,
+} from '@angular/cdk/overlay';
 import {
   afterNextRender,
   booleanAttribute,
@@ -15,18 +20,13 @@ import {
   untracked,
   viewChild,
 } from '@angular/core';
-import {
-  CdkConnectedOverlay,
-  CdkOverlayOrigin,
-  type ConnectedPosition,
-} from '@angular/cdk/overlay';
 import {
   type ControlValueAccessor,
   NG_VALUE_ACCESSOR,
 } from '@angular/forms';
 
-import { AfricaniesIconComponent } from '@africanies/africanies-icons';
 import { countryFlagUrl } from '@africanies/africanies-core';
+import { AfricaniesIconComponent } from '@africanies/africanies-icons';
 
 import {
   FORM_DISABLED_CLASS,
@@ -225,6 +225,9 @@ const PANEL_POSITIONS: ConnectedPosition[] = [
     </ng-template>
   `,
 })
+/**
+ * International phone field — flag + dial code + national number.
+ */
 export class PhoneInputComponent implements ControlValueAccessor {
   protected readonly controlId = `africanies-phone-input-${++nextPhoneInputId}`;
   protected readonly hintId = `${this.controlId}-hint`;

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

@@ -118,6 +118,9 @@ let nextRadioId = 0;
     </fieldset>
   `,
 })
+/**
+ * Radio group following the shared AFRICANIES form field pattern.
+ */
 export class RadioComponent<T = string> implements ControlValueAccessor {
   private readonly modeColor = inject(ModeColorService);
 

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

@@ -269,6 +269,9 @@ const PANEL_POSITIONS: ConnectedPosition[] = [
     }
   `,
 })
+/**
+ * Generic type-as-you-search combobox with a debounced async lookup and overlay result list.
+ */
 export class SearchComboboxComponent<T> implements ControlValueAccessor {
   private readonly destroyRef = inject(DestroyRef);
 

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

@@ -443,6 +443,9 @@ const SELECT_PANEL_POSITIONS: ConnectedPosition[] = [
     }
   `,
 })
+/**
+ * Option select following the shared AFRICANIES form field pattern.
+ */
 export class SelectComponent<T = string> implements ControlValueAccessor {
   private readonly modal = inject(ModalService, { optional: true });
   protected readonly modeColor = inject(ModeColorService);

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

@@ -115,6 +115,9 @@ export type TextInputType =
     }
   `,
 })
+/**
+ * Single-line text field — **reference** form control for `@africanies/africanies-ui`.
+ */
 export class TextInputComponent implements ControlValueAccessor {
   /** Stable ids so label / aria-describedby stay paired across re-renders. */
   protected readonly controlId = `africanies-text-input-${++nextTextInputId}`;

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

@@ -82,6 +82,9 @@ let nextTextareaId = 0;
     }
   `,
 })
+/**
+ * Multi-line text field following the shared form-control pattern (`shared AFRICANIES form field pattern`). Supports prefix/suffix slots, field-level `error`, and {@link ControlValueAccessor}.
+ */
 export class TextareaComponent implements ControlValueAccessor {
   protected readonly controlId = `africanies-textarea-${++nextTextareaId}`;
   protected readonly hintId = `${this.controlId}-hint`;

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

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

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

@@ -95,6 +95,9 @@ export type ImageFit = 'cover' | 'contain';
     </div>
   `,
 })
+/**
+ * Image with a shaped loading frame and fallback while the asset fetches or if it fails to render.
+ */
 export class ImageComponent {
   private readonly imgRef = viewChild<ElementRef<HTMLImageElement>>('img');
 

package/libs/africanies-ui/src/lib/info-popover/info-popover-content.directive.ts

@@ -20,4 +20,7 @@ import { Directive } from '@angular/core';
   selector: '[africaniesInfoPopoverContent]',
   standalone: true,
 })
+/**
+ * Marks projected content as the panel body for {@link InfoPopoverComponent}.
+ */
 export class InfoPopoverContentDirective {}

package/libs/africanies-ui/src/lib/info-popover/info-popover-trigger.directive.ts

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

package/libs/africanies-ui/src/lib/info-popover/info-popover.component.ts

@@ -205,6 +205,9 @@ const PLACEMENT_POSITIONS: Record<InfoPopoverPlacement, ConnectedPosition[]> = {
     </ng-template>
   `,
 })
+/**
+ * Hover / focus / click info panel with a white card, optional title, and fully projected body content (any child component or markup).
+ */
 export class InfoPopoverComponent {
   protected readonly panelId = `africanies-info-popover-${++nextInfoPopoverId}`;
 

package/libs/africanies-ui/src/lib/layout/app-shell-content-header.component.ts

@@ -71,6 +71,9 @@ import { PageHeaderComponent } from './page-header.component';
     }
   `,
 })
+/**
+ * Content chrome above the app-shell body: Back, breadcrumbs, then the page title and optional subtitle.
+ */
 export class AppShellContentHeaderComponent {
   private readonly router = inject(Router);
 

package/libs/africanies-ui/src/lib/layout/app-shell-header-slot.directive.ts

@@ -9,4 +9,7 @@ import { Directive } from '@angular/core';
   selector: '[africaniesAppShellHeader]',
   standalone: true,
 })
+/**
+ * Marks projected content as the custom header for {@link AppShellComponent}.
+ */
 export class AppShellHeaderSlotDirective {}

package/libs/africanies-ui/src/lib/layout/app-shell-header.component.ts

@@ -38,6 +38,9 @@ export type AppShellHeaderDensity = 'mobile' | 'tablet' | 'desktop';
   selector: '[africaniesAppShellHeaderStart]',
   standalone: true,
 })
+/**
+ * Marks projected content as extra leading chrome in {@link AppShellHeaderComponent}.
+ */
 export class AppShellHeaderStartDirective {}
 
 /**
@@ -47,6 +50,9 @@ export class AppShellHeaderStartDirective {}
   selector: '[africaniesAppShellHeaderEnd]',
   standalone: true,
 })
+/**
+ * Marks projected content as extra trailing chrome in {@link AppShellHeaderComponent}.
+ */
 export class AppShellHeaderEndDirective {}
 
 /**
@@ -206,6 +212,9 @@ export class AppShellHeaderEndDirective {}
     </div>
   `,
 })
+/**
+ * Product header bar for {@link AppShellComponent}: a short time-of-day kicker plus the given name, local weather, live clock, notification inbox drawer, and avatar menu. Breadcrumbs and Back belong in the content column via {@link AppShellContentHeaderComponent}.
+ */
 export class AppShellHeaderComponent {
   private readonly notificationsDrawer = inject(NotificationDrawerService);
   private readonly destroyRef = inject(DestroyRef);

package/libs/africanies-ui/src/lib/layout/app-shell.component.ts

@@ -85,6 +85,9 @@ export type AppShellLayoutPreview = 'mobile' | 'tablet' | 'desktop';
   },
   templateUrl: './app-shell.component.html',
 })
+/**
+ * Application chrome scaffold: side nav + sticky header + constrained content.
+ */
 export class AppShellComponent {
   protected readonly modeColor = inject(ModeColorService);
   protected readonly logoMiniUrl = inject(AFRICANIES_BRAND_LOGO_MINI_URL);

package/libs/africanies-ui/src/lib/layout/header-weather.spec.ts

@@ -66,18 +66,15 @@ describe('loadHeaderWeather', () => {
     ).resolves.toBeNull();
   });
 
-  it('reads Open-Meteo after IP geolocation and reverse-geocodes the city', async () => {
+  it('does not label the device with the IP city', async () => {
     const fetchFn = jest.fn(async (url: string) => {
       if (String(url).includes('geojs')) {
         return jsonResponse({
-          latitude: '9.0765',
-          longitude: '7.3986',
+          latitude: '6.45',
+          longitude: '3.4',
           city: 'Lagos',
         });
       }
-      if (String(url).includes('bigdatacloud')) {
-        return jsonResponse({ city: 'Abuja', locality: 'Abuja' });
-      }
       return jsonResponse({
         current: { weather_code: 61, temperature_2m: 27.4 },
       });
@@ -88,38 +85,18 @@ describe('loadHeaderWeather', () => {
     ).resolves.toEqual({
       kind: 'rain',
       temperatureC: 27.4,
-      city: 'Abuja',
-    });
-    expect(fetchFn).toHaveBeenCalledTimes(3);
-  });
-
-  it('falls back to the IP city when reverse geocode is empty', async () => {
-    const fetchFn = jest.fn(async (url: string) => {
-      if (String(url).includes('geojs')) {
-        return jsonResponse({ latitude: 1, longitude: 2, city: 'Lagos' });
-      }
-      if (String(url).includes('bigdatacloud')) {
-        return jsonResponse({});
-      }
-      return jsonResponse({ current: { weather_code: 0, temperature_2m: 30 } });
-    });
-
-    await expect(
-      loadHeaderWeather(fetchFn as unknown as typeof fetch),
-    ).resolves.toEqual({
-      kind: 'clear',
-      temperatureC: 30,
-      city: 'Lagos',
+      city: undefined,
     });
+    expect(fetchFn).not.toHaveBeenCalledWith(
+      expect.stringContaining('geocoding-api'),
+    );
   });
 
-  it('reuses the same-hour session cache', async () => {
+  it('reuses the same-hour session cache when the device city was resolved', async () => {
+    stubDeviceAt(9.0765, 7.3986);
     const fetchFn = jest.fn(async (url: string) => {
-      if (String(url).includes('geojs')) {
-        return jsonResponse({ latitude: 1, longitude: 2 });
-      }
-      if (String(url).includes('bigdatacloud')) {
-        return jsonResponse({ city: 'Accra' });
+      if (String(url).includes('geocoding-api')) {
+        return jsonResponse({ results: [{ name: 'Abuja' }] });
       }
       return jsonResponse({ current: { weather_code: 0, temperature_2m: 30 } });
     });
@@ -127,17 +104,16 @@ describe('loadHeaderWeather', () => {
     const first = await loadHeaderWeather(fetchFn as unknown as typeof fetch);
     const second = await loadHeaderWeather(fetchFn as unknown as typeof fetch);
 
-    expect(first).toEqual(second);
-    expect(fetchFn).toHaveBeenCalledTimes(3);
+    expect(first).toEqual({ kind: 'clear', temperatureC: 30, city: 'Abuja' });
+    expect(second).toEqual(first);
+    expect(fetchFn).toHaveBeenCalledTimes(2);
   });
 
   it('fetches again when the cached hour no longer matches', async () => {
+    stubDeviceAt(9.0765, 7.3986);
     const fetchFn = jest.fn(async (url: string) => {
-      if (String(url).includes('geojs')) {
-        return jsonResponse({ latitude: 1, longitude: 2, city: 'Lagos' });
-      }
-      if (String(url).includes('bigdatacloud')) {
-        return jsonResponse({ city: 'Lagos' });
+      if (String(url).includes('geocoding-api')) {
+        return jsonResponse({ results: [{ name: 'Abuja' }] });
       }
       return jsonResponse({ current: { weather_code: 0, temperature_2m: 30.2 } });
     });
@@ -146,7 +122,7 @@ describe('loadHeaderWeather', () => {
     const cacheKey = Object.keys(sessionStorage).find((key) =>
       key.startsWith('africanies-header-weather'),
     );
-    expect(cacheKey).toBeDefined();
+    expect(cacheKey).toBe('africanies-header-weather-v8');
     const stored = JSON.parse(sessionStorage.getItem(cacheKey!) ?? '{}') as {
       hour?: string;
     };
@@ -154,35 +130,15 @@ describe('loadHeaderWeather', () => {
     sessionStorage.setItem(cacheKey!, JSON.stringify(stored));
 
     await loadHeaderWeather(fetchFn as unknown as typeof fetch);
-    expect(fetchFn).toHaveBeenCalledTimes(6);
+    expect(fetchFn).toHaveBeenCalledTimes(4);
   });
 
-  it('uses browser coordinates when geolocation succeeds', async () => {
-    Object.defineProperty(navigator, 'geolocation', {
-      configurable: true,
-      value: {
-        getCurrentPosition: (success: PositionCallback) => {
-          success({
-            coords: {
-              latitude: 9.0765,
-              longitude: 7.3986,
-              accuracy: 10,
-              altitude: null,
-              altitudeAccuracy: null,
-              heading: null,
-              speed: null,
-              toJSON: () => ({}),
-            },
-            timestamp: Date.now(),
-            toJSON: () => ({}),
-          } as GeolocationPosition);
-        },
-      },
-    });
+  it('uses device coordinates and ignores the IP city', async () => {
+    stubDeviceAt(9.0765, 7.3986);
 
     const fetchFn = jest.fn(async (url: string) => {
-      if (String(url).includes('bigdatacloud')) {
-        return jsonResponse({ city: 'Abuja' });
+      if (String(url).includes('geocoding-api')) {
+        return jsonResponse({ results: [{ name: 'Abuja' }] });
       }
       if (String(url).includes('geojs')) {
         return jsonResponse({
@@ -201,34 +157,15 @@ describe('loadHeaderWeather', () => {
       temperatureC: 31,
       city: 'Abuja',
     });
+    expect(fetchFn).not.toHaveBeenCalledWith(expect.stringContaining('geojs'));
   });
 
-  it('uses the IP city when browser geo succeeds but reverse geocode is empty', async () => {
-    Object.defineProperty(navigator, 'geolocation', {
-      configurable: true,
-      value: {
-        getCurrentPosition: (success: PositionCallback) => {
-          success({
-            coords: {
-              latitude: 9.0765,
-              longitude: 7.3986,
-              accuracy: 10,
-              altitude: null,
-              altitudeAccuracy: null,
-              heading: null,
-              speed: null,
-              toJSON: () => ({}),
-            },
-            timestamp: Date.now(),
-            toJSON: () => ({}),
-          } as GeolocationPosition);
-        },
-      },
-    });
+  it('omits the city when the device fix has no place name', async () => {
+    stubDeviceAt(9.0765, 7.3986);
 
     const fetchFn = jest.fn(async (url: string) => {
-      if (String(url).includes('bigdatacloud')) {
-        return jsonResponse({ city: '' });
+      if (String(url).includes('geocoding-api')) {
+        return jsonResponse({ results: [{ name: '' }] });
       }
       if (String(url).includes('geojs')) {
         return jsonResponse({
@@ -245,13 +182,14 @@ describe('loadHeaderWeather', () => {
     ).resolves.toEqual({
       kind: 'clear',
       temperatureC: 31,
-      city: 'Lagos',
+      city: undefined,
     });
+    expect(fetchFn).not.toHaveBeenCalledWith(expect.stringContaining('geojs'));
   });
 
   it('refetches when the hour cache has weather but no city', async () => {
     sessionStorage.setItem(
-      'africanies-header-weather-v7',
+      'africanies-header-weather-v8',
       JSON.stringify({
         hour: `${new Date().getFullYear()}-${new Date().getMonth()}-${new Date().getDate()}-${new Date().getHours()}`,
         kind: 'cloudy',
@@ -274,7 +212,7 @@ describe('loadHeaderWeather', () => {
     ).resolves.toEqual({
       kind: 'cloudy',
       temperatureC: 25,
-      city: 'Lagos',
+      city: undefined,
     });
     expect(fetchFn).toHaveBeenCalled();
   });
@@ -304,6 +242,36 @@ describe('headerWeatherIcon', () => {
   });
 });
 
+function stubDeviceAt(latitude: number, longitude: number): void {
+  Object.defineProperty(navigator, 'permissions', {
+    configurable: true,
+    value: {
+      query: async () => ({ state: 'granted' }),
+    },
+  });
+  Object.defineProperty(navigator, 'geolocation', {
+    configurable: true,
+    value: {
+      getCurrentPosition: (success: PositionCallback) => {
+        success({
+          coords: {
+            latitude,
+            longitude,
+            accuracy: 10,
+            altitude: null,
+            altitudeAccuracy: null,
+            heading: null,
+            speed: null,
+            toJSON: () => ({}),
+          },
+          timestamp: Date.now(),
+          toJSON: () => ({}),
+        } as GeolocationPosition);
+      },
+    },
+  });
+}
+
 function jsonResponse(body: unknown): Pick<Response, 'ok' | 'json'> {
   return {
     ok: true,