@africanies/angular-web-sdk 0.1.4 → 0.1.5

package/.nx/cache/17626862048742598274/dist/libs/africanies-theme/types/africanies-africanies-theme.d.ts

@@ -0,0 +1,166 @@
+import * as i0 from '@angular/core';
+
+/**
+ * Tailwind safelist side-effect for shipping-mode color utilities.
+ *
+ * WHY this file exists: JIT/content scanning only keeps class names that appear
+ * as *literal strings* in scanned sources. {@link ModeColorService} already
+ * returns these literals, but keeping a dedicated comment list makes the
+ * contract obvious for consumers who configure `safelist` or purge plugins.
+ *
+ * Do not rename these strings without updating ModeColorService and THEME.md.
+ *
+ * SFN (export / green):
+ * text-export bg-export bg-export-subtle bg-export-light border-export
+ * hover:bg-export-light hover:bg-export-subtle dark:bg-export/15 dark:hover:bg-export/15
+ * dark:bg-[color-mix(in_srgb,#1cbd5d_15%,#212529)]
+ *
+ * STN (import / orange):
+ * text-import bg-import bg-import-subtle bg-import-light border-import
+ * hover:bg-import-light hover:bg-import-subtle dark:bg-import/15 dark:hover:bg-import/15
+ * dark:bg-[color-mix(in_srgb,#f08829_15%,#212529)]
+ */
+declare const MODE_COLOR_SAFELIST: readonly ["text-export", "bg-export", "bg-export-subtle", "bg-export-light", "border-export", "hover:bg-export-light", "hover:bg-export-subtle", "dark:bg-export/15", "dark:hover:bg-export/15", "dark:bg-[color-mix(in_srgb,#1cbd5d_15%,#212529)]", "text-import", "bg-import", "bg-import-subtle", "bg-import-light", "border-import", "hover:bg-import-light", "hover:bg-import-subtle", "dark:bg-import/15", "dark:hover:bg-import/15", "dark:bg-[color-mix(in_srgb,#f08829_15%,#212529)]"];
+
+/**
+ * Tailwind class bundle for the active shipping mode (SFN export / STN import).
+ *
+ * Use these for **primary** product chrome: CTAs, selected controls, progress,
+ * and accent text. Semantic colors (danger / warning) stay mode-independent.
+ */
+interface ModeColorClasses {
+    /** Text color utility, e.g. `text-export`. */
+    text: string;
+    /** Solid background utility, e.g. `bg-export`. */
+    bg: string;
+    /** Soft background utility, e.g. `bg-export-subtle`. */
+    bgSubtle: string;
+    /** Border matching the mode accent, e.g. `border-export`. */
+    border: string;
+    /**
+     * Filled primary CTA — `variant="primary"` on buttons.
+     * Includes hover utility as a literal so Tailwind keeps it.
+     */
+    primary: string;
+    /**
+     * Transparent / text-only CTA — `variant="ghost-primary"` on buttons.
+     * Mode accent text + soft hover fill.
+     */
+    ghostPrimary: string;
+    /**
+     * Soft highlight for selected / active rows (works in dark mode).
+     * Dark uses a translucent tint — fine over solid surfaces, not for
+     * sticky overlays (see {@link softSolid}).
+     */
+    soft: string;
+    /**
+     * Opaque soft fill — same tint as {@link soft}, but dark mode mixes into
+     * ink so scrolled content cannot show through (sticky table headers/cells).
+     */
+    softSolid: string;
+    /**
+     * Soft hover highlight for menus and lists.
+     */
+    softHover: string;
+}
+/**
+ * Maps {@link ShippingModeService} to mode-accent Tailwind classes.
+ *
+ * - **SFN** → export green is primary
+ * - **STN** → import orange is primary
+ *
+ * WHY literal class strings: Tailwind's scanner cannot see dynamically built
+ * names like `` `text-${token}` ``. Returning full literals (`text-export`, …)
+ * keeps utilities in the compiled CSS. See {@link MODE_COLOR_SAFELIST}.
+ *
+ * @example
+ * ```html
+ * @let colors = modeColor.classes();
+ * <button type="button" [class]="colors.primary">Save</button>
+ * <span [class]="colors.text">Mode accent</span>
+ * ```
+ */
+declare class ModeColorService {
+    private readonly shippingMode;
+    /**
+     * Mode-dependent utility classes. Recomputes when shipping mode changes.
+     */
+    readonly classes: i0.Signal<ModeColorClasses>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ModeColorService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ModeColorService>;
+}
+
+/**
+ * Supported UI color schemes for {@link ThemeService}.
+ *
+ * Kept as a closed string union so storage values and DOM class toggles stay
+ * aligned — unknown persisted strings are ignored and fall back to system
+ * preference / light.
+ */
+type Theme = 'light' | 'dark';
+
+/**
+ * Application light/dark theme preference.
+ *
+ * WHY signals (not BehaviorSubject): theme is synchronous UI state read from
+ * templates and other services; a signal avoids RxJS subscription boilerplate
+ * and matches Angular 22 change detection. Persistence goes through
+ * {@link STORAGE_TOKEN} so tests can swap storage without touching `localStorage`.
+ *
+ * Applies the Tailwind `darkMode: 'class'` contract by toggling `dark` on
+ * `document.documentElement`, and sets `color-scheme` so native UI (date
+ * pickers, scrollbars, form controls) matches the app theme — class-based
+ * dark mode alone does not restyle browser chrome.
+ *
+ * @example
+ * ```ts
+ * // app.config.ts
+ * import { inject, provideAppInitializer } from '@angular/core';
+ * import { ThemeService } from '@africanies/africanies-theme';
+ *
+ * export const appConfig = {
+ *   providers: [
+ *     provideAppInitializer(() => {
+ *       inject(ThemeService); // applies stored / system theme once
+ *     }),
+ *   ],
+ * };
+ *
+ * // In a component
+ * const theme = inject(ThemeService);
+ * theme.toggle();
+ * theme.setTheme('dark');
+ * const current = theme.theme(); // 'light' | 'dark'
+ * ```
+ */
+declare class ThemeService {
+    private readonly storage;
+    private readonly document;
+    /**
+     * Current theme. Prefer reading via `theme()` in templates / computed values
+     * rather than caching the string, so dark-class consumers stay in sync.
+     */
+    readonly theme: i0.WritableSignal<Theme>;
+    constructor();
+    /**
+     * Sets and persists the theme, updating the `dark` class and `color-scheme`
+     * on `<html>`.
+     *
+     * @param theme - Absolute preference to store.
+     */
+    setTheme(theme: Theme): void;
+    /**
+     * Flips between light and dark.
+     *
+     * @returns The theme after the toggle.
+     */
+    toggle(): Theme;
+    private resolveInitialTheme;
+    private prefersDark;
+    private applyToDocument;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ThemeService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ThemeService>;
+}
+
+export { MODE_COLOR_SAFELIST, ModeColorService, ThemeService };
+export type { ModeColorClasses, Theme };

