mantur-components 0.1.0

package/README.md

@@ -0,0 +1,178 @@
+# mantur-components
+
+Reusable Mantur React component library for React and Arco Design.
+
+## Install
+
+```bash
+npm install mantur-components
+```
+
+Required peer dependencies:
+
+```bash
+npm install react react-dom @arco-design/web-react next-themes react-i18next
+```
+
+The library uses Tailwind utility classes and does not export a standalone CSS file.
+
+## ManturHeader
+
+`ManturHeader` is the shared Mantur user header. It owns the header UI and the API calls for:
+
+- tenant list
+- current tenant
+- tenant switching
+- user points
+- profile update
+- logout
+- language switch
+- theme switch
+
+Basic usage:
+
+```tsx
+import { ManturHeader } from "mantur-components";
+
+export function Header({ userInfo }: { userInfo: { username?: string; nickname?: string; avatar?: string } | null }) {
+  return <ManturHeader user={userInfo} />;
+}
+```
+
+With disabled tenant switching and custom slots:
+
+```tsx
+import { ManturHeader } from "mantur-components";
+
+export function Header({ userInfo, disabled }: { userInfo: UserInfo | null; disabled?: boolean }) {
+  return (
+    <ManturHeader
+      user={userInfo}
+      disabled={disabled}
+      brandSlot={<span className="text-lg font-bold">Custom Brand</span>}
+    >
+      <div className="px-4">Custom center content</div>
+    </ManturHeader>
+  );
+}
+```
+
+### Props
+
+```ts
+interface ManturHeaderProps {
+  user?: ManturHeaderUser | null;
+  disabled?: boolean;
+  brandSlot?: React.ReactNode;
+  children?: React.ReactNode;
+}
+```
+
+`user`: Current user shown in the right user menu.
+
+`disabled`: Disables tenant switching. When true, the tenant selector is shown as disabled and cannot be opened or switched.
+
+`brandSlot`: Replaces the default brand title next to the logo. If omitted, the default localized title is shown.
+
+`children`: Renders custom content in the middle flexible header area. If omitted, the area stays empty.
+
+### User Type
+
+```ts
+interface ManturHeaderUser {
+  userId?: string;
+  username?: string;
+  nickname?: string;
+  avatar?: string;
+  email?: string;
+}
+```
+
+### API Base
+
+By default, API requests use `import.meta.env.VITE_API` and fall back to `/api`.
+
+You can override it before rendering:
+
+```ts
+window.__MANTUR_COMPONENTS_API_BASE__ = "/api";
+```
+
+Points endpoint defaults to `/users/me/points`. It can be overridden:
+
+```ts
+window.__MANTUR_COMPONENTS_POINTS_ENDPOINT__ = "/users/me/points";
+```
+
+### Tenant Context Event
+
+The header fetches and switches tenants internally. If the host app needs to sync local stores, listen to `MANTUR_TENANT_CONTEXT_CHANGE_EVENT`.
+
+```tsx
+import {
+  getManturTenantContextSnapshot,
+  MANTUR_TENANT_CONTEXT_CHANGE_EVENT,
+  type ManturTenantContextDetail,
+} from "mantur-components";
+
+function applyTenantContext(detail: ManturTenantContextDetail) {
+  const tenantId = detail.auth?.tenantId || detail.currentTenant?.tenantId;
+
+  // Sync host app stores here.
+  // setActiveTenantId(tenantId)
+  // setPermissions(detail.auth?.permissions || [])
+  // setRoles(detail.auth?.roles || [])
+  // setEnabledApps(detail.auth?.enabledApps || [])
+}
+
+window.addEventListener(MANTUR_TENANT_CONTEXT_CHANGE_EVENT, (event) => {
+  if (event instanceof CustomEvent) {
+    applyTenantContext(event.detail as ManturTenantContextDetail);
+  }
+});
+
+const snapshot = getManturTenantContextSnapshot();
+if (snapshot) {
+  applyTenantContext(snapshot);
+}
+```
+
+Tenant context detail:
+
+```ts
+interface ManturTenantContextDetail {
+  tenants: ManturTenant[];
+  currentTenant?: ManturTenant;
+  auth?: {
+    tenantId: string;
+    tenantName?: string;
+    roles?: string[];
+    permissions?: string[];
+    enabledApps?: string[];
+  };
+  reason: "refresh" | "switch";
+}
+```
+
+### Exported Helpers
+
+```ts
+import {
+  getManturCurrentTenant,
+  getManturTenantContextSnapshot,
+  getManturTenants,
+  getManturUserPoints,
+  MANTUR_POINTS_REFRESH_EVENT,
+  MANTUR_TENANT_CONTEXT_CHANGE_EVENT,
+  refreshManturTenantContext,
+  refreshManturUserPoints,
+  switchAndRefreshManturTenant,
+  switchManturTenant,
+} from "mantur-components";
+```
+
+## Build
+
+```bash
+npm run build
+```

