@saas-pro-lib/support

Headless React components and hooks that wrap the @core-ai-inc/saas-pro-lib/sdk/support/go HTTP API. Drop this in alongside @saas-pro-lib/auth to get a Help center, ticket form, AI feedback widget, page-aware article suggestions, AI-driven UI spotlight, screenshot capture pipeline, and a SupportActions registry that the AI Orchestrator can invoke.

Headless — no MUI / Tailwind / styled-components bundled. Every component takes className, classNames, and (where useful) a renderItem / renderRatingButton slot so you style with whatever your product already uses.

Full design: docs/design/support.md in the saas-pro-lib repo.

Install

npm install @saas-pro-lib/support
# alongside (recommended) @saas-pro-lib/auth for shared identity

Quickstart

import { AuthProvider, useAuth } from "@saas-pro-lib/auth";
import { SupportProvider } from "@saas-pro-lib/support";
// Optional positioning CSS for the spotlight overlay:
import "@saas-pro-lib/support/dist/styles/spotlight.css";

function App({ children }) {
  return (
    <AuthProvider
      baseURL="https://auth.example.com"
      clientId="app_xxx"
    >
      <SupportShell>{children}</SupportShell>
    </AuthProvider>
  );
}

function SupportShell({ children }) {
  const { client, user, currentOrgId } = useAuth();
  return (
    <SupportProvider
      apiBaseURL="https://api.example.com"
      client={client} // saas-pro-lib client = authed fetch + auto-refresh
      teamId={currentOrgId ?? undefined}
      userId={user?.id}
      locale="ja"
    >
      {children}
    </SupportProvider>
  );
}

Components

| Component | Purpose | | --------------------- | -------------------------------------------------- | | <HelpCenter> | Tabbed catalog of help articles + search. | | <HelpArticleList> | Standalone listing. | | <HelpArticleViewer> | Render a single article by slug. | | <HelpSearchBox> | Debounced search input. | | <TicketForm> | Subject + description + priority form. | | <TicketList> | Caller's own tickets (or staff-supplied user). | | <TicketStatusBadge> | Localizable status pill. | | <FeedbackWidget> | 👍 / 👎 + comment for an AI reply. | | <SuggestionsPanel> | Auto-suggested articles for current path. | | <SupportAnchor> | Annotates a UI element with data-support-action. | | <SupportSpotlight> | Overlay that highlights an anchored element. |

Hooks

useArticles({ category, locale, page, limit, publicOnly });
useArticle(slug, locale);
useArticleSearch();
useTickets({ status, conversationId, page, limit });
useFeedback(); // .submit({ rating, comment, ... })
useSuggestions({ path, locale, limit });
useSpotlight(); // .emit / .dismiss / .current
useScreenshotCapture({ capture: html2canvasFn });
useSupportActions(); // .register / .unregister / .execute / .actions

SupportActions registry

import { registerAction, executeAction } from "@saas-pro-lib/support";

registerAction({
  name: "open-board-template-drawer",
  label: "ボードを作成する",
  scope: "/crm/boards/*",
  execute: () => {
    document
      .querySelector<HTMLButtonElement>('[data-test="template-btn"]')
      ?.click();
  },
});

// Later, when the AI orchestrator decides to invoke this action:
await executeAction("open-board-template-drawer", { message: "右上のボタン" });

i18n

All component labels default to Japanese. Override per-component via labels:

<TicketForm
  labels={{ subject: "Subject", description: "Description", submit: "Submit" }}
/>

Article bodies are stored per locale in sup_articles; pass locale="en" to fetch the English variant.

Tests

npm test           # vitest + jsdom
npm run typecheck

Unit tests cover the REST client, actions registry, spotlight event flow, the SupportProvider context, and headless component primitives (<SupportAnchor>, <TicketStatusBadge>).