feat(react,js-components): slot limit prop, exported <Block> (#680)

* feat(react,js): slot limit prop, exported `<Block>`

* test: slot limit

* docs: improve jsdoc

---------

Co-authored-by: Ondřej Pešička <77627332+OPesicka@users.noreply.github.com>

Author: VojtechVidra

package.json

@@ -11,6 +11,7 @@
     "shared": "pnpm --filter shared",
     "tsc": "pnpm -r tsc",
     "test": "pnpm -r test",
+    "build": "pnpm -r build",
     "lint": "oxlint --type-aware",
     "commitlint": "commitlint --edit",
     "pre-push": "concurrently \"pnpm lint\" \"pnpm test\" \"pnpm tsc\" \"pnpm spellcheck\"",

workspaces/e2e/pages/js.ts

@@ -6,6 +6,7 @@ import {
   addFloatingBlocksChangeListener,
   fetchWorkflows,
 } from "@flows/js";
+import type { FlowsSlot } from "@flows/js-components";
 import { setupJsComponents } from "@flows/js-components";
 import * as _components from "@flows/js-components/components";
 import * as _tourComponents from "@flows/js-components/tour-components";
@@ -36,6 +37,7 @@ const customFetch =
 const noCurrentBlocks =
   new URLSearchParams(window.location.search).get("noCurrentBlocks") === "true";
 const language = new URLSearchParams(window.location.search).get("language") as LanguageOption;
+const slotLimit = new URLSearchParams(window.location.search).get("slotLimit");
 
 class Card extends LitElement {
   @property({ type: String })
@@ -181,3 +183,6 @@ addFloatingBlocksChangeListener((blocks) => {
 document.querySelector("#fetchWorkflows")?.addEventListener("click", () => {
   void fetchWorkflows();
 });
+
+const flowsSlotElement = document.querySelector<FlowsSlot>("flows-slot");
+if (flowsSlotElement) flowsSlotElement.limit = slotLimit ? Number(slotLimit) : undefined;

workspaces/e2e/pages/react.tsx

@@ -47,6 +47,7 @@ const noCurrentBlocks =
 const language = new URLSearchParams(window.location.search).get("language") as LanguageOption;
 const enableLinkComponent =
   new URLSearchParams(window.location.search).get("LinkComponent") === "true";
+const slotLimit = new URLSearchParams(window.location.search).get("slotLimit");
 
 const Card: FC<ComponentProps<{ text: string }>> = (props) => (
   <div
@@ -124,7 +125,11 @@ const Home: FC = () => {
       <h1>heading 1</h1>
       <h2>Subtitle</h2>
 
-      <FlowsSlot id="my-slot" placeholder={<p>Slot placeholder</p>} />
+      <FlowsSlot
+        id="my-slot"
+        limit={slotLimit ? Number(slotLimit) : undefined}
+        placeholder={<p>Slot placeholder</p>}
+      />
 
       {!noCurrentBlocks && <p className="current-blocks">{JSON.stringify(floatingBlocks)}</p>}
 

workspaces/e2e/tests/slot.spec.ts

@@ -73,6 +73,22 @@ const run = (packageName: string) => {
       "block number two",
     );
   });
+  test(`${packageName} - should limit rendered blocks by slot limit`, async ({ page }) => {
+    await mockBlocksEndpoint(page, [
+      getCard({ text: "block number one" }),
+      getCard({ text: "block number two" }),
+    ]);
+    await page.goto(`/${packageName}.html?slotLimit=1`);
+    await expect(page.getByText("block number one", { exact: true })).toBeVisible();
+    await expect(page.getByText("block number two", { exact: true })).toBeHidden();
+    await mockBlocksEndpoint(page, [
+      getCard({ text: "block number one" }),
+      getCard({ text: "block number two" }),
+    ]);
+    await page.goto(`/${packageName}.html?slotLimit=2`);
+    await expect(page.getByText("block number one", { exact: true })).toBeVisible();
+    await expect(page.getByText("block number two", { exact: true })).toBeVisible();
+  });
 };
 
 run("js");

workspaces/e2e/tests/tour-trigger.spec.ts

@@ -1,4 +1,10 @@
-import type { Block, TourTrigger, TourTriggerExpression, TourTriggerType } from "@flows/shared";
+import type {
+  ApiSurvey,
+  Block,
+  TourTrigger,
+  TourTriggerExpression,
+  TourTriggerType,
+} from "@flows/shared";
 import test, { expect } from "@playwright/test";
 import { randomUUID } from "crypto";
 import { mockBlocksEndpoint } from "./utils";
@@ -385,6 +391,21 @@ const run = (packageName: string) => {
       await page.reload();
       await expect(page.getByText("World", { exact: true })).toBeVisible();
     });
+    test(`${packageName} - should be hidden with different block state ID`, async ({ page }) => {
+      const block = getSurvey([{ type: "click", value: "h1" }]);
+      await mockBlocksEndpoint(page, [block]);
+      await page.goto(`/${packageName}.html`);
+      await expect(page.getByText("Hello", { exact: true })).toBeHidden();
+      await page.locator("h1").click();
+      await expect(page.getByText("Hello", { exact: true })).toBeVisible();
+      const surveyBlockWithDifferentBlockStateId: Block = {
+        ...block,
+        survey: { ...(block.survey as ApiSurvey), blockStateId: randomUUID() },
+      };
+      await mockBlocksEndpoint(page, [surveyBlockWithDifferentBlockStateId]);
+      await page.reload();
+      await expect(page.getByText("Hello", { exact: true })).toBeHidden();
+    });
   });
 };
 

