@rytass/bpm-core-react 0.16.2 → 0.17.1

package/dist/components/admin-pickers.d.cts

@@ -0,0 +1,65 @@
+import { ReactElement } from 'react';
+import { OrgUnitRecord, PositionRecord } from '@rytass/bpm-core-client/organization';
+export type MemberOption = Readonly<{
+    email: string;
+    id: string;
+    name: string;
+}>;
+export type OrgUnitOption = Readonly<{
+    id: string;
+    name: string;
+}>;
+export type PositionOption = Readonly<{
+    id: string;
+    name: string;
+}>;
+interface MemberPickerProps {
+    readonly disabled?: boolean;
+    readonly name: string;
+    readonly onChange: (option: MemberOption | null) => void;
+    readonly placeholder?: string;
+    readonly size?: 'main' | 'sub';
+    readonly value: MemberOption | null;
+}
+interface OrgUnitPickerProps {
+    readonly disabled?: boolean;
+    readonly name: string;
+    readonly onChange: (option: OrgUnitOption | null) => void;
+    readonly orgUnits: readonly OrgUnitRecord[];
+    readonly placeholder?: string;
+    readonly size?: 'main' | 'sub';
+    readonly value: OrgUnitOption | null;
+}
+interface PositionPickerProps {
+    readonly disabled?: boolean;
+    readonly name: string;
+    readonly onChange: (option: PositionOption | null) => void;
+    readonly placeholder?: string;
+    readonly positions: readonly PositionRecord[];
+    readonly size?: 'main' | 'sub';
+    readonly value: PositionOption | null;
+}
+/**
+ * AutoComplete-backed picker that searches the BPM member directory via
+ * `searchMembers()`. Emits a {@link MemberOption} `{ id, name, email }`
+ * on selection (or `null` when cleared).
+ */
+export declare function MemberPicker({ disabled, name, onChange, placeholder, size, value, }: MemberPickerProps): ReactElement;
+/**
+ * Static `<Select>` over a pre-fetched list of org units. Caller is
+ * responsible for fetching the org units (typically via
+ * `readOrganizationDashboard` from `@rytass/bpm-core-client/organization`).
+ */
+export declare function OrgUnitPicker({ disabled, onChange, orgUnits, placeholder, size, value, }: OrgUnitPickerProps): ReactElement;
+/**
+ * Static `<Select>` over a pre-fetched list of positions.
+ */
+export declare function PositionPicker({ disabled, onChange, placeholder, positions, size, value, }: PositionPickerProps): ReactElement;
+export declare function readMemberOption(member: {
+    readonly email: string;
+    readonly memberId: string;
+    readonly name: string;
+}): MemberOption;
+export declare function readOrgUnitOption(orgUnit: OrgUnitRecord): OrgUnitOption;
+export declare function readPositionOption(position: PositionRecord): PositionOption;
+export {};

package/dist/components/approval-instance-list-page.d.cts

@@ -0,0 +1,17 @@
+import { ReactElement } from 'react';
+import { ApprovalInstanceState, ApprovalInstanceView } from '@rytass/bpm-core-client/workflow';
+export interface ApprovalInstanceListPageProps {
+    readonly defaultState: ApprovalInstanceState | null;
+    readonly description: string;
+    readonly emptyMessage: string;
+    readonly searchPlaceholder: string;
+    readonly title: string;
+    readonly view: ApprovalInstanceView;
+}
+/**
+ * Shared list page for any approval-instance "view" (inbox / sent / cc /
+ * delegated). Caller picks the view + default state filter; the page renders
+ * the standard BPM filter bar + paginated table and navigates to
+ * `/instances/:id` on row action.
+ */
+export declare function ApprovalInstanceListPage({ defaultState, description, emptyMessage, searchPlaceholder, title, view, }: ApprovalInstanceListPageProps): ReactElement;

package/dist/components/bpm-form-field.d.cts

@@ -0,0 +1,10 @@
+import { ReactElement } from 'react';
+import { FormFieldProps } from '@mezzanine-ui/react';
+type BPMFormFieldProps = Omit<FormFieldProps, 'density' | 'fullWidth' | 'layout'> & Partial<Pick<FormFieldProps, 'density' | 'fullWidth' | 'layout'>>;
+/**
+ * Mezzanine `<FormField>` pre-configured with the BPM admin defaults
+ * (`TIGHT` density, `HORIZONTAL` layout, full width). Use everywhere a
+ * label-aligned field is needed.
+ */
+export declare function BPMFormField({ density, fullWidth, layout, ...props }: BPMFormFieldProps): ReactElement;
+export {};