package/.nx/cache/9040451482998546630/dist/libs/africanies-core/README.md

@@ -0,0 +1,85 @@
+# @africanies/africanies-core
+
+API and app-wiring layer for the AFRICANIES Web SDK: SDK config, HTTP client,
+shipping mode, mode-region metadata, TanStack Query default helpers, and
+route-driven overlay registration.
+
+## Install peers
+
+```bash
+# Published on npm (@africanies scope)
+npm install @africanies/africanies-core @africanies/africanies-models @africanies/africanies-storage
+```
+
+Peer dependencies: `@angular/common`, `@angular/core`, `@angular/router`,
+`rxjs`, `@africanies/africanies-models`, `@africanies/africanies-storage`.
+
+## Quick start
+
+```ts
+import { ApplicationConfig } from '@angular/core';
+import {
+  provideAfricaniesSdk,
+  provideAfricaniesHttpClient,
+  provideOverlayRoutes,
+  createAfricaniesQueryClientDefaults,
+} from '@africanies/africanies-core';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideAfricaniesSdk({ baseUrl: 'https://api.example.com', timeout: 30_000 }),
+    provideAfricaniesHttpClient(),
+    // optional extras:
+    // provideAfricaniesHttpClient({ interceptors: [correlationInterceptor] }),
+    // optional: provideOverlayRoutes([{ paramKey: 'modal', routes: { ... } }]),
+  ],
+};
+
+// TanStack Query (app dependency — pin exact experimental version):
+// new QueryClient({ defaultOptions: createAfricaniesQueryClientDefaults() })
+```
+
+## Modules
+
+| Area | Exports |
+|------|---------|
+| Config | `provideAfricaniesSdk`, `AFRICANIES_SDK_CONFIG`, `httpToasts` (`'off'` \| `'errors'` \| `'all'`) |
+| Auth | `AuthService` (`forgot`), `isValidEmail`, `AuthTokenService` (`set` / `clear` / `get`) |
+| Shipping | `ShippingModeService` (tab-scoped via `sessionStorage`), `shipmentModeInterceptor`, per-request `ApiRequestOptions.shippingMode` / `withShippingMode` |
+| HTTP | `provideAfricaniesHttpClient`, `ApiClient` (auto-tags `withToast` from config / `ApiRequestOptions.toast`; optional `shippingMode` per call; HTTP failures → `Error` with formatted `.message`), `withToast`, `withShippingMode`, `httpToastInterceptor`, `normalize` (lifts Laravel validation bags into `errors` + joined `message`), `formatApiErrorMessage` (used internally; rare for hosts), `fieldErrorsMap`, `authInterceptor` |
+| Query | `createAfricaniesQueryClientDefaults`, `provideAfricaniesQueryDefaults`, `listFetchKind` (body loader on first load / STN↔SFN; keep rows on focus / Refresh / pager) |
+| Mode | `ModeConfigService`, `provideModeConfig`, `MODE_CONFIG_PATH` |
+| Country | `CountryService`, `countryFlagUrl` / `mapCountrySelectOptions` (flagcdn.com), `COUNTRY_READ_PATH`, mappers |
+| Service | `ServiceService` (`readPage` / `readAll` / `readById`), `SERVICE_READ_PATH` (`/public/service/read`), mappers |
+| Document | `DocumentService` (`readPage` / `readAll` / `readById`), `DOCUMENT_READ_PATH` (`/public/document/read`) — preview via `file_ref` on by-id |
+| Plan | `PlanService` (`readPage` / `readAll` / `readById`), `PLAN_READ_PATH` (`/public/plan/read`), mappers |
+| Currency | `CurrencyService` (`readPage` / `readAll` / `readById`, `create` / `update` / `remove`), `CURRENCY_*_PATH`, mappers |
+| Payment method | `PaymentMethodService` (`readPage` / `readAll` / `readById`, `update`), `PAYMENT_METHOD_READ_PATH` / `PAYMENT_METHOD_UPDATE_PATH`, mappers |
+| Shipment method | `ShipmentMethodService` (`readPage` / `readAll` / `readById`), `SHIPMENT_METHOD_READ_PATH`, mappers |
+| Warehouse | `WarehouseService` (`readPage` / `readAll` / `readById`), `WAREHOUSE_READ_PATH`, mappers |
+| Zone | `ZoneService` (`readPage` / `readAll` / `readById`), `ZONE_READ_PATH`, mappers |
+| Product | `ProductService` (`readPage` / `readAll` / `readById`), `PRODUCT_READ_PATH`, mappers |
+| User | `UserService` (`me`, `changePassword`, `logoutFromAllSessions`), `USER_PATH`, `mapUser` (bare `/user` body; needs `AuthTokenService.set`) |
+| Notification | `NotificationService` (`readPage` / `readAll` / `readOne`), `NOTIFICATION_READ_PATH`, `mapNotification` / `mapNotificationInboxItem` |
+| File | `FileService` (`read` / `readMultiple` → `POST /file/read`), `FILE_READ_PATH`, `mapFileRead` / `mapFileReadList` |
+| Overlay | `provideOverlayRoutes`, `RouteOverlayService`, `MODAL_SERVICE`, `DRAWER_SERVICE` |
+| Filters | `FilterOptionsResolver` (`resolveField` lazy in drawer), `mergeFilterOptionLists`, warehouse/method mappers |
+| Browser | `copyToClipboard`, `downloadCsv` / `csvCell` (UTF-8 CSV download) |
+
+List-style GETs follow `ResourceId`: `null` (paginated), `'all'` (full dump), `number` (single).
+
+| Filter `optionsSource` | SDK resolver |
+|------------------------|--------------|
+| `warehouses` | Lazy `FilterOptionsResolver.resolveField` → `WarehouseService.readAll()` |
+| `shipmentMethods` | Lazy `FilterOptionsResolver.resolveField` → `ShipmentMethodService.readAll()` |
+| `shipmentManifests` | Host `optionLists` (no built-in service yet) |
+
+`MODAL_SERVICE` / `DRAWER_SERVICE` are tokens only — implementations ship in
+`@africanies/africanies-ui` to avoid circular dependencies.
+
+## Build / test
+
+```bash
+npx nx build africanies-core
+npx nx test africanies-core
+```