package/dist/api.d.ts

@@ -0,0 +1,21 @@
+import type { ManturHeaderUser, ManturProfileValues, ManturTenant, ManturTenantAuthContext, ManturTenantContextDetail, ManturUserPoints } from "./types";
+export declare const MANTUR_POINTS_REFRESH_EVENT = "mantur-points-refresh";
+export declare const MANTUR_TENANT_CONTEXT_CHANGE_EVENT = "mantur-tenant-context-change";
+declare global {
+    interface Window {
+        __MANTUR_COMPONENTS_API_BASE__?: string;
+        __MANTUR_COMPONENTS_POINTS_ENDPOINT__?: string;
+        __MANTUR_COMPONENTS_TENANT_CONTEXT__?: ManturTenantContextDetail;
+    }
+}
+export declare function removeManturCookie(name: string): void;
+export declare function logoutManturUser(): Promise<void>;
+export declare function updateManturProfile(values: ManturProfileValues): Promise<ManturHeaderUser | undefined>;
+export declare function getManturUserPoints(): Promise<ManturUserPoints>;
+export declare function refreshManturUserPoints(): Promise<ManturUserPoints>;
+export declare function getManturTenantContextSnapshot(): ManturTenantContextDetail | undefined;
+export declare function getManturTenants(): Promise<ManturTenant[]>;
+export declare function getManturCurrentTenant(): Promise<ManturTenantAuthContext | undefined>;
+export declare function switchManturTenant(tenantId: string): Promise<ManturTenantAuthContext | undefined>;
+export declare function refreshManturTenantContext(reason?: ManturTenantContextDetail["reason"]): Promise<ManturTenantContextDetail>;
+export declare function switchAndRefreshManturTenant(tenantId: string): Promise<ManturTenantContextDetail>;

package/dist/header/ManturHeader.d.ts

@@ -0,0 +1,2 @@
+import type { ManturHeaderProps } from "../types";
+export declare function ManturHeader({ user, disabled, brandSlot, children, }: ManturHeaderProps): import("react/jsx-runtime").JSX.Element;

package/dist/header/components/PointsDetailModal.d.ts