package/dist/components/bpm-notification-bell-button.d.cts

@@ -0,0 +1,22 @@
+import { ReactElement } from 'react';
+export interface BPMNotificationBellButtonProps {
+    /** Override the aria-label / tooltip. Defaults to `通知中心`. */
+    readonly label?: string;
+}
+/**
+ * Drop-in notification bell. Reads the unread count from
+ * `<NotificationUnreadProvider>`, opens the BPM `<NotificationDrawer />`
+ * mounted by `<Providers>` (or `<BPMNextProviders>`) on click, and
+ * renders a small red badge with the unread count.
+ *
+ * Use this when the host navigation wants the BPM notification UX with
+ * minimum wiring. Hosts that need a fully custom button can skip this
+ * widget and consume `useNotificationDrawer()` + `useNotificationUnread()`
+ * directly to wire their own trigger.
+ *
+ * Visual: uses Mezzanine `NavigationIconButton` so the bell aligns with
+ * surrounding Mezzanine navigation chrome. The button is decoupled from
+ * the `<Navigation>` container — it does not require a Mezzanine
+ * navigation tree to render.
+ */
+export declare function BPMNotificationBellButton({ label, }?: BPMNotificationBellButtonProps): ReactElement;

package/dist/components/dashboard-page.d.cts

@@ -0,0 +1,7 @@
+import { ReactElement } from 'react';
+/**
+ * Operator dashboard — shows pending/unread/active counts for the
+ * currently-authenticated member. Reads {@link readWorkflowDashboardSummary}
+ * and renders five metric tiles that navigate via {@link useRouterAdapter}.
+ */
+export declare function DashboardPage(): ReactElement;

package/dist/components/notification-drawer.d.cts

@@ -0,0 +1,11 @@
+import { ReactElement } from 'react';
+/**
+ * Right-side notification drawer mounted at the root by `<Providers>`.
+ * Opens / closes via `useNotificationDrawer()`, polls
+ * `listNotifications()` for the current member, supports filter
+ * (`all` / `read` / `unread`), per-row mark-read, per-row archive / unarchive,
+ * bulk mark-all-read, and load-more pagination. Archived notifications are
+ * hidden until the filter-bar menu turns "顯示已封存" on. Clicking a row with an
+ * `instanceId` navigates to `/instances/<id>` via the host's router adapter.
+ */
+export declare function NotificationDrawer(): ReactElement | null;

package/dist/components/org-unit-tree-draft-editor.d.cts

@@ -0,0 +1,24 @@
+import { OrgUnitRecord } from '@rytass/bpm-core-client/organization';
+import { OrgUnitHierarchyDraftChange } from '../lib/org-tree-draft.cjs';
+export type OrgUnitTreeDraftEditorHandle = Readonly<{
+    cancelEditing: () => void;
+    saveDraft: () => Promise<void>;
+    startEditing: () => void;
+}>;
+export type OrgUnitTreeDraftEditorState = Readonly<{
+    hasDraftChanges: boolean;
+    isEditing: boolean;
+}>;
+export declare const OrgUnitTreeDraftEditor: import('react').ForwardRefExoticComponent<Readonly<{
+    onCreateChild: (parentId: string) => void;
+    onCreateRoot: () => void;
+    onEditOrgUnit: (orgUnit: OrgUnitRecord) => void;
+    onSaveDraft?: (changes: readonly OrgUnitHierarchyDraftChange[]) => Promise<void>;
+    onStateChange: (state: OrgUnitTreeDraftEditorState) => void;
+    orgUnits: readonly OrgUnitRecord[];
+    saving: boolean;
+}> & import('react').RefAttributes<Readonly<{
+    cancelEditing: () => void;
+    saveDraft: () => Promise<void>;
+    startEditing: () => void;
+}>>>;

package/dist/components/org-unit-tree-draft-editor.d.ts

@@ -1,5 +1,5 @@
 import { OrgUnitRecord } from '@rytass/bpm-core-client/organization';
