@eintrek/erp-shell 0.1.59 → 0.1.61

package/dist/navigation/app-layout-shell.d.ts

@@ -1,6 +1,7 @@
 import * as React from "react";
 import { type ShellChrome, type WorkspaceHeaderTone } from "./chrome";
 import { type HelpAppId } from "../help/help-store";
+import { type OrganizationsStatus } from "./url-org-gate";
 /**
  * Shape the shell needs from an organization to wire the URL `[code]` segment
  * back to the active org id. Hosts already keep richer types around — this is
@@ -40,6 +41,20 @@ export interface AppLayoutShellProps {
     setOrganizationId: (id: string | number | null) => Promise<void> | void;
     /** Orgs the user belongs to — used to resolve URL `[code]` → org `id`. */
     organizations: AppLayoutShellOrganization[];
+    /**
+     * `status` of the query behind `organizations`. With it the page waits for
+     * the list before it mounts, and a code that is not among the user's
+     * organisations is refused. Without it the gate starts only once the list
+     * is non-empty, so requests made while it loads carry the previous
+     * organisation. Every host should pass it.
+     */
+    organizationsStatus?: OrganizationsStatus;
+    /**
+     * Shown in the content area when the URL's code is not one of the user's
+     * organisations. Defaults to AccessDenied with a way to pick an
+     * organisation.
+     */
+    notMemberComponent?: React.ReactNode;
     /** Absolute path to redirect to when the session has no accessToken (e.g.
      *  token refresh failed). The shell appends `?error=NoAccessToken&callbackUrl=…`. */
     signInUrl: string;
