@suilend/sui-fe-next 3.0.9 → 3.1.0

package/README.md

@@ -1,8 +1,113 @@
-# sui-fe-next
+# @suilend/sui-fe-next
 
-A collection of TypeScript frontend components and hooks.
+The React/Next layer shared by the Suilend-ecosystem frontends
+(`springsui-web`, `steamm-web`, `suilend-web`). Built on
+[`@suilend/sui-fe`](../sui-fe), which holds the non-React utilities.
 
-## Get started
+Providers (both are composed in each app's `_app.tsx`, in this order):
 
-1. Install `bun` [https://bun.sh/](https://bun.sh/)
-2. Run `bun i`
+- **`SettingsContextProvider`** / `useSettingsContext()` — RPC, explorer and
+  gas-budget settings, persisted to `localStorage`, plus the memoized
+  `suiJsonRpcClient` / `suiGrpcClient` / `suiGraphQLClient`.
+- **`WalletContextProvider({ appName })`** / `useWalletContext()` — wraps
+  `@mysten/dapp-kit-react`'s `DAppKitProvider`; wallet discovery/connect,
+  impersonation, WalletConnect (Reown) sessions, and
+  `signExecuteAndWaitForTransaction`.
+
+Also exported: `useFetchBalances`, `useCoinMetadataMap`,
+`useRefreshOnBalancesChange`, `useLedgerHashDialog`, `useLastSignedTransaction`,
+the `useIsAndroid`/`useIsiOS`/`useIsTouchscreen` platform hooks, the
+`shallowPushQuery`/`shallowReplaceQuery` router helpers, Sonner-based toasts, and
+Mixpanel tracking.
+
+There are no rendered UI components here — dialogs and layout live in the apps.
+
+## Working in here
+
+This is a workspace package in the `perpetual-ui` Yarn 4 monorepo — install from
+the repo root (`yarn install`), not from this directory.
+
+```sh
+yarn workspace @suilend/sui-fe-next typecheck   # tsgo --noEmit
+yarn workspace @suilend/sui-fe-next lint:ci     # eslint (repo-wide config, no local overrides)
+yarn workspace @suilend/sui-fe-next build       # tsc -> ./dist (publish artifact only)
+```
+
+The three apps depend on this package as `"@suilend/sui-fe-next": "workspace:^"`
+and list it in Next's `transpilePackages`, so **they compile this TypeScript
+source directly** — a change here reaches the apps with no build and no publish
+step. `dist/` exists only to be published; nothing in this repo consumes it.
+
+Formatting and lint come from the repo root (`.prettierrc`,
+`@bluefin/eslint-config/base`). There are no package-local overrides — don't add
+one without a reason.
+
+Two things to know before editing:
+
+- **`react`/`react-dom` are peer dependencies pinned at 19.2.3**, matching the
+  monorepo's root `resolutions`. Never add them as dependencies.
+- **`tsconfig` uses `jsx: preserve`**, so the build emits `.jsx` for `.tsx`
+  sources and consumers transpile them. That's why this package cannot extend
+  `@bluefin/typescript-config/react-library.json` (which sets `jsx: react-jsx`),
+  and why every consuming app must keep it in `transpilePackages`.
+
+## Releasing
+
+Published by `.github/workflows/sui_fe_next_publish.yaml` using npm **OIDC Trusted Publishing** —
+no npm token is stored or rotated.
+
+> Note: npm does **not** generate provenance attestations for packages published
+> from a private repository, so these releases are unsigned despite using OIDC.
+> Trusted Publishing still replaces the token; only the attestation is missing.
+
+To release:
+
+1. Bump `version` in `package.json` and merge.
+2. Push the matching tag:
+
+   ```sh
+   git tag release-sui-fe-next-v<version> && git push origin release-sui-fe-next-v<version>
+   ```
+
+   Use `release-sui-fe-next-prerelease-<version>` to publish under the `next` dist-tag.
+
+### Two phases, one approval
+
+The tag push runs a **`stage`** job immediately — everything reversible:
+
+- guards that the tag version matches `package.json` and isn't already on npm
+  (so a bad tag fails fast instead of burning an approval);
+- builds, prepares the publish manifest, and `npm pack`s the tarball;
+- cuts the GitHub Release as a **prerelease**, with the tarball attached and
+  notes listing only the commits that touched `packages/sui-fe-next` since the previous
+  `release-sui-fe-next-v*` tag. (The repo-wide "Release Trade" notes cover every commit
+  in the monorepo and aren't useful to a consumer of this package.)
+
+The **`publish`** job then waits on the **`sui-prod`** environment's
+`bluefin-internal` reviewers — the same gate as the app deploys. On approval it
+rebuilds, asserts the tarball's sha256 still matches the reviewed artifact
+(`npm pack` is byte-reproducible, so a mismatch means something changed and the
+publish is refused), publishes to npm, and promotes the Release out of
+prerelease.
+
+So the reviewer approves with the notes and the exact artifact in front of them,
+and the only gated step is the irreversible one. Releases stay `--latest=false`
+so the "Latest" badge remains on the trade release.
+
+If approval is declined, the prerelease Release remains as a record of what was
+staged — delete it if you don't want it.
+
+**One-time setup:** on npmjs.com → @suilend/sui-fe-next → *Settings → Trusted Publisher →
+GitHub Actions*, with organization `fireflyprotocol`, repository `perpetual-ui`,
+workflow `sui_fe_next_publish.yaml`.
+
+The published manifest is generated by
+[`scripts/prepare-npm-dist.mjs`](../../scripts/prepare-npm-dist.mjs), which
+rewrites the source-facing entry points (`./src/**/*.ts(x)`) to dist-relative
+ones, flips `private`, and resolves this package's `@suilend/sui-fe`
+`workspace:^` range to a real `^<version>`. That step is required because the npm
+CLI ignores `publishConfig` overrides for `main`/`types`/`exports` — see the
+script header.
+
+Publishing only matters for **external** consumers; in-repo consumers always use
+the workspace copy.

package/contexts/SettingsContext.d.ts

@@ -4,6 +4,7 @@ import { SuiGrpcClient } from "@mysten/sui/grpc";
 import { SuiJsonRpcClient } from "@mysten/sui/jsonRpc";
 import { Explorer, ExplorerId, Rpc, RpcId } from "@suilend/sui-fe";
 interface SettingsContext {
+    rpcs: Rpc[];
     rpc: Rpc;
     setRpcId: (id: RpcId) => void;
     setRpcUrl: (url: string) => void;
@@ -17,5 +18,11 @@ interface SettingsContext {
 }
 declare const SettingsContext: import("react").Context<SettingsContext>;
 export declare const useSettingsContext: () => SettingsContext;
-export declare function SettingsContextProvider({ children }: PropsWithChildren): import("react").JSX.Element;
+export type SettingsContextProviderProps = PropsWithChildren<{
+    /** RPCs to offer, in display order. Defaults to `RPCS`. Pass a stable reference. */
+    rpcs?: Rpc[];
+    /** Selected when nothing is persisted, or the persisted id isn't in `rpcs`. Defaults to `rpcs[0]`. */
+    defaultRpcId?: RpcId;
+}>;
+export declare function SettingsContextProvider({ children, rpcs: rpcsProp, defaultRpcId, }: SettingsContextProviderProps): import("react").JSX.Element;
 export {};

package/contexts/SettingsContext.jsx

@@ -1,34 +1,24 @@
-var __assign = (this && this.__assign) || function () {
-    __assign = Object.assign || function(t) {
-        for (var s, i = 1, n = arguments.length; i < n; i++) {
-            s = arguments[i];
-            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
-                t[p] = s[p];
-        }
-        return t;
-    };
-    return __assign.apply(this, arguments);
-};
-import { createContext, useContext, useMemo } from "react";
+import { createContext, useContext, useEffect, useMemo } from "react";
 import { SuiGraphQLClient } from "@mysten/sui/graphql";
 import { SuiGrpcClient } from "@mysten/sui/grpc";
 import { SuiJsonRpcClient } from "@mysten/sui/jsonRpc";
 import { useLocalStorage } from "usehooks-ts";
 import { EXPLORERS, RPCS, RPC_GRAPHQL_URL, RpcId, } from "@suilend/sui-fe";
-var defaultContextValue = {
+const defaultContextValue = {
+    rpcs: RPCS,
     rpc: RPCS[0],
-    setRpcId: function () {
+    setRpcId: () => {
         throw Error("SettingsContextProvider not initialized");
     },
-    setRpcUrl: function () {
+    setRpcUrl: () => {
         throw Error("SettingsContextProvider not initialized");
     },
     explorer: EXPLORERS[0],
-    setExplorerId: function () {
+    setExplorerId: () => {
         throw Error("SettingsContextProvider not initialized");
     },
     gasBudget: "",
-    setGasBudget: function () {
+    setGasBudget: () => {
         throw Error("SettingsContextProvider not initialized");
     },
     suiJsonRpcClient: new SuiJsonRpcClient({
@@ -44,43 +34,57 @@ var defaultContextValue = {
         network: "mainnet",
     }),
 };
-var SettingsContext = createContext(defaultContextValue);
-export var useSettingsContext = function () { return useContext(SettingsContext); };
-export function SettingsContextProvider(_a) {
-    var children = _a.children;
+const SettingsContext = createContext(defaultContextValue);
+export const useSettingsContext = () => useContext(SettingsContext);
+export function SettingsContextProvider({ children, rpcs: rpcsProp, defaultRpcId, }) {
     // RPC
-    var _b = useLocalStorage("rpcId", defaultContextValue.rpc.id), rpcId = _b[0], setRpcId = _b[1];
-    var _c = useLocalStorage("rpcUrl", ""), rpcUrl = _c[0], setRpcUrl = _c[1];
-    var rpc = useMemo(function () {
-        var _a;
-        return rpcId === RpcId.CUSTOM
-            ? __assign(__assign({}, RPCS.find(function (_rpc) { return _rpc.id === RpcId.CUSTOM; })), { url: rpcUrl }) : ((_a = RPCS.find(function (_rpc) { return _rpc.id === rpcId; })) !== null && _a !== void 0 ? _a : RPCS[0]);
-    }, [rpcId, rpcUrl]);
+    const rpcs = useMemo(() => {
+        const result = rpcsProp ?? RPCS;
+        if (result.length === 0)
+            throw new Error("SettingsContextProvider: `rpcs` must not be empty");
+        return result;
+    }, [rpcsProp]);
+    const fallbackRpc = useMemo(() => rpcs.find((_rpc) => _rpc.id === defaultRpcId) ?? rpcs[0], [rpcs, defaultRpcId]);
+    const [rpcId, setRpcId] = useLocalStorage("rpcId", fallbackRpc.id);
+    const [rpcUrl, setRpcUrl] = useLocalStorage("rpcUrl", "");
+    const isRpcIdOffered = rpcs.some((_rpc) => _rpc.id === rpcId);
+    useEffect(() => {
+        if (!isRpcIdOffered)
+            setRpcId(fallbackRpc.id);
+    }, [isRpcIdOffered, fallbackRpc.id, setRpcId]);
+    const rpc = useMemo(() => {
+        if (!isRpcIdOffered)
+            return fallbackRpc;
+        if (rpcId === RpcId.CUSTOM) {
+            const customRpc = rpcs.find((_rpc) => _rpc.id === RpcId.CUSTOM);
+            return customRpc ? { ...customRpc, url: rpcUrl } : fallbackRpc;
+        }
+        return rpcs.find((_rpc) => _rpc.id === rpcId) ?? fallbackRpc;
+    }, [isRpcIdOffered, fallbackRpc, rpcId, rpcUrl, rpcs]);
     // Explorer
-    var _d = useLocalStorage("explorerId", defaultContextValue.explorer.id), explorerId = _d[0], setExplorerId = _d[1];
-    var explorer = useMemo(function () {
-        var _a;
-        return (_a = EXPLORERS.find(function (_explorer) { return _explorer.id === explorerId; })) !== null && _a !== void 0 ? _a : EXPLORERS[0];
-    }, [explorerId]);
+    const [explorerId, setExplorerId] = useLocalStorage("explorerId", defaultContextValue.explorer.id);
+    const explorer = useMemo(() => EXPLORERS.find((_explorer) => _explorer.id === explorerId) ?? EXPLORERS[0], [explorerId]);
     // Gas budget
-    var _e = useLocalStorage("gasBudget", defaultContextValue.gasBudget), gasBudget = _e[0], setGasBudget = _e[1];
+    const [gasBudget, setGasBudget] = useLocalStorage("gasBudget", defaultContextValue.gasBudget);
     // Sui clients
-    var suiJsonRpcClient = useMemo(function () { return new SuiJsonRpcClient({ url: rpc.url, network: "mainnet" }); }, [rpc.url]);
-    var suiGrpcClient = useMemo(function () { return new SuiGrpcClient({ baseUrl: rpc.url, network: "mainnet" }); }, [rpc.url]);
-    var suiGraphQLClient = useMemo(function () { return new SuiGraphQLClient({ url: RPC_GRAPHQL_URL, network: "mainnet" }); }, []);
+    const suiJsonRpcClient = useMemo(() => new SuiJsonRpcClient({ url: rpc.url, network: "mainnet" }), [rpc.url]);
+    const suiGrpcClient = useMemo(() => new SuiGrpcClient({ baseUrl: rpc.url, network: "mainnet" }), [rpc.url]);
+    const suiGraphQLClient = useMemo(() => new SuiGraphQLClient({ url: RPC_GRAPHQL_URL, network: "mainnet" }), []);
     // Context
-    var contextValue = useMemo(function () { return ({
-        rpc: rpc,
-        setRpcId: setRpcId,
-        setRpcUrl: setRpcUrl,
-        explorer: explorer,
-        setExplorerId: setExplorerId,
-        gasBudget: gasBudget,
-        setGasBudget: setGasBudget,
-        suiJsonRpcClient: suiJsonRpcClient,
-        suiGrpcClient: suiGrpcClient,
-        suiGraphQLClient: suiGraphQLClient,
-    }); }, [
+    const contextValue = useMemo(() => ({
+        rpcs,
+        rpc,
+        setRpcId,
+        setRpcUrl,
+        explorer,
+        setExplorerId,
+        gasBudget,
+        setGasBudget,
+        suiJsonRpcClient,
+        suiGrpcClient,
+        suiGraphQLClient,
+    }), [
+        rpcs,
         rpc,
         setRpcId,
         setRpcUrl,
@@ -93,6 +97,6 @@ export function SettingsContextProvider(_a) {
         suiGraphQLClient,
     ]);
     return (<SettingsContext.Provider value={contextValue}>
-      {children}
-    </SettingsContext.Provider>);
+			{children}
+		</SettingsContext.Provider>);
 }

package/contexts/WalletContext.d.ts

@@ -70,5 +70,5 @@ export declare const useWalletContext: () => WalletContext;
 interface WalletContextProviderProps extends PropsWithChildren {
     appName: string;
 }
-export declare function WalletContextProvider({ appName, children, }: WalletContextProviderProps): import("react").JSX.Element;
+export declare function WalletContextProvider({ appName, children }: WalletContextProviderProps): import("react").JSX.Element;
 export {};