-import { OrgUnitHierarchyDraftChange } from '../lib/org-tree-draft';
+import { OrgUnitHierarchyDraftChange } from '../lib/org-tree-draft.js';
 export type OrgUnitTreeDraftEditorHandle = Readonly<{
     cancelEditing: () => void;
     saveDraft: () => Promise<void>;

package/dist/components/pdf-preview.d.cts

@@ -0,0 +1,12 @@
+import { ReactElement } from 'react';
+export declare function configurePdfWorker(workerSrc: string): void;
+export interface PDFPreviewProps {
+    readonly filename: string;
+    readonly fileUrl: string;
+    readonly onDownload?: () => void;
+}
+/**
+ * Mezzanine-styled PDF preview powered by `react-pdf`. Used by the instance
+ * detail view to preview PDF attachments inline.
+ */
+export declare function PDFPreview({ filename, fileUrl, onDownload, }: PDFPreviewProps): ReactElement;

package/dist/index.cjs

@@ -1,2 +1,2 @@
-"use client";Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});require('./index.css');const e=require("./chunks/router-adapter--gYs13E8.cjs"),t=require("./chunks/auth-provider-4BeCw7cI.cjs"),n=require("./chunks/format-date-time-D-cx5M8z.cjs"),r=require("./chunks/providers-DHtDZFNA.cjs"),i=require("./chunks/routes-config-C1j_vFKo.cjs"),a=require("./chunks/bpm-form-field-Bc6k4ZEO.cjs"),o=require("./chunks/use-bpm-member-DpNAQtNC.cjs"),s=require("./chunks/admin-pickers-qe3j--gX.cjs"),c=require("./chunks/approval-instance-list-page-ax0pm8bt.cjs"),l=require("./chunks/dashboard-page-BWQBSGDq.cjs");let u=require("@mezzanine-ui/react"),d=require("react/jsx-runtime"),f=require("@mezzanine-ui/icons");function p(){let{logout:e}=t.n();return e}var m={root:`bpm_root_jl5S-`,badge:`bpm_badge_SIKJk`};function h({label:e=`通知中心`}={}){let{open:t}=r.o(),{unreadCount:n}=r.i(),i=n>0?`${e}，${n} 則未讀`:e;return(0,d.jsxs)(`span`,{className:m.root,children:[(0,d.jsx)(u.NavigationIconButton,{"aria-label":i,icon:f.NotificationUnreadIcon,onClick:()=>{t()},title:e,type:`button`}),n>0?(0,d.jsx)(`span`,{className:m.badge,children:n>99?`99+`:n}):null]})}exports.ApprovalInstanceListPage=c.t,exports.AuthProvider=t.t,exports.BPMFormField=a.t,exports.BPMNotificationBellButton=h,exports.BPMRoutesProvider=i.t,exports.DashboardPage=l.t,exports.MemberPicker=s.t,exports.NotificationDrawer=r.n,exports.NotificationDrawerProvider=r.a,exports.NotificationUnreadProvider=r.r,exports.OrgUnitPicker=s.n,exports.PositionPicker=s.r,exports.Providers=r.t,exports.RouterAdapterProvider=e.t,exports.createDefaultBPMRoutes=i.n,exports.defaultBrowserSearchParams=e.n,exports.formatDateTime=n.t,exports.isBPMAdminMember=o.t,exports.readMemberOption=s.i,exports.readOrgUnitOption=s.a,exports.readPositionOption=s.o,exports.useAuth=t.n,exports.useBPMLogout=p,exports.useBPMMember=o.n,exports.useBPMRoutes=i.r,exports.useNotificationDrawer=r.o,exports.useNotificationUnread=r.i,exports.useRouterAdapter=e.r;
+"use client";Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});require('./index.css');const e=require("./chunks/router-adapter--gYs13E8.cjs"),t=require("./chunks/auth-provider-4BeCw7cI.cjs"),n=require("./chunks/format-date-time-D-cx5M8z.cjs"),r=require("./chunks/providers-DHtDZFNA.cjs"),i=require("./chunks/routes-config-C1j_vFKo.cjs"),a=require("./chunks/bpm-form-field-Bc6k4ZEO.cjs"),o=require("./chunks/use-bpm-member-DpNAQtNC.cjs"),s=require("./chunks/admin-pickers-BRHk3qKq.cjs"),c=require("./chunks/approval-instance-list-page-ax0pm8bt.cjs"),l=require("./chunks/dashboard-page-BWQBSGDq.cjs");let u=require("@mezzanine-ui/react"),d=require("react/jsx-runtime"),f=require("@mezzanine-ui/icons");function p(){let{logout:e}=t.n();return e}var m={root:`bpm_root_jl5S-`,badge:`bpm_badge_SIKJk`};function h({label:e=`通知中心`}={}){let{open:t}=r.o(),{unreadCount:n}=r.i(),i=n>0?`${e}，${n} 則未讀`:e;return(0,d.jsxs)(`span`,{className:m.root,children:[(0,d.jsx)(u.NavigationIconButton,{"aria-label":i,icon:f.NotificationUnreadIcon,onClick:()=>{t()},title:e,type:`button`}),n>0?(0,d.jsx)(`span`,{className:m.badge,children:n>99?`99+`:n}):null]})}exports.ApprovalInstanceListPage=c.t,exports.AuthProvider=t.t,exports.BPMFormField=a.t,exports.BPMNotificationBellButton=h,exports.BPMRoutesProvider=i.t,exports.DashboardPage=l.t,exports.MemberPicker=s.t,exports.NotificationDrawer=r.n,exports.NotificationDrawerProvider=r.a,exports.NotificationUnreadProvider=r.r,exports.OrgUnitPicker=s.n,exports.PositionPicker=s.r,exports.Providers=r.t,exports.RouterAdapterProvider=e.t,exports.createDefaultBPMRoutes=i.n,exports.defaultBrowserSearchParams=e.n,exports.formatDateTime=n.t,exports.isBPMAdminMember=o.t,exports.readMemberOption=s.i,exports.readOrgUnitOption=s.a,exports.readPositionOption=s.o,exports.useAuth=t.n,exports.useBPMLogout=p,exports.useBPMMember=o.n,exports.useBPMRoutes=i.r,exports.useNotificationDrawer=r.o,exports.useNotificationUnread=r.i,exports.useRouterAdapter=e.r;
 //# sourceMappingURL=index.cjs.map