workspaces/js-components/src/slot.ts

@@ -14,6 +14,16 @@ export class FlowsSlot extends LitElement {
   @property({ type: String, attribute: "data-slot-id" })
   slotId: string;
 
+  /**
+   * Limit of how many blocks to render in this slot. Defaults to no limit.
+   *
+   * Useful when multiple blocks match the same slot.
+   *
+   * @default undefined
+   */
+  @property({ type: Number })
+  limit?: number;
+
   connectedCallback(): void {
     super.connectedCallback();
 
@@ -46,7 +56,10 @@ export class FlowsSlot extends LitElement {
       else this.placeholderElement.hidden = false;
     }
 
-    return repeat(this._blocks, getBlockRenderKey, (block) => {
+    const blocksToRender =
+      this.limit === undefined ? this._blocks : this._blocks.slice(0, this.limit);
+
+    return repeat(blocksToRender, getBlockRenderKey, (block) => {
       return Block({ block });
     });
   }

workspaces/react/src/components/block.tsx

@@ -6,6 +6,13 @@ interface Props {
   block: ActiveBlock;
 }
 
+/**
+ * Renders a single `ActiveBlock` using the matching component from `components`, `tourComponents`, or `surveyComponents` registered in `FlowsProvider`.
+ *
+ * `ActiveBlock` can be obtained from `useCurrentFloatingBlocks` or `useCurrentSlotBlocks`.
+ *
+ * Useful for advanced block rendering implementations.
+ */
 export const Block: FC<Props> = ({ block }) => {
   const { components, tourComponents, surveyComponents } = useFlowsContext();
 

workspaces/react/src/components/flows-slot.tsx

@@ -1,18 +1,31 @@
-import { type FC, type ReactNode } from "react";
+import { useMemo, type FC, type ReactNode } from "react";
 import { getBlockRenderKey } from "@flows/shared";
 import { useCurrentSlotBlocks } from "../hooks/use-current-blocks";
 import { Block } from "./block";
 
 export interface FlowsSlotProps {
   id: string;
   placeholder?: ReactNode;
+  /**
+   * Limit of how many blocks to render in this slot. Defaults to no limit.
+   *
+   * Useful when multiple blocks match the same slot.
+   *
+   * @default undefined
+   */
+  limit?: number;
 }
 
-export const FlowsSlot: FC<FlowsSlotProps> = ({ id, placeholder }) => {
-  const items = useCurrentSlotBlocks(id);
+export const FlowsSlot: FC<FlowsSlotProps> = ({ id, placeholder, limit }) => {
+  const blocks = useCurrentSlotBlocks(id);
 
-  if (items.length)
-    return items.map((item) => {
+  const blocksToRender = useMemo(
+    () => (limit === undefined ? blocks : blocks.slice(0, limit)),
+    [blocks, limit],
+  );
+
+  if (blocksToRender.length)
+    return blocksToRender.map((item) => {
       return <Block key={getBlockRenderKey(item)} block={item} />;
     });
 

workspaces/react/src/index.ts

@@ -33,3 +33,4 @@ export type {
 export * from "./components/flows-slot";
 export { FlowsProvider } from "./flows-provider";
 export * from "./methods";
+export { Block } from "./components/block";