@roughapp/feature 0.2.0 → 0.3.0

package/index.d.ts

@@ -307,35 +307,167 @@ type Sprite = {
     publishedSpriteBuildId: SpriteBuildId | null;
 };
 
-type SurfaceDefinition = {
-    key: string;
+/**
+ * An immutable, project-independent surface contract.
+ *
+ * A definition holds no client, project id, server surface id, registration
+ * state, subscription, or lifecycle hook. That is what lets the same value be
+ * handed to two clients for two different projects at once: each resolves it
+ * against its own project and caches the canonical id privately.
+ */
+type RoughSurfaceDefinition<TKey extends string = string, TTools extends readonly AnyTool[] = readonly AnyTool[]> = Readonly<{
+    key: TKey;
     name: string;
     description: string;
-    toolList: readonly AnyTool[];
+    tools: TTools;
+}>;
+type DefineRoughSurfaceOptions<TKey extends string, TTools extends readonly AnyTool[]> = {
+    key: TKey;
+    name: string;
+    description: string;
+    tools: TTools;
 };
-declare const defineSurface: (config: SurfaceDefinition) => SurfaceDefinition;
-
-declare const getRoughFeatures: (surface: SurfaceDefinition, callback: (features: Sprite[]) => void) => (() => void);
+declare const defineRoughSurface: <const TKey extends string, const TTools extends readonly AnyTool[]>(options: DefineRoughSurfaceOptions<TKey, TTools>) => RoughSurfaceDefinition<TKey, TTools>;
 
 type FetchUserTokenFn = () => string | Promise<string>;
 
-type SurfaceEntry = {
-    surfaceId: SurfaceId;
-    toolList: readonly AnyTool[];
-};
-declare const registerSurfaceEntry: (key: string, entry: SurfaceEntry) => (() => void);
-
-type InitRoughOptions = {
-    baseUrl?: string;
+type RoughClientOptions = {
     projectId: string;
+    baseUrl?: string;
     fetchUserToken: FetchUserTokenFn;
 };
-declare const initRough: (options: InitRoughOptions) => void;
+/**
+ * A handle to one project's live Rough runtime.
+ *
+ * The client is an opaque capability: it exposes identity and lifecycle, not
+ * behavior. Behavior lives in the package's function exports, which take the
+ * client in their options.
+ */
+type RoughClient = {
+    readonly projectId: string;
+    destroy: () => Promise<void>;
+};
+/**
+ * Creates and immediately starts a client for one Rough project.
+ *
+ * Returns synchronously so a framework provider can own the value in the same
+ * tick it renders, and so a client whose auth or Replicache startup is still
+ * pending can still be destroyed. Startup runs in the background; observe it
+ * with `whenRoughClientReady({ client })` if you need to.
+ *
+ * The host owns the result until it calls `client.destroy()`. There is no
+ * release, restart, or reuse: a failed client is destroyed and replaced.
+ */
+declare const createRoughClient: (options: RoughClientOptions) => RoughClient;
+/**
+ * Awaits the client's eager startup.
+ *
+ * Rejects with the retained startup error if it failed. Operations do this
+ * internally, so hosts only need it when they want to show startup state or
+ * when a test needs a deterministic point to await.
+ */
+declare const whenRoughClientReady: (options: {
+    client: RoughClient;
+}) => Promise<void>;
+
+/**
+ * Errors that hosts are expected to branch on.
+ *
+ * These are exported from the package root so a host can distinguish "you used
+ * a client you already destroyed" (a programming error) from "another client
+ * already owns this local database" (a coordination error the host fixes by
+ * sharing one client).
+ */
+/** Thrown when an operation is started on a destroying or destroyed client. */
+declare class RoughClientDestroyedError extends Error {
+    readonly name = "RoughClientDestroyedError";
+    constructor(message?: string);
+}
+/**
+ * Thrown during startup when another live client in this JavaScript realm
+ * already owns the `<baseUrl, projectId, personId>` Replicache identity.
+ */
+declare class RoughReplicacheIdentityConflictError extends Error {
+    readonly name = "RoughReplicacheIdentityConflictError";
+    readonly replicacheName: string;
+    constructor(options: {
+        replicacheName: string;
+    });
+}
+/**
+ * Thrown when two concurrent operations disagree about the serialized contract
+ * of one surface key on the same client.
+ */
+declare class RoughSurfaceContractConflictError extends Error {
+    readonly name = "RoughSurfaceContractConflictError";
+    readonly surfaceKey: string;
+    constructor(options: {
+        surfaceKey: string;
+    });
+}
+/**
+ * Rejection value of `client.destroy()` when at least one cleanup stage failed.
+ *
+ * `destroy()` always attempts every stage, so this is reported only after all
+ * of them have settled. `errors` holds one entry per failed stage.
+ */
+declare class RoughClientDestroyError extends Error {
+    readonly name = "RoughClientDestroyError";
+    readonly errors: readonly Error[];
+    constructor(options: {
+        errors: readonly Error[];
+    });
+}
+/** Thrown when a value that is not a Rough client is passed as `client`. */
+declare class RoughInvalidClientError extends Error {
+    readonly name = "RoughInvalidClientError";
+    constructor(message?: string);
+}
+
+/**
+ * Every cleanup handle in the public API has this shape.
+ *
+ * It is a promise rather than `void` on purpose. Un-awaitable teardown is what
+ * lets Replicache closes, store watches, and mounted modals outlive the thing
+ * that owned them, which shows up as work still running during a test
+ * environment teardown long after the assertions passed. Calling a cleanup
+ * twice is always safe: the second call returns the first call's promise.
+ */
+type RoughCleanup = () => Promise<void>;
+
+type GetRoughFeaturesOptions = {
+    client: RoughClient;
+    surface: RoughSurfaceDefinition;
+    onFeatures: (features: Sprite[]) => void;
+    onError?: (error: Error) => void;
+    signal?: AbortSignal;
+};
+type RoughFeatureSubscription = {
+    /**
+     * Resolves after the first feature batch is published. Rejects if startup or
+     * surface resolution failed.
+     */
+    readonly ready: Promise<void>;
+    unsubscribe: RoughCleanup;
+};
+/** Subscribes to published features for a surface. */
+declare const getRoughFeatures: (options: GetRoughFeaturesOptions) => RoughFeatureSubscription;
 
 type OpenRoughCreateOptions = {
-    projectId?: string;
+    client: RoughClient;
+    surface: RoughSurfaceDefinition;
+    /** Portal target. Use when Rough theme variables are scoped below document.body. */
+    target?: HTMLElement;
+    signal?: AbortSignal;
 };
-declare const openRoughCreate: (surface: SurfaceDefinition, options?: OpenRoughCreateOptions) => void;
+type RoughModalHandle = {
+    close: RoughCleanup;
+};
+/**
+ * Opens the Feature Builder for a surface. Resolves the surface itself, so no
+ * `<RoughSurface>` need be mounted first.
+ */
+declare const openRoughCreate: (options: OpenRoughCreateOptions) => Promise<RoughModalHandle>;
 
 type Props$9 = {
     children?: Snippet;
@@ -377,18 +509,21 @@ declare const ResizeHandle: svelte.Component<Props$8, {}, "">;
 type ResizeHandle = ReturnType<typeof ResizeHandle>;
 
 type Props$7 = {
-    toolList: readonly AnyTool[];
+    client: RoughClient;
+    surface: RoughSurfaceDefinition;
     surfaceId: SurfaceId;
-    projectId?: string;
+    /** Portal target; use when Rough theme variables are scoped to a subtree. */
+    portalTarget?: HTMLElement;
     onclose?: () => void;
 };
 declare const RoughCreateModal: svelte.Component<Props$7, {}, "">;
 type RoughCreateModal = ReturnType<typeof RoughCreateModal>;
 
 type Props$6 = {
-    toolList: readonly AnyTool[];
+    client: RoughClient;
+    surface: RoughSurfaceDefinition;
+    spriteId: SpriteId;
     label?: string;
-    spriteId: string;
 };
 declare const RoughEditButton: svelte.Component<Props$6, {}, "">;
 type RoughEditButton = ReturnType<typeof RoughEditButton>;
@@ -407,16 +542,18 @@ type SpriteFrameDatastoreContext = {
 };
 
 type Props$5 = {
+    client: RoughClient;
+    surface: RoughSurfaceDefinition;
     featureId: SpriteId;
     buildId: SpriteBuildId;
-    surfaceKey: string;
     datastore?: SpriteFrameDatastore;
 };
 declare const RoughFeature: svelte.Component<Props$5, {}, "">;
 type RoughFeature = ReturnType<typeof RoughFeature>;
 
 type Props$4 = {
-    surface: SurfaceDefinition;
+    client: RoughClient;
+    surface: RoughSurfaceDefinition;
     getDatastore?: (context: SpriteFrameDatastoreContext) => SpriteFrameDatastore | undefined;
 };
 declare const RoughSurface: svelte.Component<Props$4, {}, "">;
@@ -440,16 +577,16 @@ declare const SecondaryButton: svelte.Component<Props$3, {}, "">;
 type SecondaryButton = ReturnType<typeof SecondaryButton>;
 
 type Props$2 = {
+    client: RoughClient;
     surfaceId: SurfaceId;
     onselect?: (sprite: Sprite, spriteBuild: SpriteBuild) => Promise<void> | void;
 };
 declare const SpriteBuildMenu: svelte.Component<Props$2, {}, "">;
 type SpriteBuildMenu = ReturnType<typeof SpriteBuildMenu>;
 
-type Props$1 = {
+type BaseProps = {
     spriteId: string;
     spriteBuildId: SpriteBuildId;
-    artifactUrl?: string;
     toolList: readonly AnyTool[];
     datastore?: SpriteFrameDatastore;
     isMock?: boolean;
@@ -457,12 +594,23 @@ type Props$1 = {
     minHeight?: number;
     maxHeight?: number;
 };
+/** A client is required unless artifactUrl is provided explicitly. */
+type Props$1 = BaseProps & ({
+    artifactUrl: string;
+    client?: undefined;
+} | {
+    artifactUrl?: undefined;
+    client: RoughClient;
+});
 declare const SpriteFrame: svelte.Component<Props$1, {}, "">;
 type SpriteFrame = ReturnType<typeof SpriteFrame>;
 
 type Props = {
-    toolList: readonly AnyTool[];
-    spriteId: string;
+    client: RoughClient;
+    surface: RoughSurfaceDefinition;
+    spriteId: SpriteId;
+    /** Where the dialog attaches. Decides which `--rough-*` values it inherits. */
+    portalTarget?: HTMLElement;
     onclose?: () => void;
 };
 declare const RoughEditModal: svelte.Component<Props, {}, "">;
@@ -494,5 +642,5 @@ declare global {
     }
 }
 
-export { Mutation, PrimaryButton, Query, ResizeHandle, RoughCreateModal, RoughEditButton, RoughFeature, RoughSurface, SecondaryButton, SpriteBuildMenu, SpriteFrame, Subscription, defineSurface, getRoughFeatures, initRough, openRoughCreate, registerSurfaceEntry };
-export type { JsonValue, RoughCreateModalElement, RoughEditButtonElement, RoughEditModalElement, RoughFeatureElement, RoughSurfaceElement, Sprite, SpriteBuild, SpriteFrameDatastore, SpriteFrameDatastoreContext, SurfaceDefinition };
+export { Mutation, PrimaryButton, Query, ResizeHandle, RoughClientDestroyError, RoughClientDestroyedError, RoughCreateModal, RoughEditButton, RoughFeature, RoughInvalidClientError, RoughReplicacheIdentityConflictError, RoughSurface, RoughSurfaceContractConflictError, SecondaryButton, SpriteBuildMenu, SpriteFrame, Subscription, createRoughClient, defineRoughSurface, getRoughFeatures, openRoughCreate, whenRoughClientReady };
+export type { FetchUserTokenFn, GetRoughFeaturesOptions, JsonValue, OpenRoughCreateOptions, RoughCleanup, RoughClient, RoughClientOptions, RoughCreateModalElement, RoughEditButtonElement, RoughEditModalElement, RoughFeatureElement, RoughFeatureSubscription, RoughModalHandle, RoughSurfaceDefinition, RoughSurfaceElement, Sprite, SpriteBuild, SpriteFrameDatastore, SpriteFrameDatastoreContext };