@mediansh/widget 0.5.0 → 0.7.0

package/README.md

@@ -5,6 +5,9 @@ support panel. An AI agent answers first, your team picks up in the Median
 inbox, and replies stream back to the visitor. There is no connection or
 message list to manage.
 
+The same panel as a modal, a contact form, and a feedback panel ship
+alongside it. Same key, same inbox.
+
 ## Install
 
 ```sh
@@ -66,6 +69,51 @@ medianSupport.reset(); // on sign out
 React components can use `useMedianSupport()` for the same control with a
 live `isOpen`.
 
+## Modal
+
+The widget, opened in the middle of the screen over a scrim rather than out
+of the corner. The button stays; every prop and every control is the same.
+
+```tsx
+import { MedianSupportModal } from "@mediansh/widget";
+
+<MedianSupportModal apiKey="median_pk_..." />;
+```
+
+`mountMedianSupportModal` is the version for pages without React. Mount one
+of the two, not both.
+
+## Contact form
+
+A form where you put it, for the page where a chat panel is the wrong shape.
+An email and a message are always asked; add the rest:
+
+```tsx
+import { MedianContactForm } from "@mediansh/widget";
+
+<MedianContactForm
+  apiKey="median_pk_..."
+  fields={[
+    { name: "name", label: "Name", required: true },
+    { name: "topic", type: "select", options: ["Billing", "A bug"] },
+  ]}
+/>;
+```
+
+Sending starts a conversation in your inbox, exactly as the widget does, and
+the reply goes to the email given. `mountMedianContactForm({ target, ... })`
+renders it into an element of yours on a page without React.
+
+Or keep your own form and only borrow the send:
+
+```tsx
+const contact = useMedianContact({ apiKey: "median_pk_..." });
+
+await contact.send({ email, message, fields: { Topic: topic } });
+```
+
+`sendMedianContact(options, message)` is the same call as a plain function.
+
 ## Feedback
 
 A second panel, for notes rather than questions. It wraps a trigger of your
@@ -88,11 +136,12 @@ and the page it was written on rides along.
 
 ## Theming
 
-Both panels read shadcn-style CSS variables from your page and fall back to
-a plain light theme without them. They inherit your font.
+Every piece reads shadcn-style CSS variables from your page and falls back
+to a plain light theme without them. They inherit your font.
 
 ## Docs
 
-Props, identity, diagnostics, feedback, and agent tools:
+Props, identity, diagnostics, the modal, the contact form, feedback, and
+agent tools:
 [docs.median.sh](https://docs.median.sh), or the source at
 [github.com/mediansh/median](https://github.com/mediansh/median).

package/dist/index.d.ts

@@ -177,16 +177,20 @@ type MedianSupportOptions = {
     /** Every open and close, whoever asked for it. */
     onOpenChange?: (open: boolean) => void;
     /**
-     * Take the visitor to a page, when one of your own tools asks for it.
+     * Take the visitor to a page, when one of your own tools offers one.
      *
      *   <MedianSupport apiKey="median_pk_..." onNavigate={router.push} />
      *
+     * A tool that answers with a destination puts a button under the reply
+     * that explains it, and this is what the button does. Nothing moves on its
+     * own: the visitor presses it, or they stay where they are.
+     *
      * Called with a path on your own site, already checked against this page's
      * origin. Your router decides what happens: pass `router.push` and the
      * conversation stays open across the move.
      *
-     * Without it a tool that asks to navigate cannot, and says so in the
-     * console while you are building. Nothing else needs it.
+     * Without it there is nowhere for a press to go, so no button is shown and
+     * the console says so while you are building. Nothing else needs it.
      */
     onNavigate?: (path: string) => void;
 };
@@ -256,19 +260,26 @@ type MedianSupportProps = MedianSupportOptions & ({
 declare function MedianSupport(props: MedianSupportProps): react.JSX.Element;
 
 /**
- * What a mounted widget hands back: the two things a host without React has
- * no re-render to do for them. Everything else goes through `medianSupport`,
- * same as anywhere.
+ * What a mounted component hands back: the two things a host without React
+ * has no re-render to do for them. Everything else goes through the
+ * component's own control, same as anywhere.
  */
-type MedianSupportInstance = {
+type MedianMountInstance<Options> = {
     /**
      * Change any option after mount. Only the keys passed change, so
      * `update({ user })` when somebody signs in leaves the rest alone.
      */
-    update: (options: Partial<MedianSupportProps>) => void;
-    /** Take the widget off the page: panel, launcher, connection, all of it. */
+    update: (options: Partial<Options>) => void;
+    /** Take it off the page: the component, its container, its connection. */
     unmount: () => void;
 };
+
+/**
+ * What a mounted widget hands back: the two things a host without React has
+ * no re-render to do for them. Everything else goes through `medianSupport`,
+ * same as anywhere.
+ */
+type MedianSupportInstance = MedianMountInstance<MedianSupportProps>;
 /**
  * The same widget, for a page that has never heard of React: Vue, Svelte,
  * Rails, a script on plain HTML. One call puts the launcher in the corner,
@@ -289,6 +300,43 @@ type MedianSupportInstance = {
  */
 declare function mountMedianSupport(options: MedianSupportProps): MedianSupportInstance;
 
+/**
+ * Every prop the widget takes, unchanged. The modal is the widget in a
+ * different place, not a different widget.
+ */
+type MedianSupportModalProps = MedianSupportProps;
+/**
+ * The support widget as a modal: the same button in the corner, and a panel
+ * that opens in the middle of the screen over a scrim rather than out of
+ * the corner.
+ *
+ *   <MedianSupportModal apiKey="median_pk_..." />
+ *
+ * Everything else is the widget's. Same props, same thread, same inbox on
+ * the other side, same `useMedianSupport()` to open it from your own nav,
+ * same sheet on a phone. Pick this for a site where a conversation deserves
+ * the room, or where a panel floating over the page would be in the way of
+ * the page.
+ *
+ * One or the other. Mounting both shares one open state, and the console
+ * says so.
+ */
+declare function MedianSupportModal(props: MedianSupportModalProps): react.JSX.Element;
+
+type MedianSupportModalInstance = MedianMountInstance<MedianSupportModalProps>;
+/**
+ * The modal, for a page that has never heard of React: Vue, Svelte, Rails,
+ * a script on plain HTML.
+ *
+ *   const support = mountMedianSupportModal({ apiKey: "median_pk_..." });
+ *
+ * It takes the component's props as one options object, and the rest of the
+ * SDK does not know the difference: `medianSupport.open()` opens this modal
+ * exactly as it opens the component. `update` and `unmount` are the same two
+ * `mountMedianSupport` hands back.
+ */
+declare function mountMedianSupportModal(options: MedianSupportModalProps): MedianSupportModalInstance;
+
 /**
  * Filing the crash the visitor is looking at.
  *
@@ -533,15 +581,7 @@ declare function MedianFeedback(props: MedianFeedbackProps): react.JSX.Element;
  * no re-render to do for them. Opening and closing go through
  * `medianFeedback`, same as anywhere.
  */
-type MedianFeedbackInstance = {
-    /**
-     * Change any option after mount. Only the keys passed change, so
-     * `update({ user })` when somebody signs in leaves the rest alone.
-     */
-    update: (options: Partial<MedianFeedbackProps>) => void;
-    /** Take the panel off the page. */
-    unmount: () => void;
-};
+type MedianFeedbackInstance = MedianMountInstance<MedianFeedbackProps>;
 /**
  * The same panel, for a page that has never heard of React: Vue, Svelte,
  * Rails, a script on plain HTML.
@@ -583,4 +623,299 @@ type MedianFeedbackControl = {
  */
 declare function useMedianFeedback(): MedianFeedbackControl;
 
-export { type MedianDiagnostics, type MedianErrorReportOptions, type MedianErrorReportOutcome, MedianFeedback, type MedianFeedbackControl, type MedianFeedbackInstance, type MedianFeedbackProps, MedianSupport, type MedianSupportControl, type MedianSupportInstance, type MedianSupportProps, type MedianUser, type MedianDiagnostics as PortalDiagnostics, type MedianErrorReportOptions as PortalErrorReportOptions, type MedianErrorReportOutcome as PortalErrorReportOutcome, MedianFeedback as PortalFeedback, type MedianFeedbackControl as PortalFeedbackControl, type MedianFeedbackInstance as PortalFeedbackInstance, type MedianFeedbackProps as PortalFeedbackProps, MedianSupport as PortalSupport, type MedianSupportControl as PortalSupportControl, type MedianSupportInstance as PortalSupportInstance, type MedianSupportProps as PortalSupportProps, type MedianUser as PortalUser, type SupportLauncherKind, medianFeedback, medianSupport, mountMedianFeedback, mountMedianSupport, mountMedianFeedback as mountPortalFeedback, mountMedianSupport as mountPortalSupport, medianFeedback as portalFeedback, medianSupport as portalSupport, reportError, useCanReportError, useMedianFeedback, useMedianSupport, useMedianFeedback as usePortalFeedback, useMedianSupport as usePortalSupport };
+/**
+ * What a host can put on the contact form, and what the form always has.
+ *
+ * Two fields are on every form whatever the host says: an email, because a
+ * message nobody can reply to is a message nobody sent, and the message
+ * itself. Everything else is the host's to add: a name, a topic, an order
+ * number, whatever their team wants to know before they read.
+ */
+/** A line, a paragraph, or one of a list. */
+type MedianContactFieldKind = "text" | "textarea" | "select";
+/**
+ * One field a host adds to the form.
+ *
+ *   { name: "topic", label: "Topic", type: "select", options: ["Billing", "A bug"] }
+ *
+ * Three names are reserved. `email` and `message` are the two the form always
+ * has, and naming either here only changes its label and placeholder. `name`
+ * lands on the customer record beside the email rather than in the message,
+ * so the team sees who wrote rather than a line saying so.
+ */
+type MedianContactField = {
+    /** Its key. Rides the message as the label on its line. */
+    name: string;
+    /** Shown above the box. Made from `name` when left out. */
+    label?: string;
+    /** `text` by default. Ignored on `email` and `message`, which know their shape. */
+    type?: MedianContactFieldKind;
+    /** What a `select` offers. A select with none falls back to a text box. */
+    options?: string[];
+    placeholder?: string;
+    /** Off by default. `email` and `message` are required whatever this says. */
+    required?: boolean;
+};
+
+type MedianContactFormOptions = {
+    /**
+     * What the form asks, beyond an email and a message, which it always asks:
+     *
+     *   <MedianContactForm
+     *     apiKey="median_pk_..."
+     *     fields={[
+     *       { name: "name", label: "Name", required: true },
+     *       { name: "topic", type: "select", options: ["Billing", "A bug", "Something else"] },
+     *     ]}
+     *   />
+     *
+     * Shown in this order. Email goes first, or right after a `name` field,
+     * and the message goes last, unless either is placed here by name. A
+     * `name` field lands on the customer record; every other answer goes
+     * above the message as a line of its own.
+     */
+    fields?: MedianContactField[];
+    /**
+     * Who is signed in on your site, if anyone. Their email and name fill the
+     * boxes in, and the rest is shown to your team.
+     */
+    user?: MedianUser;
+    /**
+     * Whether the message carries what the browser already knows: time zone,
+     * language, browser, OS, device, screen, and the page it was sent from.
+     * On by default. Pass `false` and none of it is read at all.
+     */
+    telemetry?: boolean;
+    /**
+     * Watch what goes wrong on the page, so a bug report filed from the
+     * message arrives with the error already attached. The same switch
+     * `<MedianSupport>` takes, and the same buffer behind it.
+     */
+    diagnostics?: MedianDiagnostics;
+    /**
+     * Anything about your own app worth having next to a bug report: a build,
+     * a route, a flag. Read when the form is sent.
+     */
+    appState?: Record<string, string | number | boolean>;
+    /** The heading, for a page that calls this something else. */
+    title?: string;
+    /** The line under it. */
+    description?: string;
+    /**
+     * The message landed. For whatever your page does next: a thank-you of its
+     * own, a redirect, an event. The form has already said thank you itself.
+     */
+    onSent?: () => void;
+};
+/**
+ * Two ways in, the same two `<MedianSupport>` takes.
+ *
+ * `apiKey` is the publishable id on its own. `identity` is the path to a
+ * route built with `medianIdentity`, which answers with the key and with
+ * whoever is signed in, already signed. Pass both and the form is up on the
+ * key from the prop while the route is still answering.
+ */
+type MedianContactFormProps = MedianContactFormOptions & ({
+    apiKey: string;
+    identity?: string;
+} | {
+    apiKey?: string;
+    identity: string;
+});
+/**
+ * A contact form, for the page where a chat panel is the wrong shape.
+ *
+ *   <MedianContactForm apiKey="median_pk_..." />
+ *
+ * An email and a message, on a card the shape of the support panel, with
+ * whatever else your team wants asked first. What is sent starts a
+ * conversation in your inbox exactly as the widget would: the agent answers
+ * first, your team picks it up, and the reply goes to the email given.
+ *
+ * Built on `useMedianContact`, which is also what a form of your own uses.
+ * It needs no connection of its own, and it is independent of
+ * `<MedianSupport>`: mount either, both, or neither. Mounted together they
+ * share a visitor, so somebody who writes here and later opens the widget
+ * finds the same thread.
+ */
+declare function MedianContactForm(props: MedianContactFormProps): react.JSX.Element;
+
+/**
+ * The component's props, plus where on the page the form goes.
+ *
+ * Spelled out rather than `Omit`ped off the props, because omitting a key
+ * from a union of two shapes flattens it into one and loses the "either,
+ * but not neither" the union is there to say.
+ */
+type MedianContactFormMountOptions = MedianContactFormProps & {
+    /**
+     * The element the form is rendered into, or a selector for it:
+     *
+     *   mountMedianContactForm({ target: "#contact", apiKey: "median_pk_..." });
+     *
+     * Unlike the widget, a form has no corner to go to, so this is required.
+     */
+    target: string | Element;
+};
+type MedianContactFormInstance = MedianMountInstance<MedianContactFormProps>;
+/**
+ * The same form, for a page that has never heard of React: Vue, Svelte,
+ * Rails, a script on plain HTML.
+ *
+ *   const form = mountMedianContactForm({
+ *     target: "#contact",
+ *     apiKey: "median_pk_...",
+ *     fields: [{ name: "name", label: "Name" }],
+ *   });
+ *
+ * It takes the component's props as one options object, plus `target`, and
+ * renders into a container of its own inside that element with the
+ * package's copy of React. Whatever else the element holds is left alone.
+ */
+declare function mountMedianContactForm({ target, ...options }: MedianContactFormMountOptions): MedianContactFormInstance;
+
+/**
+ * What a contact form hands over, ours or a host's own.
+ *
+ * The shape is deliberately small: the two things a message needs to be
+ * answered, who wrote it if they said, and whatever else the form asked as
+ * label to answer. Building one from a `<form>` of your own is a few lines.
+ */
+type MedianContactMessage = {
+    /** Where the reply goes. */
+    email: string;
+    /** What they wrote. */
+    message: string;
+    /** Lands on the customer record beside the email. */
+    name?: string;
+    /**
+     * Everything else the form asked, as label to answer. Each goes above the
+     * message as a line of its own, so the team reads the form the way it was
+     * filled in:
+     *
+     *   { Topic: "Billing", "Order number": "4821" }
+     *
+     * Empty answers are left off.
+     */
+    fields?: Record<string, string>;
+};
+
+/**
+ * Sending a contact message, for a form of the host's own.
+ *
+ * The same door the widget's composer uses, on the same session token, so
+ * what a host's form sends starts the thread the corner would have started:
+ * the team answers it from the inbox, the agent goes first, and with no
+ * panel open to watch, the reply goes to the email given. Somebody who
+ * writes here and later opens the widget finds their own conversation.
+ *
+ * A stateless HTTP client rather than the subscribing one, because nothing
+ * is read back: a form is a thing you hand over, not a thread you watch.
+ */
+/** What a send is told about who is sending and from where. */
+type MedianContactOptions = {
+    /** The browser-safe median_pk_ id. */
+    apiKey: string;
+    /**
+     * Who is signed in on your site, if anyone. What the form says about the
+     * email and the name wins over this; the rest is shown to your team.
+     */
+    user?: MedianUser;
+    /**
+     * Whether the message carries what the browser already knows: time zone,
+     * language, browser, OS, device, screen, and the page it was sent from.
+     * On by default. Pass `false` and none of it is read at all.
+     */
+    telemetry?: boolean;
+};
+/**
+ * Send a contact message from a form of your own, on any page in the
+ * browser:
+ *
+ *   await sendMedianContact(
+ *     { apiKey: "median_pk_..." },
+ *     { email, message, name, fields: { Topic: topic } },
+ *   );
+ *
+ * It resolves once the message is in your inbox and rejects with an `Error`
+ * whose `message` is worth showing above your button. Nothing about the
+ * form is ours: any `<form>`, any framework, any styling.
+ *
+ * In React, `useMedianContact()` is the same call with `isSending` and
+ * `error` kept for you, and an identity route resolved.
+ */
+declare function sendMedianContact(options: MedianContactOptions, message: MedianContactMessage): Promise<void>;
+
+type MedianContactHookOptions = {
+    /** Who is signed in on your site, if anyone. */
+    user?: MedianUser;
+    /** Browser context on the message. On by default. */
+    telemetry?: boolean;
+    /**
+     * Watch what goes wrong on the page, so a bug report filed from the
+     * message arrives with the error already attached. The same switch
+     * `<MedianSupport>` takes, and the same buffer behind it.
+     */
+    diagnostics?: MedianDiagnostics;
+    /** Anything about your own app worth having next to a bug report. */
+    appState?: Record<string, string | number | boolean>;
+};
+/**
+ * Two ways in, the same two every component takes: the publishable key, or
+ * the path of a route built with `medianIdentity`, which answers with the
+ * key and whoever is signed in.
+ */
+type UseMedianContactOptions = MedianContactHookOptions & ({
+    apiKey: string;
+    identity?: string;
+} | {
+    apiKey?: string;
+    identity: string;
+});
+/** What the hook hands back: one call, and the state around it. */
+type MedianContactControl = {
+    /**
+     * Send what the form holds. Resolves once the message is in the inbox.
+     * Rejects with an `Error` whose `message` is worth showing, and `error`
+     * holds the same words until the next send.
+     */
+    send: (message: MedianContactMessage) => Promise<void>;
+    /** A send is in flight. Hold the button. */
+    isSending: boolean;
+    /** Why the last send failed, or null. Cleared by the next send. */
+    error: string | null;
+    /**
+     * Whether a send has somewhere to go. False on the server, and for the
+     * beat before an identity route has answered with the key.
+     */
+    isReady: boolean;
+    /**
+     * Who is typing, as far as the page knows: what you passed, what the
+     * identity route said, and the email the widget's own question was
+     * answered with on this browser. For filling the boxes in.
+     */
+    user: MedianUser | undefined;
+};
+/**
+ * A contact form of your own, on Median's inbox:
+ *
+ *   const contact = useMedianContact({ apiKey: "median_pk_..." });
+ *
+ *   <form
+ *     onSubmit={async (event) => {
+ *       event.preventDefault();
+ *       await contact.send({ email, message });
+ *     }}
+ *   >
+ *     ...
+ *     {contact.error && <p>{contact.error}</p>}
+ *     <button disabled={contact.isSending}>Send</button>
+ *   </form>
+ *
+ * Everything about the form is yours. What is sent starts a conversation in
+ * your inbox exactly as `<MedianContactForm>` and the widget do, and the
+ * reply goes to the email given. No provider, no connection to manage.
+ */
+declare function useMedianContact(options: UseMedianContactOptions): MedianContactControl;
+
+export { type MedianContactControl, type MedianContactField, type MedianContactFieldKind, MedianContactForm, type MedianContactFormInstance, type MedianContactFormMountOptions, type MedianContactFormProps, type MedianContactMessage, type MedianContactOptions, type MedianDiagnostics, type MedianErrorReportOptions, type MedianErrorReportOutcome, MedianFeedback, type MedianFeedbackControl, type MedianFeedbackInstance, type MedianFeedbackProps, MedianSupport, type MedianSupportControl, type MedianSupportInstance, MedianSupportModal, type MedianSupportModalInstance, type MedianSupportModalProps, type MedianSupportProps, type MedianUser, type MedianDiagnostics as PortalDiagnostics, type MedianErrorReportOptions as PortalErrorReportOptions, type MedianErrorReportOutcome as PortalErrorReportOutcome, MedianFeedback as PortalFeedback, type MedianFeedbackControl as PortalFeedbackControl, type MedianFeedbackInstance as PortalFeedbackInstance, type MedianFeedbackProps as PortalFeedbackProps, MedianSupport as PortalSupport, type MedianSupportControl as PortalSupportControl, type MedianSupportInstance as PortalSupportInstance, type MedianSupportProps as PortalSupportProps, type MedianUser as PortalUser, type SupportLauncherKind, type UseMedianContactOptions, medianFeedback, medianSupport, mountMedianContactForm, mountMedianFeedback, mountMedianSupport, mountMedianSupportModal, mountMedianFeedback as mountPortalFeedback, mountMedianSupport as mountPortalSupport, medianFeedback as portalFeedback, medianSupport as portalSupport, reportError, sendMedianContact, useCanReportError, useMedianContact, useMedianFeedback, useMedianSupport, useMedianFeedback as usePortalFeedback, useMedianSupport as usePortalSupport };