@roughapp/feature 0.4.1 → 0.5.0

package/README.md

@@ -10,7 +10,8 @@ declarations and a separate stylesheet.
 
 > **Pre-1.0:** minor releases may contain breaking changes. Pin
 > `@roughapp/feature` to an exact version if you want to control when you
-> upgrade. See the [changelog](./CHANGELOG.md) before updating.
+> upgrade. Review the hosted [Feature SDK changelog](https://rough.app/docs/changelog)
+> before updating.
 
 ## Before you start
 
@@ -130,7 +131,6 @@ export const roughClient = createRoughClient({
     const { token } = (await response.json()) as { token: string }
     return token
   },
-  // baseUrl is optional. Omit it when using the Rough production API.
 })
 ```
 
@@ -147,24 +147,45 @@ await whenRoughClientReady({ client: roughClient })
 A failed client is not restarted. Destroy it and create a new one after the
 underlying problem has been handled.
 
-### 3. Render the surface
+### 3. Subscribe and render feature frames
 
-Importing `@roughapp/feature` registers its custom elements. Set the `client`
-and `surface` properties on `<rough-surface>`; these are JavaScript values, not
+The SDK supplies published feature metadata; your app chooses where and how to
+render each frame. Subscribe with `getRoughFeatures()`, then render a
+`<rough-feature>` for every feature with a `publishedSpriteBuildId`. Its
+`client`, `surface`, `featureId`, and `buildId` are JavaScript properties, not
 HTML attributes.
 
 ```ts
 import '@roughapp/feature'
+import { getRoughFeatures } from '@roughapp/feature'
 
-const element = document.createElement('rough-surface')
-element.client = roughClient
-element.surface = inboxSurface
+const slot = document.querySelector('#rough-slot')
+const subscription = getRoughFeatures({
+  client: roughClient,
+  surface: inboxSurface,
+  onFeatures: (features) => {
+    slot?.replaceChildren(
+      ...features.flatMap((feature) => {
+        if (!feature.publishedSpriteBuildId) return []
+
+        const frame = document.createElement('rough-feature')
+        frame.client = roughClient
+        frame.surface = inboxSurface
+        frame.featureId = feature.id
+        frame.buildId = feature.publishedSpriteBuildId
+        return [frame]
+      }),
+    )
+  },
+  onError: (error) => console.error('Unable to load Rough Features', error),
+})
 
-document.querySelector('#rough-slot')?.append(element)
+// During route teardown:
+await subscription.unsubscribe()
 ```
 
-The package also exports `RoughSurface` for Svelte apps. As with the custom
-element, import and render it only on the client when the app uses SSR.
+`RoughFeature` is also exported for Svelte apps. Import and render it only on
+the client when the app uses SSR.
 
 ## Open the Feature Builder
 
@@ -191,8 +212,8 @@ The user can also close the modal from the UI. Calling `close()` again is safe.
 ## Subscribe to published features
 
 Use `getRoughFeatures()` when you need the feature list rather than the rendered
-`<rough-surface>`. The callback runs with the initial list, even when it is
-empty, and runs again as published features change.
+a rendered feature frame. The callback runs with the initial list, even when
+it is empty, and runs again as published features change.
 
 ```ts
 import { getRoughFeatures } from '@roughapp/feature'
@@ -271,12 +292,12 @@ inherits them.
 The recommended integration surface is:
 
 - `createRoughClient`, `whenRoughClientReady` and the `RoughClient`,
-  `RoughClientOptions` types;
+  `RoughClientOptions` types.
 - `defineRoughSurface` and the `RoughSurfaceDefinition` type;
 - `getRoughFeatures` and the `GetRoughFeaturesOptions`,
   `RoughFeatureSubscription` types;
 - `openRoughCreate` and the `OpenRoughCreateOptions`, `RoughModalHandle` types;
-- `RoughSurface` / `<rough-surface>`;
+- `RoughFeature` / `<rough-feature>` for rendering each published feature;
 - `Query`, `Mutation`, `Subscription`; and
 - `RoughClientDestroyedError`, `RoughReplicacheIdentityConflictError`,
   `RoughSurfaceContractConflictError`, `RoughClientDestroyError` and
@@ -286,9 +307,9 @@ The package also exports lower-level components and data types used to build its
 own UI. During the pre-1.0 series, do not treat these as a stable integration
 surface:
 
-- `RoughCreateModal` (`<rough-create-modal>`), `RoughEditButton`
-  (`<rough-edit-button>`) and `RoughFeature` (`<rough-feature>`). The
-  `<rough-edit-modal>` element is registered transitively.
+- `RoughCreateModal` (`<rough-create-modal>`) and `RoughEditButton`
+  (`<rough-edit-button>`). The `<rough-edit-modal>` element is registered
+  transitively.
 - `PrimaryButton`, `SecondaryButton`, `ResizeHandle`, `SpriteBuildMenu` and
   `SpriteFrame`.
 - `Sprite`, `SpriteBuild`, `JsonValue`, `RoughCleanup`, `FetchUserTokenFn`,

package/index.d.ts

