@tinvar/react 0.4.12 → 0.4.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinvar/react",
-  "version": "0.4.12",
+  "version": "0.4.14",
   "license": "MIT",
   "files": [
     "src"
@@ -158,6 +158,10 @@
       "types": "./src/when-mounted.d.ts",
       "default": "./src/when-mounted.js"
     },
+    "./impersonation-banner": {
+      "types": "./src/impersonation-banner.d.ts",
+      "default": "./src/impersonation-banner.js"
+    },
     "./testing": {
       "types": "./src/testing.d.ts",
       "default": "./src/testing.js"

package/src/client.d.ts

@@ -34,3 +34,4 @@ export * from './use-form';
 export * from './use-http';
 export * from './optimistic';
 export * from './when-mounted';
+export * from './impersonation-banner';

package/src/client.js

@@ -40,3 +40,4 @@ export { inlinePayloadStream, payloadRowBytes } from './payload.js';
 export { action, actionName, actionUrl, isActionReference, ActionError, ACTION_PREFIX } from './action.js';
 export * from './forms.js';
 export { WhenMounted } from './when-mounted.js';
+export { ImpersonationBanner } from './impersonation-banner.js';

package/src/impersonation-banner.d.ts

@@ -0,0 +1,29 @@
+import type { ReactNode } from 'react';
+import type { ActionTarget } from './action';
+
+/** What Impersonations::banner() hands a page (ImpersonationBannerData), as it arrives. */
+export interface ImpersonationBannerData {
+  /** The user being acted as: their name, or their address without one. */
+  actingAs: string;
+  /** Who is acting as them, the same way. */
+  impersonator: string;
+  /** Why, as the impersonator gave it. */
+  reason?: string;
+  /** When it ends by itself. */
+  until?: string;
+}
+
+export interface ImpersonationBannerProps {
+  /** The page's impersonation, from shared data; null or undefined draws nothing. */
+  impersonation: ImpersonationBannerData | null | undefined;
+  /** The app's action that calls Impersonations::stop() and answers `{ next }`. */
+  stop: ActionTarget;
+  className?: string;
+  stopLabel?: string;
+}
+
+/**
+ * "You are acting as Ada -- stop" (ADR 0194): a status line and a button
+ * that posts the stop action, then loads the page it names.
+ */
+export declare function ImpersonationBanner(props: ImpersonationBannerProps): ReactNode;

package/src/impersonation-banner.js

@@ -0,0 +1,62 @@
+'use client';
+
+// <ImpersonationBanner>: what a page shows while staff act as its user
+// (ADR 0194).
+//
+// The server hands every page the impersonation, as shared data an app
+// makes from Impersonations::banner() -- whom the session acts as, who is
+// acting, why and until when -- or null for every other session. This draws
+// it: a status line naming both, and a button that posts the app's stop
+// action and follows where it says to go, by a document load: the session
+// the browser comes back to is another person's, and nothing the router
+// holds for this one is theirs. Unstyled, as everything in the package is;
+// the app styles it through className, or draws its own from the same data.
+
+import { createElement, useState } from 'react';
+import { action } from './action.js';
+import { clearHistory } from './router.js';
+
+/**
+ * @param {{
+ *   impersonation: { actingAs: string, impersonator: string, reason?: string, until?: string } | null | undefined,
+ *   stop: string | { readonly action: string },
+ *   className?: string,
+ *   stopLabel?: string,
+ * }} props
+ */
+export function ImpersonationBanner({ impersonation, stop, className, stopLabel = 'Stop impersonating' }) {
+  const [busy, setBusy] = useState(false);
+  const [failed, setFailed] = useState(false);
+  if (impersonation === null || impersonation === undefined) {
+    return null;
+  }
+
+  const leave = async () => {
+    setBusy(true);
+    setFailed(false);
+    try {
+      const result = await action(stop)({});
+      const next = /** @type {{ next?: unknown } | null} */ (result.value)?.next;
+      clearHistory();
+      window.location.assign(typeof next === 'string' ? next : '/');
+    } catch {
+      setBusy(false);
+      setFailed(true);
+    }
+  };
+
+  const by = impersonation.impersonator === '' ? '' : ` (you are ${impersonation.impersonator})`;
+
+  return createElement(
+    'div',
+    { role: 'status', className, 'data-impersonation': '' },
+    createElement('span', null, `You are acting as ${impersonation.actingAs}${by}.`),
+    ' ',
+    createElement(
+      'button',
+      { type: 'button', disabled: busy, onClick: () => void leave() },
+      busy ? 'Stopping…' : stopLabel,
+    ),
+    failed ? createElement('span', { role: 'alert' }, ' Not stopped. Try again.') : null,
+  );
+}