package/dist/index.d.cts

@@ -0,0 +1,15 @@
+export * from './lib/auth-provider.cjs';
+export * from './lib/format-date-time.cjs';
+export * from './lib/notification-drawer-provider.cjs';
+export * from './lib/notification-unread-provider.cjs';
+export * from './lib/providers.cjs';
+export * from './lib/router-adapter.cjs';
+export * from './lib/routes-config.cjs';
+export * from './lib/use-bpm-logout.cjs';
+export * from './lib/use-bpm-member.cjs';
+export * from './components/admin-pickers.cjs';
+export * from './components/approval-instance-list-page.cjs';
+export * from './components/bpm-form-field.cjs';
+export * from './components/bpm-notification-bell-button.cjs';
+export * from './components/dashboard-page.cjs';
+export * from './components/notification-drawer.cjs';

package/dist/index.d.ts

@@ -1,15 +1,15 @@
-export * from './lib/auth-provider';
-export * from './lib/format-date-time';
-export * from './lib/notification-drawer-provider';
-export * from './lib/notification-unread-provider';
-export * from './lib/providers';
-export * from './lib/router-adapter';
-export * from './lib/routes-config';
-export * from './lib/use-bpm-logout';
-export * from './lib/use-bpm-member';
-export * from './components/admin-pickers';
-export * from './components/approval-instance-list-page';
-export * from './components/bpm-form-field';
-export * from './components/bpm-notification-bell-button';
-export * from './components/dashboard-page';
-export * from './components/notification-drawer';
+export * from './lib/auth-provider.js';
+export * from './lib/format-date-time.js';
+export * from './lib/notification-drawer-provider.js';
+export * from './lib/notification-unread-provider.js';
+export * from './lib/providers.js';
+export * from './lib/router-adapter.js';
+export * from './lib/routes-config.js';
+export * from './lib/use-bpm-logout.js';
+export * from './lib/use-bpm-member.js';
+export * from './components/admin-pickers.js';
+export * from './components/approval-instance-list-page.js';
+export * from './components/bpm-form-field.js';
+export * from './components/bpm-notification-bell-button.js';
+export * from './components/dashboard-page.js';
+export * from './components/notification-drawer.js';

package/dist/index.js

@@ -6,7 +6,7 @@ import { a as o, i as s, n as c, o as l, r as u, t as d } from "./chunks/provide
 import { n as f, r as p, t as m } from "./chunks/routes-config-yZbESPlw.js";
 import { t as h } from "./chunks/bpm-form-field-Cao0rMol.js";
 import { n as g, t as _ } from "./chunks/use-bpm-member-D57LKe_u.js";
-import { a as v, i as y, n as b, o as x, r as S, t as C } from "./chunks/admin-pickers-DxhzECkD.js";
+import { a as v, i as y, n as b, o as x, r as S, t as C } from "./chunks/admin-pickers-Djq3h-UR.js";
 import { t as w } from "./chunks/approval-instance-list-page-CPXMP3PL.js";
 import { t as T } from "./chunks/dashboard-page-DdBvV6YI.js";
 import { NavigationIconButton as E } from "@mezzanine-ui/react";

package/dist/lib/auth-provider.d.cts