@@ -343,6 +343,12 @@ type FetchUserTokenFn = () => string | Promise<string>;
 type RoughClientOptions = {
     projectId: string;
     baseUrl?: string;
+    /**
+     * Origin for uploaded media and Cloudflare image transformations. Defaults to
+     * Rough's production media server; set this when using a custom Gateway or
+     * media deployment.
+     */
+    mediaBaseUrl?: string;
     fetchUserToken: FetchUserTokenFn;
 };
 /**
@@ -474,11 +480,11 @@ type RoughModalHandle = {
 };
 /**
  * Opens the Feature Builder for a surface. Resolves the surface itself, so no
- * `<RoughSurface>` need be mounted first.
+ * feature frame need be mounted first.
  */
 declare const openRoughCreate: (options: OpenRoughCreateOptions) => Promise<RoughModalHandle>;
 
-type Props$9 = {
+type Props$8 = {
     children?: Snippet;
     class?: string;
     type?: 'button' | 'submit' | 'reset';
@@ -492,7 +498,7 @@ type Props$9 = {
     'aria-haspopup'?: boolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog';
     'aria-expanded'?: boolean;
 };
-declare const PrimaryButton: svelte.Component<Props$9, {}, "">;
+declare const PrimaryButton: svelte.Component<Props$8, {}, "">;
 type PrimaryButton = ReturnType<typeof PrimaryButton>;
 
 type ResizableHandle = {
@@ -509,15 +515,15 @@ type ResizableHandle = {
     destroy: (node: HTMLElement) => void;
 };
 
-type Props$8 = {
+type Props$7 = {
     handle: ResizableHandle;
     children?: Snippet;
     class?: string;
 };
-declare const ResizeHandle: svelte.Component<Props$8, {}, "">;
+declare const ResizeHandle: svelte.Component<Props$7, {}, "">;
 type ResizeHandle = ReturnType<typeof ResizeHandle>;
 
-type Props$7 = {
+type Props$6 = {
     client: RoughClient;
     surface: RoughSurfaceDefinition;
     surfaceId: SurfaceId;
@@ -525,16 +531,16 @@ type Props$7 = {
     portalTarget?: HTMLElement;
     onclose?: () => void;
 };
-declare const RoughCreateModal: svelte.Component<Props$7, {}, "">;
+declare const RoughCreateModal: svelte.Component<Props$6, {}, "">;
 type RoughCreateModal = ReturnType<typeof RoughCreateModal>;
 
-type Props$6 = {
+type Props$5 = {
     client: RoughClient;
     surface: RoughSurfaceDefinition;
     spriteId: SpriteId;
     label?: string;
 };
-declare const RoughEditButton: svelte.Component<Props$6, {}, "">;
+declare const RoughEditButton: svelte.Component<Props$5, {}, "">;
 type RoughEditButton = ReturnType<typeof RoughEditButton>;
 
 type JsonValue = null | boolean | number | string | JsonValue[] | {
@@ -550,24 +556,17 @@ type SpriteFrameDatastoreContext = {
     spriteInstanceId: string;
 };
 
-type Props$5 = {
+type Props$4 = {
     client: RoughClient;
     surface: RoughSurfaceDefinition;
     featureId: SpriteId;
     buildId: SpriteBuildId;
     datastore?: SpriteFrameDatastore;
+    isEditable?: boolean;
 };
-declare const RoughFeature: svelte.Component<Props$5, {}, "">;
+declare const RoughFeature: svelte.Component<Props$4, {}, "">;
 type RoughFeature = ReturnType<typeof RoughFeature>;
 
-type Props$4 = {
-    client: RoughClient;
-    surface: RoughSurfaceDefinition;
-    getDatastore?: (context: SpriteFrameDatastoreContext) => SpriteFrameDatastore | undefined;
-};
-declare const RoughSurface: svelte.Component<Props$4, {}, "">;
-type RoughSurface = ReturnType<typeof RoughSurface>;
-
 type Props$3 = {
     children?: Snippet;
     class?: string;
@@ -636,14 +635,12 @@ type RoughEditModal = ReturnType<typeof RoughEditModal>;
  * components.
  */
 
-type RoughSurfaceElement = HTMLElement & ComponentProps<typeof RoughSurface>;
 type RoughCreateModalElement = HTMLElement & ComponentProps<typeof RoughCreateModal>;
 type RoughEditModalElement = HTMLElement & ComponentProps<typeof RoughEditModal>;
 type RoughEditButtonElement = HTMLElement & ComponentProps<typeof RoughEditButton>;
 type RoughFeatureElement = HTMLElement & ComponentProps<typeof RoughFeature>;
 declare global {
     interface HTMLElementTagNameMap {
-        'rough-surface': RoughSurfaceElement;
         'rough-create-modal': RoughCreateModalElement;
         'rough-edit-modal': RoughEditModalElement;
         'rough-edit-button': RoughEditButtonElement;
@@ -651,5 +648,5 @@ declare global {
     }
 }
 
-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 };
+export { Mutation, PrimaryButton, Query, ResizeHandle, RoughClientDestroyError, RoughClientDestroyedError, RoughCreateModal, RoughEditButton, RoughFeature, RoughInvalidClientError, RoughReplicacheIdentityConflictError, 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, Sprite, SpriteBuild, SpriteFrameDatastore, SpriteFrameDatastoreContext };