@saas-pro-lib/ui

Headless React UI primitives shared across saas-pro-lib SaaS products (saiyou-pro / shukyaku-pro / beauty-pro / saas-pro-lib-ui).

The package is split into two public subpaths:

| Import path | Scope | | --------------------------- | ----- | | @saas-pro-lib/ui/common | Product-agnostic primitives such as buttons, forms, cards, badges, empty states, dialogs, stats, and notifications. | | @saas-pro-lib/ui/team | API-independent team/org display components such as member lists, role badges, role summaries, and invite dialogs. |

The root export @saas-pro-lib/ui remains available for backward compatibility and re-exports both subpaths.

Tailwind class strings are baked in but composed via clsx so the consumer can override anything with className. The package does not ship a CSS file — the consumer's Tailwind setup must include node_modules/@saas-pro-lib/ui/dist/**/* in its content glob.

Components

| Export | Purpose | | ------------- | ---------------------------------------------------- | | <Button> | Primary / secondary / ghost / danger / warning × sm / md / lg. | | <Badge> | Small semantic label for statuses, roles, and metadata. | | <Alert> | Info / success / warning / error banner. | | <Input> | Bare text input with invalid styling. | | <FormField> | <label> + error/hint + child render-prop. | | <Card> | Padded white panel with optional title / footer. | | <RequiredBadge> | Small required marker for form labels. | | <EmptyState> | Empty state block for pages, sections, and tables. | | <TableEmptyRow> | Table row wrapper for empty table bodies. | | <StatCard> | Metric / chart card with header and optional footer. | | <ConfirmDialog> | Confirmation modal for destructive / warning flows. | | <Skeleton> / <SkeletonText> / <SkeletonAvatar> | Low-level skeleton primitives for page and section loading. | | <SkeletonCard> / <SkeletonTable> | Ready-made skeleton layouts for repeated cards and tables. | | <LoadingSpinner> / <LoadingState> | Spinner-based feedback for actions and blocking operations. | | <LoadingBoundary> | Tiny conditional wrapper for loading fallback composition. | | <ProgressBar> | Determinate progress for tasks with known completion. | | <NotificationProvider> | Toast notification state provider. | | <NotificationContainer> | Fixed-position toast notification stack. |

Team Components

| Export | Purpose | | ---------------------- | ------- | | <TeamMemberList> | Table-style team member list with optional department / joined date / last active columns. | | <TeamInvitationList> | Table-style invitation history list. | | <RoleBadge> | Role label badge. | | <MemberStatusBadge> | Active / inactive / pending status badge. | | <RoleSummary> | Role count summary with donut-style visual and bars. | | <InviteMemberDialog> | Controlled invite dialog. Data submission is passed in via props. |

Install (workspace)

// consumer's package.json
{
  "dependencies": {
    "@saas-pro-lib/ui": "file:../../saas-pro-lib/sdk/ui/react",
  },
}

Tailwind config

The consumer needs the brand color tokens used by primary/focus styling. Add to tailwind.config.ts:

theme: {
  extend: {
    colors: {
      brand: "#2563eb",
      "brand-hover": "#1d4ed8",
    },
  },
},
content: [
  "./src/**/*.{ts,tsx}",
  "./node_modules/@saas-pro-lib/ui/dist/**/*.{js,mjs}",
],

Usage

import {
  Alert,
  Button,
  EmptyState,
  FormField,
  Input,
  NotificationContainer,
  NotificationProvider,
  useNotification,
} from "@saas-pro-lib/ui/common";

import {
  InviteMemberDialog,
  RoleSummary,
  TeamMemberList,
} from "@saas-pro-lib/ui/team";

<FormField label="メールアドレス" required error={errors.email}>
  {(id) => (
    <Input id={id} type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
  )}
</FormField>

<Button variant="primary">保存する</Button>
<Alert variant="error">入力内容を確認してください</Alert>
<EmptyState title="データがありません" description="条件を変更してください" />

Loading Usage

