@africanies/angular-web-sdk 0.1.11 → 0.1.13

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

@@ -3,14 +3,14 @@ import type { IconName } from '@africanies/africanies-icons';
 import type { HeaderWeather, HeaderWeatherKind } from './header-greeting.util';
 
 /** Bump when cache shape or city resolution strategy changes. */
-const CACHE_KEY = 'africanies-header-weather-v7';
-const FETCH_MS = 4_000;
-const BROWSER_GEO_MS = 3_500;
-/** IP fallback — city string is used only when reverse-geocode is empty. */
+const CACHE_KEY = 'africanies-header-weather-v8';
+const FETCH_MS = 8_000;
+/** After Allow, wait for a GPS/Wi-Fi fix. A short timeout loses the prompt and falls through to IP. */
+const DEVICE_GEO_MS = 15_000;
+const DEVICE_GEO_PROMPT_MS = 25_000;
+/** IP city is the office egress (often Lagos) and must not label the device. */
 const GEO_URL = 'https://get.geojs.io/v1/ip/geo.json';
-/** Client reverse-geocode so the label matches the forecast coordinates. */
-const REVERSE_GEO_URL =
-  'https://api.bigdatacloud.net/data/reverse-geocode-client';
+const REVERSE_GEO_URL = 'https://geocoding-api.open-meteo.com/v1/reverse';
 
 const WEATHER_LABELS: Record<HeaderWeatherKind, string> = {
   clear: 'Clear',
@@ -36,9 +36,10 @@ interface GeoJsPayload {
 }
 
 interface ReverseGeoPayload {
-  city?: string;
-  locality?: string;
-  principalSubdivision?: string;
+  results?: Array<{
+    name?: string;
+    admin1?: string;
+  }>;
 }
 
 interface OpenMeteoPayload {
@@ -119,15 +120,16 @@ export function headerWeatherIcon(kind: HeaderWeatherKind, hour: number): IconNa
 }
 
 /**
- * City-level forecast via browser / IP geolocation + Open-Meteo (no API key).
+ * City-level forecast. The label is the device location only.
  *
- * Coordinates prefer the browser Geolocation API (accurate for travellers;
- * may prompt once). Otherwise IP geo is used. The city label is reverse-
- * geocoded from those coordinates, with the IP city as a fallback.
+ * The Geolocation API (GPS / nearby Wi-Fi) is reverse-geocoded. IP lookup is
+ * not used for the city — a shared office egress makes every colleague "Lagos".
+ * If the device fix is refused, weather still loads from IP coordinates with
+ * no city.
  *
  * Fails closed: missing browser APIs, timeouts, and HTTP errors all return
- * `null` so the greeting can stay time-of-day only. Cached per local hour
- * in `sessionStorage`.
+ * `null` so the greeting can stay time-of-day only. A snapshot with a city
+ * is cached per local hour in `sessionStorage`.
  *
  * @param fetchFn - Injected `fetch` for tests.
  * @returns Forecast snapshot, or `null` when lookup fails.
@@ -147,7 +149,8 @@ export async function loadHeaderWeather(
   }
 
   try {
-    const coords = await resolveCoordinates(run);
+    const device = await tryDeviceCoordinates();
+    const coords = device ?? (await ipCoordinates(run));
     if (!coords) {
       return null;
     }
@@ -168,11 +171,13 @@ export async function loadHeaderWeather(
     }
 
     const temperatureC = asNumber(forecast?.current?.temperature_2m) ?? undefined;
-    const city =
-      (await reverseGeocodeCity(run, coords.latitude, coords.longitude)) ??
-      coords.fallbackCity;
+    const city = device
+      ? await reverseGeocodeCity(run, device.latitude, device.longitude)
+      : undefined;
     const weather: HeaderWeather = { kind, temperatureC, city };
-    writeCache({ hour, kind, temperatureC, city });
+    if (city) {
+      writeCache({ hour, kind, temperatureC, city });
+    }
     return weather;
   } catch {
     return null;
@@ -221,41 +226,17 @@ function writeCache(value: CachedWeather): void {
   }
 }
 
-/**
- * Prefer device coordinates when available (may prompt once); otherwise fall
- * back to IP geo. IP is always fetched in parallel so its city can backfill
- * the label when reverse-geocode is empty (browser geo has no city string).
- */
-async function resolveCoordinates(
-  fetchFn: typeof fetch,
-): Promise<(Coordinates & { fallbackCity?: string }) | null> {
-  const [browser, ipGeo] = await Promise.all([
-    tryBrowserGeolocation(),
-    fetchIpGeo(fetchFn),
-  ]);
-  const ipCity = asCity(ipGeo?.city);
-
-  if (browser) {
-    return { ...browser, fallbackCity: ipCity };
-  }
-
-  const latitude = asNumber(ipGeo?.latitude);
-  const longitude = asNumber(ipGeo?.longitude);
+async function ipCoordinates(fetchFn: typeof fetch): Promise<Coordinates | null> {
+  const payload = (await fetchJson(fetchFn, GEO_URL)) as GeoJsPayload | null;
+  const latitude = asNumber(payload?.latitude);
+  const longitude = asNumber(payload?.longitude);
   if (latitude === null || longitude === null) {
     return null;
   }
-  return {
-    latitude,
-    longitude,
-    fallbackCity: ipCity,
-  };
+  return { latitude, longitude };
 }
 
-async function fetchIpGeo(fetchFn: typeof fetch): Promise<GeoJsPayload | null> {
-  return (await fetchJson(fetchFn, GEO_URL)) as GeoJsPayload | null;
-}
-
-async function tryBrowserGeolocation(): Promise<Coordinates | null> {
+async function tryDeviceCoordinates(): Promise<Coordinates | null> {
   if (
     typeof navigator === 'undefined' ||
     typeof navigator.geolocation?.getCurrentPosition !== 'function'
@@ -263,8 +244,14 @@ async function tryBrowserGeolocation(): Promise<Coordinates | null> {
     return null;
   }
 
+  const permission = await geolocationPermission();
+  if (permission === 'denied') {
+    return null;
+  }
+
+  const timeout = permission === 'granted' ? DEVICE_GEO_MS : DEVICE_GEO_PROMPT_MS;
   return await new Promise((resolve) => {
-    const timer = setTimeout(() => resolve(null), BROWSER_GEO_MS);
+    const timer = setTimeout(() => resolve(null), timeout);
     navigator.geolocation.getCurrentPosition(
       (position) => {
         clearTimeout(timer);
@@ -278,14 +265,23 @@ async function tryBrowserGeolocation(): Promise<Coordinates | null> {
         resolve(null);
       },
       {
-        enableHighAccuracy: false,
-        maximumAge: 600_000,
-        timeout: BROWSER_GEO_MS,
+        enableHighAccuracy: true,
+        maximumAge: 0,
+        timeout,
       },
     );
   });
 }
 
+async function geolocationPermission(): Promise<PermissionState | 'unknown'> {
+  try {
+    const status = await navigator.permissions?.query({ name: 'geolocation' });
+    return status?.state ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
 async function reverseGeocodeCity(
   fetchFn: typeof fetch,
   latitude: number,
@@ -294,13 +290,10 @@ async function reverseGeocodeCity(
   const url =
     `${REVERSE_GEO_URL}?latitude=${encodeURIComponent(String(latitude))}` +
     `&longitude=${encodeURIComponent(String(longitude))}` +
-    `&localityLanguage=en`;
+    `&language=en&count=1`;
   const payload = (await fetchJson(fetchFn, url)) as ReverseGeoPayload | null;
-  return (
-    asCity(payload?.city) ??
-    asCity(payload?.locality) ??
-    asCity(payload?.principalSubdivision)
-  );
+  const place = payload?.results?.[0];
+  return asCity(place?.name) ?? asCity(place?.admin1);
 }
 
 function asNumber(value: unknown): number | null {

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

@@ -54,6 +54,9 @@ import { ChangeDetectionStrategy, Component, input } from '@angular/core';
     }
   `,
 })
+/**
+ * Page title + subtitle for product screens.
+ */
 export class PageHeaderComponent {
   /** Page heading. Omit when the shell already rendered a title. */
   readonly title = input('');

package/libs/africanies-ui/src/lib/modules/africanies-actions.module.ts

@@ -32,4 +32,7 @@ const ACTIONS = [
   imports: [...ACTIONS],
   exports: [...ACTIONS],
 })
+/**
+ * Button, copy-to-clipboard control, overflow action menu, and avatar menu.
+ */
 export class AfricaniesActionsModule {}

package/libs/africanies-ui/src/lib/modules/africanies-feedback.module.ts

@@ -39,4 +39,7 @@ const FEEDBACK = [
   imports: [...FEEDBACK],
   exports: [...FEEDBACK],
 })
+/**
+ * Async feedback states, accordion panels, inline alert, and status chips.
+ */
 export class AfricaniesFeedbackModule {}

package/libs/africanies-ui/src/lib/modules/africanies-forms.module.ts

@@ -6,6 +6,7 @@ import { DatePickerComponent } from '../forms/date-picker';
 import { FileUploadComponent } from '../forms/file-upload';
 import { NumberInputComponent } from '../forms/number-input';
 import { OtpInputComponent } from '../forms/otp-input';
+import { PhoneInputComponent } from '../forms/phone-input';
 import { RadioComponent } from '../forms/radio';
 import { SelectComponent } from '../forms/select';
 import { TextInputComponent } from '../forms/text-input';
@@ -24,6 +25,7 @@ const FORM_CONTROLS = [
   DatePickerComponent,
   FileUploadComponent,
   OtpInputComponent,
+  PhoneInputComponent,
 ] as const;
 
 /**
@@ -43,4 +45,7 @@ const FORM_CONTROLS = [
   imports: [...FORM_CONTROLS],
   exports: [...FORM_CONTROLS],
 })
+/**
+ * All form controls in one import for apps that prefer NgModules.
+ */
 export class AfricaniesFormsModule {}

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

@@ -26,4 +26,7 @@ import {
     InfoPopoverTriggerDirective,
   ],
 })
+/**
+ * NgModule facade for {@link InfoPopoverComponent} and its trigger/content markers.
+ */
 export class AfricaniesInfoPopoverModule {}

package/libs/africanies-ui/src/lib/modules/africanies-navigation.module.ts

@@ -48,4 +48,7 @@ const NAV = [
   imports: [...NAV],
   exports: [...NAV],
 })
+/**
+ * App shell, breadcrumb, tabs (+ `africaniesTabDef`), segment, side nav, shipping mode switch, brand logo, avatar menu, and shell header chrome.
+ */
 export class AfricaniesNavigationModule {}

package/libs/africanies-ui/src/lib/modules/africanies-stepper.module.ts

@@ -19,4 +19,7 @@ const STEPPER = [StepperComponent, StepDefDirective] as const;
   imports: [...STEPPER],
   exports: [...STEPPER],
 })
+/**
+ * Stepper (+ `africaniesStepDef`).
+ */
 export class AfricaniesStepperModule {}

package/libs/africanies-ui/src/lib/modules/africanies-table.module.ts

@@ -25,4 +25,7 @@ const DATA = [
   imports: [...DATA],
   exports: [...DATA],
 })
+/**
+ * Table (+ `africaniesCellDef`) and pagination.
+ */
 export class AfricaniesTableModule {}

package/libs/africanies-ui/src/lib/modules/africanies-tooltip.module.ts

@@ -22,4 +22,7 @@ const TOOLTIP = [TooltipComponent, TooltipTriggerDirective] as const;
   imports: [...TOOLTIP],
   exports: [...TOOLTIP],
 })
+/**
+ * Tooltip (+ `africaniesTooltipTrigger`).
+ */
 export class AfricaniesTooltipModule {}

package/libs/africanies-ui/src/lib/navigation/breadcrumb/breadcrumb.component.ts

@@ -95,6 +95,9 @@ import type { AfricaniesNavItem } from '../nav-item';
     </nav>
   `,
 })
+/**
+ * Breadcrumb trail for hierarchical navigation.
+ */
 export class BreadcrumbComponent {
   protected readonly modeColor = inject(ModeColorService);
 

package/libs/africanies-ui/src/lib/navigation/segment/segment.component.ts

@@ -70,8 +70,9 @@ const DEFAULT_LINK_ACTIVE: IsActiveMatchOptions = {
   changeDetection: ChangeDetectionStrategy.OnPush,
   imports: [AfricaniesIconComponent],
   styles: `
+    /* Track p-1 (0.25×2) + 0.25 gap between pills — keep right inset equal to left. */
     :host .africanies-segment-thumb {
-      width: calc((100% - 0.5rem) / 2);
+      width: calc((100% - 0.75rem) / 2);
     }
   `,
   template: `
@@ -134,6 +135,9 @@ const DEFAULT_LINK_ACTIVE: IsActiveMatchOptions = {
     </div>
   `,
 })
+/**
+ * Compact segmented control for view modes and filters.
+ */
 export class SegmentComponent {
   private readonly router = inject(Router);
   protected readonly modeColor = inject(ModeColorService);

package/libs/africanies-ui/src/lib/navigation/shipping-mode-switch/shipping-mode-switch.component.ts

@@ -211,6 +211,9 @@ const SHIPPING_MODE_GLYPH = `M88.42,68.75a48.8,48.8,0,0,1-4.74,11.1h9.89a7.67,7.
     }
   `,
 })
+/**
+ * Two-up shipping mode switcher for app-shell side navs.
+ */
 export class ShippingModeSwitchComponent {
   private readonly shipping = inject(ShippingModeService);
 

package/libs/africanies-ui/src/lib/navigation/side-nav/africanies-side-nav.component.ts

@@ -81,6 +81,9 @@ const DEFAULT_LINK_ACTIVE: IsActiveMatchOptions = {
   styleUrl: './africanies-side-nav.component.css',
   templateUrl: './africanies-side-nav.component.html',
 })
+/**
+ * App shell side navigation with icons, nested items, and a collapsible rail.
+ */
 export class SideNavComponent {
   protected readonly modeColor = inject(ModeColorService);
   private readonly defaultLogoUrl = inject(AFRICANIES_BRAND_LOGO_URL);

package/libs/africanies-ui/src/lib/navigation/tabs/tab-def.directive.ts

@@ -23,6 +23,9 @@ export interface TabDefContext {
   selector: '[africaniesTabDef]',
   standalone: true,
 })
+/**
+ * Registers projected tab panel content against a tab id for {@link TabsComponent} (local / non-router mode).
+ */
 export class TabDefDirective {
   /** Template projected as the active tab panel. */
   readonly template = inject(TemplateRef<TabDefContext>);

package/libs/africanies-ui/src/lib/navigation/tabs/tabs.component.ts

@@ -155,6 +155,9 @@ const DEFAULT_LINK_ACTIVE: IsActiveMatchOptions = {
     </div>
   `,
 })
+/**
+ * Tab list for page / section navigation.
+ */
 export class TabsComponent {
   private readonly router = inject(Router);
   protected readonly modeColor = inject(ModeColorService);

package/libs/africanies-ui/src/lib/notifications/notification-drawer.panel.ts

@@ -272,6 +272,9 @@ const MARK_ALL_CONFIRM_MS = 4000;
     </div>
   `,
 })
+/**
+ * Right-edge drawer listing in-app notifications.
+ */
 export class NotificationDrawerPanel {
   protected readonly ref =
     inject<AfricaniesOverlayRef<NotificationDrawerResult>>(AfricaniesOverlayRef);

package/libs/africanies-ui/src/lib/notifications/notification-drawer.service.ts

@@ -15,6 +15,9 @@ import { NotificationDrawerPanel } from './notification-drawer.panel';
  * Requires {@link provideAfricaniesUiOverlays} at bootstrap.
  */
 @Injectable({ providedIn: 'root' })
+/**
+ * Opens {@link NotificationDrawerPanel} via {@link DrawerService}.
+ */
 export class NotificationDrawerService {
   private readonly drawer = inject(DrawerService);
 

package/libs/africanies-ui/src/lib/overlay/confirm-dialog.component.ts

@@ -115,6 +115,9 @@ import { OVERLAY_DATA } from './overlay-data.token';
     </div>
   `,
 })
+/**
+ * Built-in confirm dialog hosted by {@link ConfirmService} / {@link ModalService}.
+ */
 export class ConfirmDialogComponent {
   /** Stable ids so aria-labelledby / aria-describedby stay unique per instance. */
   protected readonly titleId = `africanies-confirm-title-${cryptoRandom()}`;

package/libs/africanies-ui/src/lib/overlay/confirm.service.ts

@@ -33,6 +33,9 @@ import { ModalService } from './modal.service';
  * ```
  */
 @Injectable()
+/**
+ * One-line confirm flow built on {@link ModalService}.
+ */
 export class ConfirmService {
   private readonly modal = inject(ModalService);
 

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

@@ -21,6 +21,9 @@ import {
  * ```
  */
 @Injectable()
+/**
+ * Opens edge-anchored drawer panels via Angular CDK Overlay.
+ */
 export class DrawerService implements OverlayOpener {
   private readonly overlay = inject(Overlay);
   private readonly injector = inject(Injector);

package/libs/africanies-ui/src/lib/overlay/modal.service.ts

@@ -72,6 +72,9 @@ export interface ModalOpenConfig<TData = unknown>
  * ```
  */
 @Injectable()
+/**
+ * Opens centered modal dialogs via Angular CDK Overlay.
+ */
 export class ModalService implements OverlayOpener {
   private readonly overlay = inject(Overlay);
   private readonly injector = inject(Injector);

package/libs/africanies-ui/src/lib/overlay/overlay-frame.component.ts

@@ -18,6 +18,9 @@ import { ChangeDetectionStrategy, Component, Directive } from '@angular/core';
   selector: '[africaniesOverlayHeader]',
   standalone: true,
 })
+/**
+ * Marks projected chrome as the non-scrolling overlay header (title + close).
+ */
 export class OverlayHeaderDirective {}
 
 /**
@@ -38,6 +41,9 @@ export class OverlayHeaderDirective {}
   selector: '[africaniesOverlayFooter]',
   standalone: true,
 })
+/**
+ * Marks projected chrome as the non-scrolling overlay footer (actions).
+ */
 export class OverlayFooterDirective {}
 
 /**
@@ -92,4 +98,7 @@ export class OverlayFooterDirective {}
     </div>
   `,
 })
+/**
+ * Header / scroll body / footer shell for {@link ModalService} and {@link DrawerService} panels.
+ */
 export class OverlayFrameComponent {}

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

@@ -181,6 +181,9 @@ type PageItem = number | 'ellipsis';
     </nav>
   `,
 })
+/**
+ * Page-size select, numbered pager, and prev/next — driven by {@link PaginationMetaModel} from the API envelope.
+ */
 export class PaginationComponent {
   private readonly filterQuery = inject(FilterQueryService);
   protected readonly modeColor = inject(ModeColorService);

package/libs/africanies-ui/src/lib/stepper/step-def.directive.ts

@@ -30,6 +30,9 @@ export interface StepDefContext {
   selector: '[africaniesStepDef]',
   standalone: true,
 })
+/**
+ * Registers projected step body content against a step key for {@link StepperComponent}.
+ */
 export class StepDefDirective {
   /** Template projected as the active step body. */
   readonly template = inject(TemplateRef<StepDefContext>);

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

@@ -136,6 +136,9 @@ function prefersReducedMotion(): boolean {
     </div>
   `,
 })
+/**
+ * Multi-step wizard for form flows (e.g. shipment creation).
+ */
 export class StepperComponent {
   protected readonly modeColor = inject(ModeColorService);
 

package/libs/africanies-ui/src/lib/table/cell-def.directive.ts

@@ -30,6 +30,9 @@ export interface CellDefContext<T = unknown> {
   selector: '[africaniesCellDef]',
   standalone: true,
 })
+/**
+ * Registers a projected cell template against a column key for {@link TableComponent}.
+ */
 export class CellDefDirective {
   /** Template projected into matching column body cells. */
   readonly template = inject(TemplateRef<CellDefContext>);

package/libs/africanies-ui/src/lib/table/header-cell-def.directive.ts

@@ -18,6 +18,9 @@ import { Directive, inject, input, TemplateRef } from '@angular/core';
   selector: '[africaniesHeaderCellDef]',
   standalone: true,
 })
+/**
+ * Registers a projected header cell template against a column key for {@link TableComponent}.
+ */
 export class HeaderCellDefDirective {
   /** Template projected into the matching column header cell. */
   readonly template = inject(TemplateRef);

package/libs/africanies-ui/src/lib/table/row-detail-def.directive.ts

@@ -25,6 +25,9 @@ export type RowDetailDefContext<T = unknown> = CellDefContext<T>;
   selector: '[africaniesRowDetail]',
   standalone: true,
 })
+/**
+ * Registers a label / value pair inside an expanded table row.
+ */
 export class RowDetailDefDirective {
   /** Template rendered as the detail value. */
   readonly template = inject(TemplateRef<RowDetailDefContext>);

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

@@ -499,6 +499,9 @@ import { TableColumn, TableSortChange } from './table-column';
     </div>
   `,
 })
+/**
+ * Presentational data table with template-based cells.
+ */
 export class TableComponent<T = unknown> {
   private readonly destroyRef = inject(DestroyRef);
   protected readonly shipping = inject(ShippingModeService);

package/libs/africanies-ui/src/lib/toast/toast-host.component.ts

@@ -25,7 +25,7 @@ import { ToastItemComponent } from './toast-item.component';
     <div class="flex w-full flex-col gap-2">
       @if (toastService.showHostActions()) {
         <div
-          class="sticky top-0 z-10 flex flex-wrap justify-end gap-2 bg-white/80 pb-1 backdrop-blur-sm dark:bg-ink-surface/80"
+          class="sticky top-0 z-10 flex flex-wrap justify-end gap-2 bg-transparent pb-1 backdrop-blur-sm dark:bg-transparent"
         >
           @if (toastService.hasStacks()) {
             @if (toastService.allStacksExpanded()) {
@@ -78,6 +78,9 @@ import { ToastItemComponent } from './toast-item.component';
     </div>
   `,
 })
+/**
+ * Fixed stack host attached once by {@link ToastService.ensureHost}. Caps to the viewport and scrolls when the stack (or an expanded group) would otherwise run off-screen.
+ */
 export class ToastHostComponent {
   protected readonly toastService = inject(ToastService);
   protected readonly toasts = this.toastService.items;

package/libs/africanies-ui/src/lib/toast/toast-item.component.ts

@@ -221,6 +221,9 @@ import {
     }
   `,
 })
+/**
+ * Single toast card — dense, token-based, with optional countdown rail. Stacked identical toasts can expand; close peels the outermost copy.
+ */
 export class ToastItemComponent {
   /** Stack entry to render. */
   readonly item = input.required<ToastItem>();

package/libs/africanies-ui/src/lib/toast/toast.service.ts

@@ -47,6 +47,9 @@ type PopoverToggles = {
  * Prefer {@link provideAfricaniesToasts} at bootstrap so the host overlay mounts once.
  */
 @Injectable()
+/**
+ * Imperative toast stack for AFRICANIES apps.
+ */
 export class ToastService implements AfricaniesHttpToastHandler {
   private readonly overlay = inject(Overlay);
   private readonly injector = inject(Injector);

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

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

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

@@ -191,6 +191,9 @@ const PLACEMENT_POSITIONS: Record<TooltipPlacement, ConnectedPosition[]> = {
     </ng-template>
   `,
 })
+/**
+ * Contextual help tip — default info icon or a custom projected trigger.
+ */
 export class TooltipComponent {
   protected readonly tooltipId = `africanies-tooltip-${++nextTooltipId}`;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@africanies/angular-web-sdk",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "packageManager": "pnpm@11.24.0",
   "license": "MIT",
   "contributors": [