@@ -0,0 +1,37 @@
+import { ReactElement, ReactNode } from 'react';
+import { ApiMember } from '@rytass/bpm-core-client';
+interface AuthContextValue {
+    readonly loading: boolean;
+    readonly member: ApiMember | null;
+    readonly login: (input: {
+        readonly identifier: string;
+        readonly password: string;
+    }) => Promise<ApiMember>;
+    readonly logout: () => Promise<void>;
+    readonly refresh: () => Promise<ApiMember | null>;
+}
+export interface AuthProviderProps {
+    readonly children: ReactNode;
+    /**
+     * Paths that should not redirect to `/login` when there is no session.
+     * Defaults to `['/login']`. Override when your host runs the login UI
+     * under a different path.
+     */
+    readonly publicPaths?: readonly string[];
+    /**
+     * Where to send unauthenticated users. Defaults to `'/login'`.
+     */
+    readonly loginPath?: string;
+}
+/**
+ * BPM auth context provider. Reads / writes the host BPM API session via
+ * `@rytass/bpm-core-client` (`loginApi` / `logoutApi` / `readApiCurrentMember`)
+ * and uses the host-supplied {@link useRouterAdapter} to redirect
+ * unauthenticated users.
+ */
+export declare function AuthProvider({ children, publicPaths, loginPath, }: AuthProviderProps): ReactElement;
+/**
+ * Access the BPM auth context. Throws when used outside `<AuthProvider>`.
+ */
+export declare function useAuth(): AuthContextValue;
+export {};

package/dist/lib/format-date-time.d.cts

@@ -0,0 +1,5 @@
+/**
+ * Default BPM datetime formatter: `YYYY-MM-DD HH:mm:ss`. Returns `'-'` for
+ * `null` / `undefined` so list cells render a consistent placeholder.
+ */
+export declare function formatDateTime(value: string | null | undefined): string;

package/dist/lib/format-member-label.d.cts

@@ -0,0 +1,12 @@
+/**
+ * How the e-mail is attached to the name: `ascii` is `name (email)`,
+ * `fullwidth` is `name（email）` and `dot` is `name · email`. Each call site
+ * keeps the separator it always had.
+ */
+export type MemberLabelStyle = 'ascii' | 'dot' | 'fullwidth';
+/**
+ * `name` followed by the e-mail in the given style. A host may resolve a member
+ * with `email: ''` (or a blank string), and then the label is just the name —
+ * never `name ()` or `name · `.
+ */
+export declare function formatMemberLabel(name: string, email: string | null | undefined, style?: MemberLabelStyle): string;

package/dist/lib/member-profile-resolution.d.cts

@@ -0,0 +1,48 @@
+import { MemberProfileRecord } from '@rytass/bpm-core-client/template';
+/** Most ids asked for on their own after a failed batch, per round. */
+export declare const MAX_PER_ID_REQUESTS = 20;
+/** Most per-id requests in flight at once. */
+export declare const PER_ID_CONCURRENCY = 4;
+export type MemberProfileResolution = Readonly<{
+    /** Ids whose lookup failed even when asked for on their own. */
+    failedIds: readonly string[];
+    profiles: readonly MemberProfileRecord[];
+    /**
+     * Ids left unasked because a failed batch held more than the per-id budget.
+     * They were not tried, so a later round may ask for them again.
+     */
+    skippedIds: readonly string[];
+}>;
+export type MemberProfileResolutionLimits = Readonly<{
+    concurrency?: number;
+    maxPerIdRequests?: number;
+}>;
+/**
+ * Looks up member profiles in one batch, and degrades per id when the batch
+ * request fails.
+ *
+ * The host fails a whole lookup when it contains an id it cannot handle (a
+ * foreign id stored in a template, say). Treating that as "nobody resolved"
+ * labels every approver of the template 「未知會員」 for the sake of one bad
+ * id, so a failed batch is retried one id at a time and only the ids that fail
+ * on their own are reported back in `failedIds`.
+ *
+ * The retry is bounded: at most `maxPerIdRequests` ids are asked for on their
+ * own (the rest come back in `skippedIds` without a request), and at most
+ * `concurrency` of those requests run at once, so one bad id in a large
+ * template cannot turn into a burst of requests.
+ *
+ * A single-id batch is not retried: it already is the per-id request.
+ */
+export declare function resolveMemberProfilesPerIdOnFailure(memberIds: readonly string[], resolveMembers: (memberIds: readonly string[]) => Promise<readonly MemberProfileRecord[]>, limits?: MemberProfileResolutionLimits): Promise<MemberProfileResolution>;
+/**
+ * The ids still worth asking the directory for: those that already failed on
+ * their own in this session are left out, so they stay 「未知會員」 instead of
+ * being re-requested every time the option list changes.
+ *
+ * A failed id stays 「未知會員」 for the rest of the session, even when the
+ * failure was transient (a network blip, say), unless a later member search
+ * returns it and replaces the placeholder. Ids skipped over the per-id cap
+ * were never asked and must not be added to `failedMemberIds`.
+ */
+export declare function excludeFailedMemberIds(memberIds: readonly string[], failedMemberIds: ReadonlySet<string>): readonly string[];