@@ -0,0 +1,8 @@
+import type { ManturHeaderLabels, ManturUserPoints } from "../../types";
+export declare function PointsDetailModal({ visible, points, text, onCancel, onRecharge, }: {
+    visible: boolean;
+    points: Required<ManturUserPoints>;
+    text: ManturHeaderLabels;
+    onCancel: () => void;
+    onRecharge: () => void;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/header/components/ProfileModal.d.ts

@@ -0,0 +1,2 @@
+import type { ProfileModalProps } from "../../types";
+export declare function ProfileModal({ visible, user, labels, onCancel, onSubmit, }: ProfileModalProps): import("react/jsx-runtime").JSX.Element;

package/dist/header/components/RechargeModal.d.ts

@@ -0,0 +1,10 @@
+import type { ManturHeaderLabels, ManturHeaderUser, ManturUserPoints } from "../../types";
+import { type RechargePackage } from "../mock";
+export declare function RechargeModal({ visible, user, points, text, onCancel, onPay, }: {
+    visible: boolean;
+    user?: ManturHeaderUser | null;
+    points: Required<ManturUserPoints>;
+    text: ManturHeaderLabels;
+    onCancel: () => void;
+    onPay: (rechargePackage: RechargePackage) => void;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/header/components/UserAvatar.d.ts

@@ -0,0 +1,7 @@
+import type { ManturHeaderUser } from "../../types";
+export declare function getUserInitial(user?: ManturHeaderUser | null): string;
+export declare function ManturUserAvatar({ user, size, className, }: {
+    user?: ManturHeaderUser | null;
+    size: number;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/header/components/UserMenu.d.ts

@@ -0,0 +1,10 @@
+import type { ManturHeaderLabels, ManturHeaderUser, ManturUserPoints } from "../../types";
+export declare function UserMenu({ user, points, text, onEditProfile, onRecharge, onPointsDetail, onLogout, }: {
+    user?: ManturHeaderUser | null;
+    points: Required<ManturUserPoints>;
+    text: ManturHeaderLabels;
+    onEditProfile: () => void;
+    onRecharge: () => void;
+    onPointsDetail: () => void;
+    onLogout?: () => void | Promise<void>;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/header/index.d.ts

@@ -0,0 +1 @@
+export { ManturHeader } from "./ManturHeader";

package/dist/header/mock.d.ts

@@ -0,0 +1,35 @@
+export declare const RECHARGE_PACKAGES: readonly [{
+    readonly id: "points-500";
+    readonly points: 500;
+    readonly price: 5;
+}, {
+    readonly id: "points-1000";
+    readonly points: 1000;
+    readonly price: 10;
+}, {
+    readonly id: "points-5500";
+    readonly points: 5500;
+    readonly price: 50;
+    readonly recommended: true;
+}, {
+    readonly id: "points-24000";
+    readonly points: 24000;
+    readonly price: 200;
+}];
+export type RechargePackage = (typeof RECHARGE_PACKAGES)[number];
+export type RechargePackageId = RechargePackage["id"];
+export type PointsLedgerType = "all" | "income" | "expense";
+export type PointsLedgerSource = "all" | "recharge" | "gift";
+export type PointsLedgerBadgeKind = "recharge" | "gift" | "deducted" | "expired";
+export interface PointsLedgerRecord {
+    id: string;
+    type: Exclude<PointsLedgerType, "all">;
+    source?: Exclude<PointsLedgerSource, "all">;
+    name: string;
+    meta: string;
+    date: string;
+    amount: number;
+    badgeKind: PointsLedgerBadgeKind;
+    badgeText: string;
+}
+export declare const MOCK_POINTS_LEDGER: PointsLedgerRecord[];

package/dist/i18n.d.ts

@@ -0,0 +1,13 @@
+import type { ManturHeaderLabels } from "./types";
+export type ManturLocale = "zh-CN" | "en-US";
+export interface ManturMessages extends ManturHeaderLabels {
+    languageZh: string;
+    languageEn: string;
+}
+export declare const MANTUR_LANGUAGE_STORAGE_KEY = "i18nextLng";
+export declare const MANTUR_LANGUAGE_SOURCE_STORAGE_KEY = "manturLanguageSource";
+export declare const MANTUR_LANGUAGE_CHANGE_EVENT = "mantur-language-change";
+export declare const MANTUR_MESSAGES: Record<ManturLocale, ManturMessages>;
+export declare function normalizeManturLocale(language?: string): ManturLocale;
+export declare function getStoredManturLocale(): ManturLocale;
+export declare function getManturMessages(language?: string): ManturMessages;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { ManturHeader } from "./header";
+export { getManturCurrentTenant, getManturTenantContextSnapshot, getManturTenants, getManturUserPoints, MANTUR_POINTS_REFRESH_EVENT, MANTUR_TENANT_CONTEXT_CHANGE_EVENT, refreshManturUserPoints, refreshManturTenantContext, switchAndRefreshManturTenant, switchManturTenant, } from "./api";
+export { getManturMessages, getStoredManturLocale, MANTUR_LANGUAGE_CHANGE_EVENT, MANTUR_LANGUAGE_SOURCE_STORAGE_KEY, MANTUR_LANGUAGE_STORAGE_KEY, MANTUR_MESSAGES, normalizeManturLocale, } from "./i18n";
+export { LangSwitch, LANGUAGE_SOURCE_STORAGE_KEY, LANGUAGE_STORAGE_KEY } from "./lang-switch";
+export { ThemeSwitch } from "./theme-switch";
+export type { ManturLocale, ManturMessages } from "./i18n";
+export type { ManturHeaderLabels, ManturHeaderProps, ManturHeaderUser, ManturProfileValues, ManturRole, ManturTenant, ManturTenantAuthContext, ManturTenantContextDetail, ManturUserPoints, } from "./types";

package/dist/labels.d.ts

@@ -0,0 +1,3 @@
+import type { ManturHeaderLabels } from "./types";
+export declare const DEFAULT_LABELS: ManturHeaderLabels;
+export declare function mergeLabels(labels?: Partial<ManturHeaderLabels>): ManturHeaderLabels;

package/dist/lang-switch/LangSwitch.d.ts

@@ -0,0 +1,3 @@
+export declare const LANGUAGE_STORAGE_KEY = "i18nextLng";
+export declare const LANGUAGE_SOURCE_STORAGE_KEY = "manturLanguageSource";
+export declare function LangSwitch(): import("react/jsx-runtime").JSX.Element;

package/dist/lang-switch/index.d.ts

@@ -0,0 +1 @@
+export { LANGUAGE_SOURCE_STORAGE_KEY, LANGUAGE_STORAGE_KEY, LangSwitch } from "./LangSwitch";