kaafil-react-uikit 0.1.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to `kaafil-react-uikit`.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this package uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+While on `0.x` a minor bump may carry a breaking change; the entry will say so.
+
+## [0.1.0-beta.1] — 2026-09-10
+
+First published release. Beta: stable enough to build against, not yet
+frozen. Pin an exact version.
+
+### Added
+
+- **Six subpath exports** — `/core`, `/manager`, `/admin`, `/traveller`,
+  `/styles`, `/testing`. No bare `.` export.
+- **`/core`** — `KaafilUIKitProvider`, nine shells, 53 hooks, the error
+  classifier, a type-keyed registry factory, and an opt-in deep-link module
+  (param names, the closing-day blocker table, and pure query-string
+  serializers). The only place in the package that imports `kaafil-js`.
+- **`/manager`** — the field family. `KaafilManagerApp`, `ManagerShell`,
+  `ManagerFab`, and 20 composites covering Now, the trip tab set, manifest,
+  roster, itinerary, pickups, rooming, vehicles, vendors, checklists, forms,
+  money, float, close-out, documents, traveller profile, notifications, the
+  sync centre and the manager's own profile.
+- **`/admin`** — the desk family. `KaafilAgencyWorkspace`, `AdminShell`, and
+  27 composites and flows: the trip workspace and its fifteen panels, plus
+  the agency-wide traveller and manager directories, the checklist-template
+  and form authoring libraries, journey triggers and agency settings.
+- **`/traveller`** — `KaafilShareView`, one surface driven entirely by the
+  share snapshot's own returned sections.
+- **Six system screens** — session expired, not found, locked trip, plan
+  locked, offline fallback and boot error. Authored once and re-exported per
+  family, each family taking only the screens that make sense for it.
+- **`/styles`** — the compiled token ladder. Opt-in; never auto-injected.
+  Everything lands in `@layer kaafil-ui`, with `@layer kaafil-ui-overrides`
+  reserved for the host.
+- **`/testing`** — plain-data fixture builders for sessions, capability
+  states, sync events and a fake offline engine. Zero test-framework
+  dependency.
+- **Per-instance theming** — every exported component accepts a `style` prop
+  typed to carry only `--kf-*` custom properties.
+- **English and Hindi** chrome catalogs, shipped in the bundle.
+- **Storybook documentation** — twelve pages, from getting started through
+  the hook catalog, offline and sync, deep links and a component index.
+
+### Requires
+
+- `kaafil-js@^0.1.0-beta.7`. Earlier betas lack the `trip_document` file
+  purpose and the `agencyAdmin` grants the desk family reads through, so the
+  Bookings, Forms, Documents and Payments panels fail against them before a
+  request is even built.
+- `react` and `react-dom` `>=18.2.0 <20.0.0`.
+
+### Known gaps
+
+Named here so they are not mistaken for defects. Each has a reason:
+
+- **No trek board.** `useTreks()` is built and the routes are open; the UI
+  is not. The `treks` tab is dropped from the rail rather than shown empty.
+- **No feedback/NPS panel.** `useFeedbackNps()` is built; the panel is not.
+- **No form answer-distribution dashboard.** Its backing read is
+  `apiKey`-only, so no browser session can reach it.
+- **No vendor rating.** The entitlement flag exists; the engine has no
+  rating model behind it.
+- **`AdminShell` collapses to an icon rail**, not a drawer, below `60rem` of
+  its own container.
+
+[0.1.0-beta.1]: https://github.com/kaafil/kaafil-react-uikit/releases/tag/v0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaafil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# kaafil-react-uikit
+
+React components for the Kaafil v2 engine, built on the headless
+[`kaafil-js`](https://www.npmjs.com/package/kaafil-js) SDK — designed to be
+dropped into a partner CRM **under that CRM's own brand**.
+
+Three persona families ship as one package: **manager** (field, on a phone,
+offline-assumed), **admin** (desk, embedded in your own page), and
+**traveller** (a public share link). Behind all three sits one hook layer,
+so capability gating, offline writes, idempotency, delta sync, conflict
+handling and money/date correctness are implemented exactly once and
+inherited by everything you mount — including your own components.
+
+> **Beta.** The API is stable enough to build against and not yet frozen.
+> Pin an exact version.
+
+## Install
+
+```sh
+npm install kaafil-react-uikit@beta kaafil-js@beta
+```
+
+`react`, `react-dom` and `kaafil-js` are peer dependencies:
+
+| Peer | Range |
+|---|---|
+| `react` / `react-dom` | `>=18.2.0 <20.0.0` |
+| `kaafil-js` | `^0.1.0-beta.7` |
+
+## Quick start
+
+Mint your tokens however your own backend already authenticates a user —
+your API key never reaches the browser — then hand them to the provider as
+**values**. There is no endpoint for the UIKit to call.
+
+```tsx
+import { KaafilUIKitProvider } from 'kaafil-react-uikit/core';
+import { KaafilAgencyWorkspace } from 'kaafil-react-uikit/admin';
+import 'kaafil-react-uikit/styles';
+
+export function DeskApp() {
+  return (
+    <KaafilUIKitProvider
+      accessToken={accessToken}
+      refreshToken={refreshToken}
+      agencyRef={agencyRef}
+      onSessionExpired={(kind) => redirectToLogin(kind)}
+    >
+      <KaafilAgencyWorkspace />
+    </KaafilUIKitProvider>
+  );
+}
+```
+
+The field surface additionally needs a storage adapter, so the outbox
+survives a reload:
+
+```tsx
+import { createIndexedDbStorageAdapter } from 'kaafil-js/client';
+import { KaafilManagerApp } from 'kaafil-react-uikit/manager';
+
+<KaafilUIKitProvider
+  accessToken={accessToken}
+  refreshToken={refreshToken}
+  agencyRef={agencyRef}
+  storage={createIndexedDbStorageAdapter()}
+  onSessionExpired={(kind) => redirectToLogin(kind)}
+>
+  <KaafilManagerApp
+    onNavigateModule={(key) => router.push(`/trip/${key}`)}
+    onLogExpense={() => router.push('/expenses/new')}
+    onCollectPayment={() => router.push('/collections/new')}
+    onCollectFromGroup={(id) => router.push(`/collections/new?group=${id}`)}
+    onVendorSelect={(id) => router.push(`/vendors/${id}`)}
+  />
+</KaafilUIKitProvider>
+```
+
+Passing `shareToken` instead of the token trio opens a traveller session —
+the provider derives the persona from the shape you pass, at the type
+level, so passing both is a compile error rather than a runtime ambiguity.
+
+## Subpath exports
+
+There is no bare `.` export. Import the one family your product needs, plus
+`/core`, and opt in to `/styles` once.
+
+| Subpath | Contains |
+|---|---|
+| `kaafil-react-uikit/core` | Hooks, the provider, the shells, the error classifier, the deep-link helpers. The only place in the package that imports `kaafil-js`. |
+| `kaafil-react-uikit/manager` | The field family — 20 composites plus `KaafilManagerApp`, `ManagerShell`, `ManagerFab`. |
+| `kaafil-react-uikit/admin` | The desk family — 27 composites and flows plus `KaafilAgencyWorkspace` and `AdminShell`. |
+| `kaafil-react-uikit/traveller` | The public family — `KaafilShareView`. |
+| `kaafil-react-uikit/styles` | The compiled CSS. **Opt-in**; never auto-injected. |
+| `kaafil-react-uikit/testing` | Plain-data fixture builders. Zero test-framework dependency. |
+
+## Two things to know before you start
+
+**The stylesheet is opt-in.** `import 'kaafil-react-uikit/styles'` once,
+where you want it in your cascade. Nothing is injected on your behalf,
+because you own the `@layer` order — everything we ship lives in
+`@layer kaafil-ui`, and your overrides belong in `@layer kaafil-ui-overrides`.
+
+**Sections can be legitimately absent.** Not every agency has every module,
+and some modules cannot exist for some trip shapes. Components gate on that
+before rendering rather than throwing, and the three reasons get three
+different treatments — a section that can never apply renders nothing, one
+missing its data says which ingest to connect, one outside the plan says so.
+Don't collapse them into a generic "unavailable".
+
+## Customising
+
+Seven tiers, shallow to deep in *mechanism*. Most integrations never leave
+the first three.
+
+| Tier | You get |
+|---|---|
+| 0 | Mount a whole persona's product in one component. |
+| 1–2 | Behaviour props and `on*` callbacks. Navigation is always a callback — the UIKit ships no router. |
+| 3 | Inject the SDK's own filter/sort params. No parallel filter language. |
+| 4 | `components={{ Name: YourComponent }}` — replace a named part, keep every guarantee. |
+| 5 | Mount the feature composites yourself, in your own layout. |
+| 6 | `/core` hooks — own every pixel, keep the outbox. |
+
+CSS is not a rung; it is an independent axis at every tier. Class names
+(`.kf-*`) and custom properties (`--kf-*`) are a **published API**:
+unhashed, BEM, and stable. Twelve semantic tokens are enough for a full
+reskin.
+
+```css
+:root {
+  --kf-accent: var(--brand-accent);
+  --kf-surface-base: var(--brand-surface);
+  --kf-text-primary: var(--brand-ink);
+  /* …nine more */
+}
+```
+
+Per-instance overrides go through a typed `style` prop that accepts only
+`--kf-*` keys, so a stray `color: red` is a compile error.
+
+## Building your own UI
+
+Every hook is exported. They return data, mutations and state — never JSX —
+and everything the components rely on comes with them.
+
+```tsx
+import { useRooming } from 'kaafil-react-uikit/core';
+
+function MyBoard({ tripRef }) {
+  const rooming = useRooming(tripRef);
+
+  if (rooming.status === 'loading') return <MySpinner />;
+  if (rooming.status === 'dark') return <MyLocked reason={rooming.reason} />;
+  if (rooming.status === 'error') return <MyError error={rooming.error} />;
+
+  // `ready` means the hook finished — not that the read succeeded.
+  if (rooming.syncedAt === undefined) return <MyCouldNotLoad />;
+
+  return <MyBedGrid rooms={rooming.rooms} onAssign={rooming.assign} />;
+}
+```
+
+That `syncedAt` check is the one thing worth memorising: a failed live read
+still resolves `ready` with an empty array, so `syncedAt === undefined` is
+what separates "there is nothing here" from "we could not read it".
+
+## Documentation
+
+Full docs ship as Storybook — twelve pages covering tokens, the
+customization ladder, the layer model, capability behaviour, per-instance
+theming, the hook catalog, offline and sync, deep links, system screens,
+i18n and RTL, and an index of every component with the states it renders.
+
+```sh
+git clone https://github.com/kaafil/kaafil-react-uikit
+cd kaafil-react-uikit && pnpm install && pnpm storybook
+```
+
+## Requirements
+
+Node `>=20.11` for the toolchain. The package itself ships ESM and CJS
+builds with type declarations for both, targeting ES2022.
+
+## License
+
+MIT © Kaafil

package/dist/OfflineFallbackScreen-B5dfaJBN.d.ts

@@ -0,0 +1,37 @@
+import { ReactNode } from 'react';
+import { K as KaafilTokenOverrides } from './tokenStyle-CToG5oOS.js';
+
+/** The same failure modes `<KaafilSessionProbe/>` distinguishes, plus the
+ * honest sixth for anything unclassifiable. */
+type BootFailureMode = 'endpoint-401' | 'wrong-environment' | 'test-key-on-live' | 'clock-skew' | 'cors' | 'unknown';
+interface BootErrorScreenProps {
+    readonly failureMode?: BootFailureMode;
+    /** The underlying error's message. Rendered behind a disclosure, never
+     * inline in the primary copy — it is developer-facing. */
+    readonly detail?: string;
+    /** Remounts the entire provider tree; some boot failures (a `kf_test_`
+     * key shipped to production) cannot be fixed by retrying at all, which
+     * is why this is optional. */
+    readonly onRetry?: () => void;
+    readonly components?: {
+        readonly BootErrorScreenUI?: () => ReactNode;
+    };
+}
+declare function BootErrorScreen({ failureMode, detail, onRetry, components, }: BootErrorScreenProps): ReactNode;
+
+interface OfflineFallbackScreenProps {
+    /** Present on a trip-scoped mount; absent on the share surface. Context
+     * only — this screen fetches nothing. */
+    readonly tripRef?: string;
+    /** Present on a share mount instead of `tripRef`. */
+    readonly token?: string;
+    /** The host's own retry — typically remounting whatever failed. */
+    readonly onRetry?: () => void;
+    readonly components?: {
+        readonly OfflineFallbackScreenUI?: () => ReactNode;
+    };
+    readonly style?: KaafilTokenOverrides;
+}
+declare function OfflineFallbackScreen({ onRetry, components, style, }: OfflineFallbackScreenProps): ReactNode;
+
+export { BootErrorScreen as B, OfflineFallbackScreen as O, type BootErrorScreenProps as a, type BootFailureMode as b, type OfflineFallbackScreenProps as c };

package/dist/OfflineFallbackScreen-Ctm7nBa-.d.cts

@@ -0,0 +1,37 @@
+import { ReactNode } from 'react';
+import { K as KaafilTokenOverrides } from './tokenStyle-CToG5oOS.cjs';
+
+/** The same failure modes `<KaafilSessionProbe/>` distinguishes, plus the
+ * honest sixth for anything unclassifiable. */
+type BootFailureMode = 'endpoint-401' | 'wrong-environment' | 'test-key-on-live' | 'clock-skew' | 'cors' | 'unknown';
+interface BootErrorScreenProps {
+    readonly failureMode?: BootFailureMode;
+    /** The underlying error's message. Rendered behind a disclosure, never
+     * inline in the primary copy — it is developer-facing. */
+    readonly detail?: string;
+    /** Remounts the entire provider tree; some boot failures (a `kf_test_`
+     * key shipped to production) cannot be fixed by retrying at all, which
+     * is why this is optional. */
+    readonly onRetry?: () => void;
+    readonly components?: {
+        readonly BootErrorScreenUI?: () => ReactNode;
+    };
+}
+declare function BootErrorScreen({ failureMode, detail, onRetry, components, }: BootErrorScreenProps): ReactNode;
+
+interface OfflineFallbackScreenProps {
+    /** Present on a trip-scoped mount; absent on the share surface. Context
+     * only — this screen fetches nothing. */
+    readonly tripRef?: string;
+    /** Present on a share mount instead of `tripRef`. */
+    readonly token?: string;
+    /** The host's own retry — typically remounting whatever failed. */
+    readonly onRetry?: () => void;
+    readonly components?: {
+        readonly OfflineFallbackScreenUI?: () => ReactNode;
+    };
+    readonly style?: KaafilTokenOverrides;
+}
+declare function OfflineFallbackScreen({ onRetry, components, style, }: OfflineFallbackScreenProps): ReactNode;
+
+export { BootErrorScreen as B, OfflineFallbackScreen as O, type BootErrorScreenProps as a, type BootFailureMode as b, type OfflineFallbackScreenProps as c };

package/dist/SessionExpiredScreen-CytQNuak.d.cts

@@ -0,0 +1,50 @@
+import { ReactNode } from 'react';
+import { K as KaafilTokenOverrides } from './tokenStyle-CToG5oOS.cjs';
+
+interface LockedTripScreenProps {
+    /** For context and for building the link's destination — never used to
+     * fetch anything. */
+    readonly tripRef: string;
+    /** What the dead-end link would have done ("Record a collection"), from
+     * whatever metadata came with it. Absent means the generic sentence: this
+     * screen invents no explanation of its own. */
+    readonly intendedAction?: string;
+    /** The host's own navigation to wherever it mounts Closing Day. A screen
+     * never navigates itself. */
+    readonly onGoToClosingDay: (tripRef: string) => void;
+    readonly components?: {
+        readonly LockedTripScreenUI?: () => ReactNode;
+    };
+    readonly style?: KaafilTokenOverrides;
+}
+declare function LockedTripScreen({ tripRef, intendedAction, onGoToClosingDay, components, style, }: LockedTripScreenProps): ReactNode;
+
+interface NotFoundScreenProps {
+    /** The host's own "back" navigation. Optional — a host that reached this
+     * with no history to return to simply gets no button, which is more
+     * honest than one that goes nowhere. */
+    readonly onGoBack?: () => void;
+    readonly components?: {
+        readonly NotFoundScreenUI?: () => ReactNode;
+    };
+    readonly style?: KaafilTokenOverrides;
+}
+declare function NotFoundScreen({ onGoBack, components, style }: NotFoundScreenProps): ReactNode;
+
+interface SessionExpiredScreenProps {
+    /** The host's own re-auth entry point. Required: there is no default
+     * action, because Kaafil has no login page of its own. */
+    readonly onReauthenticate: (returnTo?: string) => void | Promise<void>;
+    /** Threaded back to `onReauthenticate` UNEXAMINED. This screen never
+     * interprets it, builds a URL from it, or hands it to a router — it
+     * exists purely so the host's own flow can restore the right destination
+     * afterwards. */
+    readonly returnTo?: string;
+    readonly components?: {
+        readonly SessionExpiredScreenUI?: () => ReactNode;
+    };
+    readonly style?: KaafilTokenOverrides;
+}
+declare function SessionExpiredScreen({ onReauthenticate, returnTo, components, style, }: SessionExpiredScreenProps): ReactNode;
+
+export { LockedTripScreen as L, NotFoundScreen as N, SessionExpiredScreen as S, type LockedTripScreenProps as a, type NotFoundScreenProps as b, type SessionExpiredScreenProps as c };

package/dist/SessionExpiredScreen-D8GHyZc3.d.ts

@@ -0,0 +1,50 @@
+import { ReactNode } from 'react';
+import { K as KaafilTokenOverrides } from './tokenStyle-CToG5oOS.js';
+
+interface LockedTripScreenProps {
+    /** For context and for building the link's destination — never used to
+     * fetch anything. */
+    readonly tripRef: string;
+    /** What the dead-end link would have done ("Record a collection"), from
+     * whatever metadata came with it. Absent means the generic sentence: this
+     * screen invents no explanation of its own. */
+    readonly intendedAction?: string;
+    /** The host's own navigation to wherever it mounts Closing Day. A screen
+     * never navigates itself. */
+    readonly onGoToClosingDay: (tripRef: string) => void;
+    readonly components?: {
+        readonly LockedTripScreenUI?: () => ReactNode;
+    };
+    readonly style?: KaafilTokenOverrides;
+}
+declare function LockedTripScreen({ tripRef, intendedAction, onGoToClosingDay, components, style, }: LockedTripScreenProps): ReactNode;
+
+interface NotFoundScreenProps {
+    /** The host's own "back" navigation. Optional — a host that reached this
+     * with no history to return to simply gets no button, which is more
+     * honest than one that goes nowhere. */
+    readonly onGoBack?: () => void;
+    readonly components?: {
+        readonly NotFoundScreenUI?: () => ReactNode;
+    };
+    readonly style?: KaafilTokenOverrides;
+}
+declare function NotFoundScreen({ onGoBack, components, style }: NotFoundScreenProps): ReactNode;
+
+interface SessionExpiredScreenProps {
+    /** The host's own re-auth entry point. Required: there is no default
+     * action, because Kaafil has no login page of its own. */
+    readonly onReauthenticate: (returnTo?: string) => void | Promise<void>;
+    /** Threaded back to `onReauthenticate` UNEXAMINED. This screen never
+     * interprets it, builds a URL from it, or hands it to a router — it
+     * exists purely so the host's own flow can restore the right destination
+     * afterwards. */
+    readonly returnTo?: string;
+    readonly components?: {
+        readonly SessionExpiredScreenUI?: () => ReactNode;
+    };
+    readonly style?: KaafilTokenOverrides;
+}
+declare function SessionExpiredScreen({ onReauthenticate, returnTo, components, style, }: SessionExpiredScreenProps): ReactNode;
+
+export { LockedTripScreen as L, NotFoundScreen as N, SessionExpiredScreen as S, type LockedTripScreenProps as a, type NotFoundScreenProps as b, type SessionExpiredScreenProps as c };