package/dist/lib/notification-drawer-provider.d.cts

@@ -0,0 +1,27 @@
+import { ReactElement, ReactNode } from 'react';
+interface NotificationDrawerContextValue {
+    readonly close: () => void;
+    readonly isOpen: boolean;
+    readonly open: () => void;
+    readonly toggle: () => void;
+}
+interface NotificationDrawerProviderProps {
+    readonly children: ReactNode;
+}
+/**
+ * Controls the open/closed state of the BPM notification drawer. Wraps
+ * children with a context that `<NotificationDrawer />` reads to mount /
+ * hide itself, and that the host navigation reads (via
+ * `<BPMNotificationBellButton />` or `useNotificationDrawer().open`) to
+ * open the drawer when the bell icon is clicked.
+ *
+ * When used outside this provider, the returned hook is a safe no-op so
+ * components don't crash in test or storybook environments.
+ */
+export declare function NotificationDrawerProvider({ children, }: NotificationDrawerProviderProps): ReactElement;
+/**
+ * Read the BPM notification drawer's open state and control helpers.
+ * Returns a no-op stub when used outside `<NotificationDrawerProvider>`.
+ */
+export declare function useNotificationDrawer(): NotificationDrawerContextValue;
+export {};

package/dist/lib/notification-unread-provider.d.cts

@@ -0,0 +1,25 @@
+import { ReactElement, ReactNode } from 'react';
+interface NotificationUnreadContextValue {
+    readonly refreshUnreadCount: () => Promise<number>;
+    readonly unreadCount: number;
+}
+interface NotificationUnreadProviderProps {
+    readonly children: ReactNode;
+}
+/**
+ * Polls BPM for the current member's unread notification count via
+ * `readUnreadNotificationCount` and exposes it through context for the
+ * host navigation (`<BPMNotificationBellButton />` badge or any custom
+ * trigger using `useNotificationUnread().unreadCount`) and the BPM
+ * `<NotificationDrawer />` (header count). Refresh is triggered on
+ * mount and whenever the auth member id changes; consumers can call
+ * `refreshUnreadCount()` after acknowledging a notification.
+ */
+export declare function NotificationUnreadProvider({ children, }: NotificationUnreadProviderProps): ReactElement;
+/**
+ * Read the current unread-notification count and a manual refresh helper.
+ * Returns a zero/no-op stub when used outside
+ * `<NotificationUnreadProvider>`.
+ */
+export declare function useNotificationUnread(): NotificationUnreadContextValue;
+export {};

package/dist/lib/org-tree-draft.d.cts

@@ -0,0 +1,27 @@
+import { OrgUnitRecord } from '@rytass/bpm-core-client/organization';
+export type OrgUnitParentDraftMap = ReadonlyMap<string, string | null>;
+export type OrgUnitHierarchyDraftChange = Readonly<{
+    orgUnitId: string;
+    parentId: string | null;
+    previousParentId: string | null;
+}>;
+export type OrgUnitParentAssignmentResult = Readonly<{
+    message: string;
+    parentDraft: OrgUnitParentDraftMap;
+    status: 'INVALID' | 'UNCHANGED' | 'UPDATED';
+}>;
+export declare function createOrgUnitParentDraftMap(orgUnits: readonly OrgUnitRecord[]): OrgUnitParentDraftMap;
+export declare function assignOrgUnitDraftParent({ orgUnitId, parentDraft, parentId, }: {
+    readonly orgUnitId: string;
+    readonly parentDraft: OrgUnitParentDraftMap;
+    readonly parentId: string | null;
+}): OrgUnitParentAssignmentResult;
+export declare function readOrgUnitHierarchyDraftChanges({ orgUnits, parentDraft, }: {
+    readonly orgUnits: readonly OrgUnitRecord[];
+    readonly parentDraft: OrgUnitParentDraftMap;
+}): readonly OrgUnitHierarchyDraftChange[];
+export declare function readOrgUnitParentValidationMessage({ orgUnitId, parentDraft, parentId, }: {
+    readonly orgUnitId: string;
+    readonly parentDraft: OrgUnitParentDraftMap;
+    readonly parentId: string | null;
+}): string | null;