@@ -84,4 +99,4 @@ export interface AppLayoutShellProps {
  * an erp-shell bump — domain components must NOT add their own root padding
  * or content gets indented twice.
  */
-export declare function AppLayoutShell({ children, sidebar, loadingComponent, breadcrumb, permissionProvider, organizationId, setOrganizationId, organizations, signInUrl, selectOrganizationUrl, chrome, workspaceHeader, headerEnd, mobileBrand, showHelp, helpApp, }: AppLayoutShellProps): import("react/jsx-runtime").JSX.Element;
+export declare function AppLayoutShell({ children, sidebar, loadingComponent, breadcrumb, permissionProvider, organizationId, setOrganizationId, organizations, organizationsStatus, notMemberComponent, signInUrl, selectOrganizationUrl, chrome, workspaceHeader, headerEnd, mobileBrand, showHelp, helpApp, }: AppLayoutShellProps): import("react/jsx-runtime").JSX.Element;

package/dist/navigation/nav-row.d.ts

@@ -0,0 +1,24 @@
+import type { Module } from "./navigation-types";
+/**
+ * How a sidebar row looks, apart from its layout.
+ *
+ * Exactly one row is lit — the page's own (resolveSidebarNav). Until 0.1.60 a
+ * row under the pointer took the lit row's fill and colour, and an open group
+ * (or a one-line row once clicked, which was a collapsible too) took its
+ * colour, so the menu showed several "current pages" at once.
+ */
+/** A row under the pointer: a faint neutral tint, never the lit row's look. */
+export declare const NAV_ROW_HOVER = "hover:bg-sidebar-foreground/5 hover:text-sidebar-foreground";
+/** The lit row: the accent fill and text. The pointer changes nothing. */
+export declare const NAV_ROW_LIT = "bg-sidebar-accent text-sidebar-accent-foreground hover:bg-sidebar-accent hover:text-sidebar-accent-foreground";
+/** Fill and colour for a row, lit or not. */
+export declare function navRowTone(lit: boolean): string;
+/**
+ * A group opens and shuts; any other row is a plain link with no open state.
+ */
+export declare function isNavGroup(item: Pick<Module, "subModules">): boolean;
+/**
+ * The open groups after `id` is opened or shut. An id that is not a group's
+ * is ignored — a one-line row has nothing to open.
+ */
+export declare function setNavGroupOpen(openIds: ReadonlySet<string>, items: ReadonlyArray<Pick<Module, "id" | "subModules">>, id: string, isOpen: boolean): ReadonlySet<string>;

package/dist/navigation/sidebar-components.d.ts

@@ -16,6 +16,11 @@ export declare const SidebarMenuItem: React.ForwardRefExoticComponent<Omit<React
 export declare const SidebarMenuButton: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLButtonElement> & React.ButtonHTMLAttributes<HTMLButtonElement> & {
     asChild?: boolean;
     isActive?: boolean;
+    /**
+     * The row's name beside it, for a row that shows only its icon — the
+     * theme's tooltip on the right, never a native `title` (which the
+     * browser drops wherever it likes, over the logo included).
+     */
     tooltip?: string;
     size?: "sm" | "default" | "lg";
 }, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/navigation/url-org-gate.d.ts

@@ -0,0 +1,78 @@
+/**
+ * What AppLayoutShell does with the page while the organisation in the URL and
+ * the tab's active organisation are being reconciled. Pure, so it is tested
+ * without React (url-org-gate.test.ts).
+ *
+ * The URL's `[code]` is authoritative. The page — and with it every request
+ * the page makes — mounts only once the active organisation IS the one the
+ * URL names:
+ *
+ *   ready       the active organisation is the URL's: render the page.
+ *   resolving   the caller's organisations are still loading, so the code
+ *               cannot be resolved yet: hold the page.
+ *   switching   the code is one of the caller's organisations but not the
+ *               active one: switch to it (`targetId`), hold the page meanwhile.
+ *   not-member  the list loaded and the code is not in it: refuse.
+ *   unverified  the list could not be loaded: render as before the gate
+ *               existed (the API still scopes every request), rather than
+ *               leave the page on a loader for good.
+ */
+export interface UrlOrgGateOrganization {
+    id: string | number;
+    code?: string | null;
+}
+/** react-query's `status` of the host's organisations query. */
+export type OrganizationsStatus = "pending" | "success" | "error";
+export type UrlOrgGate = {
+    state: "ready";
+    targetId: string | null;
+} | {
+    state: "resolving";
+} | {
+    state: "switching";
+    targetId: string;
+} | {
+    state: "not-member";
+} | {
+    state: "unverified";
+};
+export interface UrlOrgGateInput {
+    /** The URL's `[code]` segment. */
+    code: string | undefined;
+    /** The caller's organisations. */
+    organizations: readonly UrlOrgGateOrganization[];
+    /**
+     * Status of the query that produced `organizations`. A host that does not
+     * pass it gets the gate only once the list is non-empty: an empty list then
+     * cannot be told apart from "still loading" or "failed", and holding the
+     * page on that would strand a host that never loads one.
+     */
+    organizationsStatus?: OrganizationsStatus;
+    /** The active organisation (the host's ERP context). */
+    organizationId: string | number | null | undefined;
+}
+/** The organisation a `[code]` segment names, among the caller's. */
+export declare function findOrganizationForCode<T extends UrlOrgGateOrganization>(code: string | undefined, organizations: readonly T[]): T | null;
+export declare function resolveUrlOrgGate({ code, organizations, organizationsStatus, organizationId, }: UrlOrgGateInput): UrlOrgGate;
+/**
+ * What to do when the active organisation is not one of the user's — a
+ * browser that remembers an organisation that was deleted, or that the user
+ * has left. Pure, tested in url-org-gate.test.ts.
+ *
+ *   none     nothing to recover: the list has not loaded, there is no active
+ *            organisation, or the active one is the user's.
+ *   use      make `targetId` active: the URL's organisation when the user is
+ *            a member of it, otherwise the user's only organisation.
+ *   forget   clear it; the user has several organisations and the URL names
+ *            none of them, so they pick one.
+ */
+export type StaleOrganizationRecovery = {
+    action: "none";
+} | {
+    action: "use";
+    targetId: string;
+    fromUrl: boolean;
+} | {
+    action: "forget";
+};
+export declare function resolveStaleOrganization({ code, organizations, organizationsStatus, organizationId, }: UrlOrgGateInput): StaleOrganizationRecovery;

package/dist/organization/active-organization.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The organisation this browser tab is working in.
+ *
+ * Every request carries an X-Organization-ID header, and every cached query
+ * belongs to one organisation. Both used to come from the `erp.organizationId`
+ * cookie (then localStorage), which is the organisation the BROWSER last had
+ * active — shared by every tab and, on antniti.com, by every app. A tab
+ * showing /O26000021/… therefore sent whatever another tab, or another app,
+ * had picked last, and the URL lost.
+ *
+ * The tab's own value is set by `useOrganizationIdState` — the state that
+ * AppLayoutShell drives to the organisation the URL names — and read first by
+ * `getRequestOrganizationId()`. Until a tab has one (a cold load before the
+ * provider mounts), localStorage and then the cookie answer as before.
+ *
+ * Module state, so browser-only: on the server one module instance serves
+ * every request, and a value written there would leak between users.
+ */
+/** The organisation this tab is working in, or null before it has one. */
+export declare function getTabOrganizationId(): string | null;
+/** Record the organisation this tab is working in (browser only). */
+export declare function setTabOrganizationId(id: string | number | null | undefined): void;
+/**
+ * Record the user's organisations (browser only). From then on a stored or
+ * tab organisation that is not among them loses to one that is: a browser
+ * that still remembers a deleted organisation — or one the user has left —
+ * must not keep sending it while the cookie names a good one.
+ */
+export declare function setKnownOrganizationIds(ids: Iterable<string | number> | null): void;
+/** Whether the loaded list says the user is NOT a member of `id`. */
+export declare function isKnownStaleOrganizationId(id: string | number | null | undefined): boolean;
+/**
+ * Marks a request that must not carry X-Organization-ID: the user's own list
+ * of organisations is how a stale organisation id is found out, so it cannot
+ * depend on one. An app's interceptor honours it by passing the request's
+ * config to getRequestOrganizationId(config).
+ *
+ *   axiosInstance.get("/organizations", withoutOrganization({ params }))
+ */
+export declare const WITHOUT_ORGANIZATION_FLAG = "erpWithoutOrganization";
+export declare function withoutOrganization<T extends object = Record<never, never>>(config?: T): T & {
+    erpWithoutOrganization: true;
+};
+/**
+ * Marks a request for one particular organisation, whatever this tab has
+ * active. Used to retry the organisation list under each stored id when an
+ * API refuses it without one (see http/organization-fallback.ts).
+ */
+export declare const FOR_ORGANIZATION_FIELD = "erpOrganizationId";
+/**
+ * Every organisation id this browser has stored for the tab — the tab's
+ * own, localStorage, the cookie — distinct, in that order.
+ */
+export declare function getStoredOrganizationIds(): string[];
+/**
+ * The organisation a request from this tab belongs to: the tab's own, then
+ * localStorage, then the cookie. Use it for the X-Organization-ID header —
+ * and read it before any `await` in the interceptor, so the header names the
+ * organisation that was active when the request was made.
+ *
+ * Pass the request's config: a request marked withoutOrganization() gets
+ * null, so no header.
+ *
+ * localStorage before the cookie: setOrganizationId writes localStorage
+ * synchronously and then awaits a server action for the cookie, so during
+ * that round trip the cookie still names the previous organisation.
+ *
+ * Once the user's organisations are known (setKnownOrganizationIds), the
+ * first of those that is one of them wins: 0.1.60 let a deleted
+ * organisation's id left in localStorage beat a valid cookie, and every
+ * request — the organisation list included — was refused. If none is a
+ * member the first is still sent, as before: the list may simply be behind
+ * (an organisation created a moment ago).
+ */
+export declare function getRequestOrganizationId(config?: unknown): string | null;
+/**
+ * Forget the active organisation everywhere this browser keeps it: the tab,
+ * localStorage and the `erp.organizationId` cookie. Call on sign-out, so the
+ * next person to sign in on this browser does not start in the previous
+ * person's organisation.
+ */
+export declare function clearStoredOrganization(): void;

package/dist/providers/query-scope.d.ts

@@ -0,0 +1,25 @@
+import { type QueryKey } from "@tanstack/react-query";
+/**
+ * Every query is cached per organisation.
+ *
+ * Requests are scoped by the X-Organization-ID header, so almost no query key
+ * names the organisation — ["purchase-requests", "detail", id] is the same key
+ * in every company. A key that is the same in two organisations is one cache
+ * entry: what was fetched in one was a fresh cache hit in the other, and a
+ * page opened under another organisation's URL rendered the first one's
+ * document until something refetched it.
+ *
+ * The hash — the identity of a cache entry — therefore carries the
+ * organisation requests are sent with right now (getQueryClientConfig passes
+ * getRequestOrganizationId()). The key itself is untouched,
+ * so partial-key invalidation and every existing key keep working; a switch
+ * simply lands on a different set of entries.
+ */
+export declare function organizationScopedQueryHash(queryKey: QueryKey, organizationId: string | null): string;
+/**
+ * Retry a failed query at most twice — unless the API answered with a 4xx.
+ * A 404 for a document that is not in this organisation will not appear on a
+ * second ask; retrying held the page on its skeleton for three seconds before
+ * it could say "not found". 408 and 429 are transient and still retried.
+ */
+export declare function shouldRetryQuery(failureCount: number, error: unknown): boolean;

package/dist/providers/react-query-config.d.ts

@@ -1,7 +1,9 @@
 import { QueryClientConfig } from "@tanstack/react-query";
 /**
  * Default React Query config used across ERP apps:
- *   - 2 retries on queries / 1 on mutations, exponential backoff
+ *   - cache entries scoped by organisation (organizationScopedQueryHash)
+ *   - 2 retries on queries except 4xx answers / none on mutations,
+ *     exponential backoff
  *   - 5 min staleTime, refetchOnWindowFocus
  *   - swallows "no org context" errors to silence noise on the
  *     select-organization page

package/dist/version.d.ts

@@ -2,4 +2,4 @@
  * This package's version, attached to help messages so the back office can
  * tell which shell a report came from. Keep in step with package.json.
  */
-export declare const SHELL_VERSION = "0.1.59";
+export declare const SHELL_VERSION = "0.1.61";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eintrek/erp-shell",
-  "version": "0.1.59",
+  "version": "0.1.61",
   "private": false,
   "type": "module",
   "description": "Shared frontend platform for ERP apps — HTTP client, providers, navigation, hooks.",