Use loading components as product-agnostic primitives. Keep API calls, polling, and generated data state in product code, then choose the smallest loading component that communicates the current wait.

import {
  Button,
  LoadingBoundary,
  LoadingSpinner,
  LoadingState,
  ProgressBar,
  SkeletonCard,
  SkeletonTable,
} from "@saas-pro-lib/ui/common";

<LoadingBoundary
  loading={loading}
  fallback={<SkeletonTable rows={5} columns={[240, 120, 160, 80]} />}
>
  <CampaignTable campaigns={campaigns} />
</LoadingBoundary>

<div className="grid gap-4 md:grid-cols-3">
  <SkeletonCard />
  <SkeletonCard />
  <SkeletonCard />
</div>

<Button disabled={saving}>
  {saving ? <LoadingSpinner size="sm" decorative className="mr-2" /> : null}
  保存する
</Button>

<LoadingState
  label="広告文を生成しています"
  description="数十秒かかる場合があります。画面を閉じずにお待ちください。"
/>

<ProgressBar value={uploadedBytes} max={totalBytes} label="アップロード中" showValue />

Loading Guidelines

Choose loading states by the user's context, not by implementation convenience.

| Context | Use | Avoid | | ------- | --- | ----- | | Initial page, section, card, table, or form data loading | Skeleton / shimmer that roughly matches the final layout. | A single centered spinner for large content areas. | | Button click, save, delete, publish, invite, or other user action | Inline LoadingSpinner near the action and disable the triggering control. | Replacing the whole page with a skeleton. | | Known progress such as upload, import, or batch processing | ProgressBar with a concise label and percentage when useful. | Indeterminate spinner when the system knows progress. | | Long-running AI generation or external API work | LoadingState with a short status message; update the message if stages are known. | Empty skeletons that imply normal content is about to appear immediately. | | Fast responses under roughly one second | Prefer pressed/disabled state only, or delay showing fallback in product code. | Flashing skeletons that create visual noise. |

Skeletons should be low fidelity. Match the broad shape and density of the final UI, but do not mirror every detail. Keep stable dimensions so content does not jump when the real data arrives. When a page title or static navigation is already known, render the real text and apply skeletons only to dynamic content.

Do not mix several loading indicators in the same region. For example, a table should use either SkeletonTable or a section-level LoadingState, not both. For accessibility, use LoadingState for blocking waits that need a status announcement, and mark decorative inline spinners with decorative.

Team Usage

team components do not call auth or product APIs by themselves. Keep data fetching in @saas-pro-lib/auth, GraphQL hooks, or product-specific code, then pass display data and event handlers in through props.

<TeamMemberList
  members={[
    {
      id: "u_1",
      name: "田中 太郎",
      email: "[email protected]",
      role: { id: "admin", label: "管理者", tone: "blue" },
      department: "マーケティング",
      joinedAt: "2025/01/01",
      lastActiveAt: "2025/01/24",
      status: "active",
    },
  ]}
/>

<RoleSummary
  items={[
    { id: "admin", label: "管理者", count: 2, tone: "blue" },
    { id: "editor", label: "編集者", count: 3, tone: "cyan" },
  ]}
/>

<InviteMemberDialog
  open={inviteOpen}
  roles={[
    { id: "admin", label: "管理者", tone: "blue" },
    { id: "viewer", label: "閲覧者", tone: "gray" },
  ]}
  onClose={() => setInviteOpen(false)}
  onSubmit={(input) => inviteMember(input)}
/>

Notifications

Wrap the application once with NotificationProvider, render NotificationContainer, and call showNotification from child components.

function AppShell({ children }: { children: React.ReactNode }) {
  return (
    <NotificationProvider>
      {children}
      <NotificationContainer />
    </NotificationProvider>
  );
}

function SaveButton() {
  const { showNotification } = useNotification();

  return (
    <Button
      onClick={() =>
        showNotification({
          message: "保存しました",
          type: "success",
          duration: 5000,
        })
      }
    >
      保存する
    </Button>
  );
}