package/dist/lib/providers.d.cts

@@ -0,0 +1,31 @@
+import { ReactElement, ReactNode } from 'react';
+import { CalendarLocale } from '@mezzanine-ui/react/moment';
+interface ProvidersProps {
+    readonly children: ReactNode;
+    /** Override Mezzanine calendar locale. Defaults to `CalendarLocale.ZH_TW`. */
+    readonly locale?: CalendarLocale;
+    /**
+     * Public paths that should not trigger redirect to `/login` when there
+     * is no session. Forwarded to `<AuthProvider>`. Defaults to `['/login']`.
+     */
+    readonly publicPaths?: readonly string[];
+    /** Where to send unauthenticated users. Defaults to `'/login'`. */
+    readonly loginPath?: string;
+}
+/**
+ * One-stop BPM admin provider stack. Wires:
+ *
+ * - Mezzanine UI calendar locale (moment-based, `ZH_TW` by default)
+ * - `<AuthProvider>` (BPM session via REST `/auth/*`)
+ * - `<NotificationUnreadProvider>` (polls unread count)
+ * - `<NotificationDrawerProvider>` (controls drawer open/close state)
+ * - `<NotificationDrawer />` mounted at the root so the host navigation
+ *   bell (`<BPMNotificationBellButton />` or any custom trigger calling
+ *   `useNotificationDrawer().open`) can open it.
+ *
+ * Consumer hosts wrap this **inside** a `<RouterAdapterProvider>` (provided
+ * by the `pages/*` subpath shims when consuming via Next.js, or wired by
+ * hand for other frameworks).
+ */
+export declare function Providers({ children, locale, publicPaths, loginPath, }: ProvidersProps): ReactElement;
+export {};

package/dist/lib/router-adapter.d.cts

@@ -0,0 +1,47 @@
+import { ReactElement, ReactNode } from 'react';
+/**
+ * Framework-agnostic router contract every BPM view consumes.
+ *
+ * Next.js App Router consumers wire it from `useRouter()` / `usePathname()`,
+ * but the contract is intentionally generic so SPA / Remix / Tanstack Router
+ * hosts can plug in the same `<RouterAdapterProvider>` with their own
+ * navigation primitives.
+ */
+export interface RouterAdapter {
+    /** Current pathname (e.g. "/inbox"). `null` during SSR before hydration. */
+    readonly pathname: string | null;
+    /** Navigate to `href` (push onto history). */
+    push(href: string): void;
+    /** Navigate to `href` and replace the current history entry. */
+    replace(href: string): void;
+    /** Optional: go back. Falls back to `history.back()` when omitted. */
+    back?(): void;
+    /**
+     * Optional search params accessor. Returned `URLSearchParams` should be
+     * read-only — mutating it does not navigate. Default implementation reads
+     * `window.location.search` on the client.
+     */
+    searchParams?(): URLSearchParams;
+}
+export interface RouterAdapterProviderProps {
+    readonly value: RouterAdapter;
+    readonly children: ReactNode;
+}
+/**
+ * Wraps the BPM React tree so `useRouterAdapter()` resolves to the host's
+ * navigation primitives. Consumers typically put this once at the very root
+ * of their layout (or inside a `'use client'` shim that reads
+ * `useRouter()` + `usePathname()` from `next/navigation`).
+ */
+export declare function RouterAdapterProvider({ value, children, }: RouterAdapterProviderProps): ReactElement;
+/**
+ * Reads the host-provided {@link RouterAdapter}. Throws when used outside a
+ * `<RouterAdapterProvider>` to surface wiring mistakes early.
+ */
+export declare function useRouterAdapter(): RouterAdapter;
+/**
+ * Pure default search-params reader for the browser. Server-side returns an
+ * empty `URLSearchParams`. Used internally when a {@link RouterAdapter}
+ * does not override `searchParams()`.
+ */
+export declare function defaultBrowserSearchParams(): URLSearchParams;

package/dist/lib/routes-config.d.cts

