@microsoft/rayfin-app-state-fabric 1.35.0-alpha.1412

package/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) Microsoft Corporation.
+
+MIT License
+
+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,140 @@
+# @microsoft/rayfin-app-state-fabric
+
+Deep-link application state for Rayfin apps embedded in the Fabric portal.
+
+## Getting started
+
+```bash
+npm install @microsoft/rayfin-app-state-fabric
+```
+
+For more details, [visit our docs](https://aka.ms/rayfin/docs).
+
+## Deep linking
+
+A Fabric App runs in an iframe and cannot touch the portal address bar directly.
+`createFabricAppStateClient()` lets your app read the state it was launched with and write state back, so a user can share a link that reopens the exact view they were looking at.
+
+Read launch state *before* your first render so default state never flashes:
+
+```ts
+import { createFabricAppStateClient } from '@microsoft/rayfin-app-state-fabric';
+
+const appState = createFabricAppStateClient({
+  targetOrigin: 'https://app.fabric.microsoft.com',
+});
+
+const launch = appState.getLaunchStateSync();
+renderApp(launch ?? defaultView);
+```
+
+Write state as the user navigates.
+Use `setState` for navigation the user would expect the Back button to undo, and `replaceState` for transient changes such as dragging a slider:
+
+```ts
+await appState.setState({ view: 'sales-by-region', filter: 'AT' });
+await appState.replaceState({ view: 'sales-by-region', filter: 'AT', zoom: 3 });
+```
+
+React to the Back and Forward buttons.
+The listener receives `undefined` when the user reaches a URL that carries no state, which means you should restore your defaults:
+
+```ts
+const unsubscribe = appState.onStateChange((state) => {
+  restore(state ?? defaultView);
+});
+
+// On teardown
+unsubscribe();
+appState.dispose();
+```
+
+Deep linking rolls out per tenant, so check support before showing a share button:
+
+```ts
+const capabilities = await appState.isSupported();
+if (capabilities) {
+  showShareButton();
+  // Some hosts can update the URL but not add history entries.
+  if (!capabilities.canPush) hideBackForwardHints();
+}
+```
+
+### Running outside the portal
+
+The same app often ships standalone as well as embedded, where it owns its own address bar and there is no host to talk to.
+The client is safe to construct either way: nothing throws at construction, and it never rewrites a URL it does not own.
+
+`isSupported()` is the single branch point.
+It resolves to `undefined` when the app is not embedded, so the check that guards a share button also selects your standalone path:
+
+```ts
+const capabilities = await appState.isSupported();
+
+if (capabilities) {
+  // Embedded in Fabric: the portal owns the address bar.
+  await appState.setState({ view: 'sales', region: 'AT' });
+} else {
+  // Standalone: the app owns its own URL, so use your router.
+  router.push({ path: '/sales', query: { region: 'AT' } });
+}
+```
+
+What each call does when the app is not embedded:
+
+| Call | Standalone result |
+| --- | --- |
+| `isSupported()` | `undefined` |
+| `getLaunchStateSync()` | seeded state when the URL carries it, otherwise `undefined` |
+| `getLaunchState()` | the same, and never rejects |
+| `setState()` / `replaceState()` | rejects with `NO_HOST_WINDOW` |
+| `onStateChange()` | the listener registers but never fires |
+
+Writes reject rather than silently doing nothing, so a missing branch shows up in development instead of quietly dropping state.
+Branch on `isSupported()`, or catch `NO_HOST_WINDOW` if you would rather attempt the write.
+
+### Rules and limits
+
+- State must be a plain JSON object.
+  `Date`, `Map`, `Set`, class instances, functions, and `undefined` are rejected rather than silently degraded.
+- State is capped at 4 KiB encoded and 20 levels deep so links survive proxies, mail gateways, and chat clients.
+  For anything larger, store it yourself and put an identifier in the state.
+- The whole object is replaced on every write.
+  There is no partial or namespaced update, so an app with several independent pieces of state must merge them itself before writing.
+- Your app owns the shape of its state.
+  The encoding is versioned, but the payload is not, so a link shared before a shape change will still arrive in the old shape and your app must tolerate it.
+- Errors are `FabricAppStateError` with a stable `code`.
+  Branch on the code, not the message.
+
+### Security
+
+State travels in a URL, so treat it accordingly.
+
+- **It is visible to the user.** It appears in the address bar, browser history, and bookmarks.
+  Never put secrets, tokens, or personal data in it.
+- **It is untrusted input.** Anyone can edit a link before sending it, so validate launch state exactly as you would a query parameter before using it to drive queries.
+  Your app should also tolerate state written by a different version of itself.
+
+## Security
+
+Microsoft takes the security of our software products and services seriously, which
+includes all source code repositories in our GitHub organizations.
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+For security reporting information, locations, contact information, and policies,
+please review the latest guidance for Microsoft repositories at
+[https://aka.ms/SECURITY.md](https://aka.ms/SECURITY.md).
+
+## Trademarks
+
+This project may contain trademarks or logos for projects, products, or services.
+Authorized use of Microsoft trademarks or logos must follow the [Microsoft Trademark and Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+Any use of third-party trademarks or logos is subject to those third parties' policies.
+
+## License
+
+Copyright (c) Microsoft Corporation.
+
+MIT License

package/assets/docs/index.md

@@ -0,0 +1,211 @@
+# Fabric deep-link app state
+
+Shareable, bookmarkable URLs for Rayfin applications embedded in the Fabric portal.
+
+A Fabric App runs inside an iframe and cannot touch the portal address bar directly.
+`@microsoft/rayfin-app-state-fabric` bridges that gap: your app can read the state it was launched with and write state back, so a user can copy the browser URL and send someone the exact view they were looking at.
+
+The package builds on the message bridge in `@microsoft/fabric-embedded-host`, which handles the underlying `postMessage` transport.
+
+## Installation
+
+```bash
+npm install @microsoft/rayfin-app-state-fabric
+```
+
+## Quick start
+
+Create one client for the lifetime of the app and read the launch state before your first render, so a default view never flashes before the real one appears.
+
+```typescript
+import { createFabricAppStateClient } from '@microsoft/rayfin-app-state-fabric';
+
+const appState = createFabricAppStateClient({
+  targetOrigin: 'https://app.fabric.microsoft.com',
+});
+
+const launch = appState.getLaunchStateSync();
+renderApp(launch ?? defaultView);
+```
+
+`targetOrigin` is strongly recommended.
+When it is omitted, messages are posted with `"*"` and inbound events are not origin-checked.
+
+## Reading launch state
+
+Two readers are available, and which one you want depends on whether your code path can be asynchronous.
+
+`getLaunchStateSync()` returns the seeded state without awaiting, which is what you want on the first render path.
+It returns `undefined` when the host did not seed the URL.
+
+`getLaunchState()` resolves synchronously from the seeded URL when the host supports it, and falls back to a bridge round trip only on hosts that do not seed.
+Awaiting it does not delay first paint on a modern host.
+
+```typescript
+const launch = await appState.getLaunchState();
+```
+
+Both return `undefined` when the URL carries no state, which is the normal case for a fresh navigation.
+
+## Writing state
+
+Choose between the two writers by asking **who caused the change**.
+
+Use `setState()` when the *user* caused it, such as a click, a filter change, or opening a record.
+It creates a history entry, so Back returns the user to where they were.
+
+```typescript
+// The user picked a region: Back should undo it.
+await appState.setState({ view: 'sales', region: 'AT' });
+```
+
+Use `replaceState()` when the *app* caused it, such as restoring, reconciling, or normalising state the user never asked for.
+Also use it for high-frequency updates like a slider drag, where one history entry per update would make Back unusable.
+
+```typescript
+// Continuous updates while dragging: do not grow history.
+await appState.replaceState({ view: 'sales', threshold: value });
+```
+
+The whole object is replaced on every write.
+There is no partial or namespaced update, so an app with several independent pieces of state must merge them itself before writing.
+
+### Platform caveat
+
+The Fabric host downgrades a replace to a push when the previous history entry belongs to a different extension, which stops one extension from overwriting another's history.
+The first `replaceState()` after a user arrives from elsewhere in Fabric may therefore still create an entry.
+This is platform behaviour and cannot be overridden.
+
+## Reacting to Back and Forward
+
+Subscribe to observe changes the app did not initiate: browser Back or Forward, or a deep link opened in the current tab.
+
+The listener receives `undefined` when navigation reaches a URL that carries no state, which means the app should restore its own defaults.
+
+```typescript
+const unsubscribe = appState.onStateChange((state) => {
+  restore(state ?? defaultView);
+});
+
+// On teardown
+unsubscribe();
+appState.dispose();
+```
+
+## Checking host support
+
+Deep linking rolls out per tenant, so check support before showing a share button rather than letting a user click one that cannot work.
+The result is cached.
+
+```typescript
+const capabilities = await appState.isSupported();
+
+if (capabilities) {
+  showShareButton();
+
+  // Some hosts can update the URL but not add history entries.
+  if (!capabilities.canPush) {
+    hideBackForwardHints();
+  }
+}
+```
+
+`isSupported()` resolves to `undefined` when the host does not implement deep-link state.
+Otherwise it reports the host's `version`, `maxEncodedBytes`, `maxDepth`, and `canPush`.
+
+The host is authoritative.
+The client's own limits exist only to fail fast before a round trip, so treat the reported values as the real contract.
+
+## Running outside the portal
+
+Many apps ship standalone as well as embedded.
+Standalone, the app owns its own address bar and there is no host to talk to, so deep-link state is unavailable by design.
+
+The client is safe to construct either way.
+Nothing throws at construction, and it never rewrites a URL it does not own — the launch parameter is only scrubbed when the app is actually embedded.
+
+`isSupported()` is the single branch point.
+It resolves to `undefined` when the app is not embedded, so the same check that guards a share button also selects your standalone path.
+
+```typescript
+const capabilities = await appState.isSupported();
+
+if (capabilities) {
+  // Embedded in Fabric: the portal owns the address bar.
+  await appState.setState({ view: 'sales', region: 'AT' });
+} else {
+  // Standalone: the app owns its own URL, so use your router.
+  router.push({ path: '/sales', query: { region: 'AT' } });
+}
+```
+
+What each call does when the app is not embedded:
+
+| Call | Standalone result |
+| --- | --- |
+| `isSupported()` | `undefined` |
+| `getLaunchStateSync()` | seeded state when the URL carries it, otherwise `undefined` |
+| `getLaunchState()` | the same, and never rejects |
+| `setState()` / `replaceState()` | rejects with `NO_HOST_WINDOW` |
+| `onStateChange()` | the listener registers but never fires |
+
+Reads degrade quietly so startup code needs no branching, but writes reject rather than silently doing nothing.
+A missing branch therefore surfaces during development instead of dropping state without a trace.
+Branch on `isSupported()`, or catch `NO_HOST_WINDOW` if you would rather attempt the write and handle the failure.
+
+## Limits and rules
+
+- State must be a plain JSON object.
+  `Date`, `Map`, `Set`, class instances, functions, and `undefined` are rejected rather than silently degraded.
+- State is capped at 4 KiB encoded and 20 levels deep, so links survive proxies, mail gateways, and chat clients.
+  For anything larger, store it yourself and put an identifier in the state.
+- Your app owns the shape of its state.
+  The encoding is versioned, but the payload is not, so a link shared before a shape change will still arrive in the old shape and your app must tolerate it.
+
+## Error handling
+
+Failures throw `FabricAppStateError` with a stable `code`.
+Branch on the code, never on the message.
+State values are never included in the code or the message, so these errors are safe to log.
+
+| Code | Meaning |
+| --- | --- |
+| `INVALID_STATE` | State is not JSON-serialisable |
+| `STATE_TOO_LARGE` | State exceeds the encoded-size budget |
+| `STATE_TOO_DEEP` | State exceeds the nesting-depth limit |
+| `UNSUPPORTED_HOST_CAPABILITY` | Host does not implement deep-link state |
+| `NO_HOST_WINDOW` | App is not running embedded in the Fabric portal |
+| `BRIDGE_TIMEOUT` | Host did not respond in time |
+
+```typescript
+import { FabricAppStateError } from '@microsoft/rayfin-app-state-fabric';
+
+try {
+  await appState.setState(nextState);
+} catch (error) {
+  if (error instanceof FabricAppStateError) {
+    if (error.code === 'STATE_TOO_LARGE') {
+      // Fall back to storing the state server-side.
+    }
+  }
+}
+```
+
+A host that predates this feature, or has the feature switch turned off, surfaces as `UNSUPPORTED_HOST_CAPABILITY` so the app can degrade gracefully instead of treating it as a bug.
+
+## Security
+
+State travels in a URL, so treat it accordingly.
+
+**It is visible to the user.** It appears in the address bar, browser history, bookmarks, screenshots, copied links, and corporate proxy logs.
+Never put secrets, access tokens, or personal data in it.
+When the state is sensitive, use an opaque identifier that maps to server-side data.
+
+**It is untrusted input.** Anyone can edit a link before sending it, so validate launch state exactly as you would validate a query parameter before using it to drive queries.
+Your app should also tolerate state written by a different version of itself.
+
+## Browser requirements
+
+This package is intended for browser environments running embedded in the Fabric portal.
+
+It depends on browser APIs such as `postMessage`, `window.parent`, and `window.location`.

package/dist/errors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Error type and transport-error mapping for the app state client.
+ */
+import { SdkError } from '@microsoft/rayfin-lib';
+/**
+ * Error thrown for invalid state or a host that cannot service the
+ * request.
+ *
+ * The `code` is stable and safe to branch on; the `message` is not.
+ * State values are never included in either, so the error can be logged
+ * without leaking user data.
+ *
+ * Codes currently emitted:
+ *
+ * | Code | Meaning |
+ * | --- | --- |
+ * | `INVALID_STATE` | State is not JSON-serialisable |
+ * | `STATE_TOO_LARGE` | State exceeds the encoded-size budget |
+ * | `STATE_TOO_DEEP` | State exceeds the nesting-depth limit |
+ * | `UNSUPPORTED_HOST_CAPABILITY` | Host does not implement deep-link state |
+ * | `NO_HOST_WINDOW` | App is not running embedded in the Fabric portal |
+ * | `BRIDGE_TIMEOUT` | Host did not respond in time |
+ */
+export declare class FabricAppStateError extends SdkError {
+    name: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Translate transport errors into a stable app-state vocabulary.
+ *
+ * A host that predates this feature, or has the feature switch off,
+ * replies `UNKNOWN_CHANNEL`.  Surfacing that as
+ * `UNSUPPORTED_HOST_CAPABILITY` lets an app degrade gracefully instead
+ * of treating it as a bug.
+ *
+ * @internal
+ */
+export declare function toAppStateError(err: unknown): FabricAppStateError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,54 @@
+/**
+ * Error type and transport-error mapping for the app state client.
+ */
+import { BridgeError } from '@microsoft/fabric-embedded-host';
+import { SdkError } from '@microsoft/rayfin-lib';
+/**
+ * Error thrown for invalid state or a host that cannot service the
+ * request.
+ *
+ * The `code` is stable and safe to branch on; the `message` is not.
+ * State values are never included in either, so the error can be logged
+ * without leaking user data.
+ *
+ * Codes currently emitted:
+ *
+ * | Code | Meaning |
+ * | --- | --- |
+ * | `INVALID_STATE` | State is not JSON-serialisable |
+ * | `STATE_TOO_LARGE` | State exceeds the encoded-size budget |
+ * | `STATE_TOO_DEEP` | State exceeds the nesting-depth limit |
+ * | `UNSUPPORTED_HOST_CAPABILITY` | Host does not implement deep-link state |
+ * | `NO_HOST_WINDOW` | App is not running embedded in the Fabric portal |
+ * | `BRIDGE_TIMEOUT` | Host did not respond in time |
+ */
+export class FabricAppStateError extends SdkError {
+    name = 'FabricAppStateError';
+    constructor(message, code) {
+        super(message, code);
+        Object.setPrototypeOf(this, FabricAppStateError.prototype);
+    }
+}
+/**
+ * Translate transport errors into a stable app-state vocabulary.
+ *
+ * A host that predates this feature, or has the feature switch off,
+ * replies `UNKNOWN_CHANNEL`.  Surfacing that as
+ * `UNSUPPORTED_HOST_CAPABILITY` lets an app degrade gracefully instead
+ * of treating it as a bug.
+ *
+ * @internal
+ */
+export function toAppStateError(err) {
+    if (err instanceof FabricAppStateError)
+        return err;
+    if (err instanceof BridgeError) {
+        if (err.code === 'UNKNOWN_CHANNEL') {
+            return new FabricAppStateError('This Fabric host does not support deep-link state. The app should ' +
+                'continue without it.', 'UNSUPPORTED_HOST_CAPABILITY');
+        }
+        return new FabricAppStateError(err.message, err.code ?? 'BRIDGE_ERROR');
+    }
+    return new FabricAppStateError(err instanceof Error ? err.message : 'Unknown app-state error.', 'UNKNOWN_ERROR');
+}
+//# sourceMappingURL=errors.js.map

package/dist/fabricAppState.d.ts

@@ -0,0 +1,32 @@
+/**
+ * fabricAppState — deep-linking client for Rayfin apps embedded in Fabric.
+ *
+ * An embedded app cannot touch the portal address bar, so it hands the host
+ * an opaque JSON object and the host owns the URL. That indirection is what
+ * lets the encoding change without a breaking SDK release.
+ *
+ * @example
+ * ```ts
+ * const appState = createFabricAppStateClient();
+ *
+ * // Restore before first render so defaults never flash.
+ * restoreApplicationState(appState.getLaunchStateSync());
+ *
+ * // User-initiated: Back should undo it.
+ * await appState.setState({ view: 'sales-by-region', filter: 'AT' });
+ *
+ * // App-initiated: do not grow history.
+ * await appState.replaceState({ view: 'sales-by-region', filter: 'DE' });
+ *
+ * const unsubscribe = appState.onStateChange(restoreApplicationState);
+ * ```
+ */
+import type { FabricAppStateClient, FabricAppStateClientOptions } from './types.js';
+/**
+ * Create a {@link FabricAppStateClient} bound to the Fabric host.
+ *
+ * Safe to call once per application; create a single instance and share
+ * it rather than constructing one per component.
+ */
+export declare function createFabricAppStateClient(options?: FabricAppStateClientOptions): FabricAppStateClient;
+//# sourceMappingURL=fabricAppState.d.ts.map