@@ -0,0 +1,117 @@
+import { ReactElement, ReactNode } from 'react';
+/**
+ * Framework-agnostic path mapping every BPM view uses for internal
+ * cross-navigation. When a host embeds BPM under a non-root prefix
+ * (e.g. `/workspace/bpm/*`) it provides its own implementation through
+ * `<BPMRoutesProvider value={...}>`; otherwise the default factory
+ * preserves the historical `/instances/:id`, `/templates`, etc. paths.
+ *
+ * Function-shape (instead of string templates) means:
+ * - Optional and multi-param routes can branch on argument presence
+ *   (`caseNew(templateId?)`).
+ * - Query-string composition stays inside the host's resolver, not the
+ *   view.
+ * - TypeScript flags missing arguments at compile time.
+ *
+ * Mirror sibling: {@link RouterAdapter} owns *navigation primitives*
+ * (`push`, `replace`, `pathname`); `BPMRoutes` owns *path strings*. The
+ * two compose: views call `router.push(routes.caseDetail(id))`.
+ */
+export interface BPMRoutes {
+    /** Workflow dashboard landing. Used by sidebar + dashboard tiles. */
+    dashboard(): string;
+    /** Inbox (待簽) — pending tasks assigned to the current member. */
+    inbox(): string;
+    /** Sent (我發起的) — instances the current member initiated or submitted on someone's behalf. */
+    sent(): string;
+    /** CC (抄送給我) — instances the current member is copied on. */
+    cc(): string;
+    /** Cross-view search. */
+    search(): string;
+    /** Personal delegation rules. */
+    delegations(): string;
+    /**
+     * Reserved for hosts that want a dedicated `/notifications` page —
+     * BPM's built-in views do **not** navigate here by default (the
+     * notification drawer mounted by `<BPMNextProviders>` is the primary
+     * unread-notification UX). The `createDefaultBPMRoutes()` factory
+     * returns `'/notifications'` so consumers can mount their own page
+     * at that path if desired; no BPM-shipped `pages/notifications`
+     * shim exists.
+     */
+    notifications(): string;
+    /**
+     * Detail page for one approval instance.
+     *
+     * @example default → `/instances/abc123`
+     */
+    caseDetail(instanceId: string): string;
+    /**
+     * Launch a new approval instance. When `templateId` is passed, the
+     * launch form is pre-populated for that template — by default this is
+     * appended as a `?templateId=` query string so the path itself stays
+     * stable for routing.
+     *
+     * @example default `caseNew()` → `/instances/new`
+     * @example default `caseNew('tpl-1')` → `/instances/new?templateId=tpl-1`
+     */
+    caseNew(templateId?: string): string;
+    /** Template index. */
+    templates(): string;
+    /**
+     * Unified "form + flow" creation wizard. Designs a form and an approval
+     * flow together, then publishes both atomically. This is the only place
+     * forms are designed — there is no separate standalone form builder page.
+     */
+    templateCompose(): string;
+    /** Template designer (xyflow canvas). */
+    templateDesigner(templateId: string): string;
+    /** Template version history. */
+    templateVersions(templateId: string): string;
+    /** Template categories admin. */
+    templateCategories(): string;
+    /** Per-member notification preferences. */
+    notificationSettings(): string;
+    /** Admin: organization tree management. */
+    adminOrgs(): string;
+    /** Admin: member directory mapping. */
+    adminUsers(): string;
+    /** Admin: delegation rule management. */
+    adminDelegations(): string;
+    /** Admin: database-managed notify webhook endpoints (ADR 18). */
+    adminWebhookEndpoints(): string;
+}
+/**
+ * Factory for the default `BPMRoutes` value. Reproduces the exact path
+ * literals BPM views used before `BPMRoutesContext` existed, so existing
+ * hosts (no provider mounted) keep working unchanged.
+ */
+export declare function createDefaultBPMRoutes(): BPMRoutes;
+export interface BPMRoutesProviderProps {
+    /**
+     * Override the path mapping. Provide a full implementation, or spread
+     * the default and override individual entries:
+     *
+     * ```tsx
+     * <BPMRoutesProvider value={{
+     *   ...createDefaultBPMRoutes(),
+     *   caseDetail: (id) => `/workspace/cases/${id}`,
+     * }}>
+     * ```
+     */
+    readonly value?: BPMRoutes;
+    readonly children: ReactNode;
+}
+/**
+ * Wraps the BPM React tree with a {@link BPMRoutes} value. Mounting the
+ * provider is **optional** — `useBPMRoutes()` falls back to
+ * {@link createDefaultBPMRoutes} when no provider is present. Use it
+ * only when the host needs to remap BPM's internal paths.
+ */
+export declare function BPMRoutesProvider({ value, children, }: BPMRoutesProviderProps): ReactElement;
+/**
+ * Reads the host-configured {@link BPMRoutes}. Falls back to
+ * {@link createDefaultBPMRoutes} when no `<BPMRoutesProvider>` ancestor
+ * is mounted, so views remain self-contained.
+ */
+export declare function useBPMRoutes(): BPMRoutes;