-
π§ͺ
-
- Texera lets you build big-data workflows by
- dragging blocks β no code required.
-
-
- Take a friendly 2-minute tour and you'll have a
- real workflow running by the end. We'll celebrate together π
-
-
- You can relaunch the tour any time from the floating button.
-
+
+
You're partway through ${flow.name} β step ${stepNum} of ${flow.steps.length}.
+
Pick up where you left off, restart this flow, or browse other tours.
+
+
+
+
+
`,
},
},
],
});
- this.welcomeDriver.drive();
+ this.resumeDriver.drive();
+
+ setTimeout(() => this.bindResumeHandlers(flow), 50);
+ }
+
+ private bindResumeHandlers(flow: TutorialFlow): void {
+ const root = document.querySelector(".tutorial-resume-popover");
+ if (!root) return;
+ root.querySelector
("[data-action='resume']")?.addEventListener("click", () => {
+ this.resumeDriver?.destroy();
+ setTimeout(() => this.tutorialService.resume(), 250);
+ });
+ root.querySelector("[data-action='restart']")?.addEventListener("click", () => {
+ this.resumeDriver?.destroy();
+ setTimeout(() => this.tutorialService.start(flow.id), 250);
+ });
+ root.querySelector("[data-action='picker']")?.addEventListener("click", () => {
+ this.resumeDriver?.destroy();
+ setTimeout(() => this.showFlowPickerPopover(), 250);
+ });
+ }
+
+ /**
+ * Asks the user whether to chain into the next flow after the current one
+ * finished. Driven by the completed flow's `chainTo` field β fires after a
+ * short delay so the celebration burst + badge notification land first.
+ */
+ private showChainConfirmPopover(finished: TutorialFlow, next: TutorialFlow): void {
+ this.chainDriver = driver({
+ showProgress: false,
+ allowClose: true,
+ overlayColor: "#000",
+ overlayOpacity: 0.65,
+ stagePadding: 0,
+ popoverClass: "tutorial-welcome-popover tutorial-resume-popover",
+ showButtons: ["close"],
+ onCloseClick: () => this.chainDriver?.destroy(),
+ onDestroyed: () => {
+ this.chainDriver = null;
+ },
+ steps: [
+ {
+ popover: {
+ title: `${finished.badge.emoji} ${finished.badge.name} unlocked!`,
+ description: `
+
+
Nice β you've got the lay of the land. Want to build your first workflow now?
+
+
+
+
+
year > 1960 β so the chart later only shows the modern era.",
+ side: "bottom",
+ align: "center",
+ },
+ title: "Step 3 β Meet the filter",
+ aiHint:
+ "Spotlight on the prebuilt Filter operator with its single predicate (year > 1960) explained. No interaction needed β user clicks Next.",
+ },
+ {
+ element: 'nz-collapse-panel[data-group-name="Visualization"]',
+ popover: {
+ title: "Open the Visualization category",
+ description:
+ 'On the left, click "Visualization". This category holds every chart Texera supports: bar, line, pie, scatter, and more exotic ones.',
+ side: "right",
+ align: "start",
+ },
+ title: "Step 4 β Visualization category",
+ aiHint: "The user is expanding the 'Visualization' group in the operator menu so they can find chart operators.",
+ advanceOnClick: true,
+ },
+ {
+ element: 'nz-collapse-panel[data-group-name="Basic"]',
+ popover: {
+ title: "Then the Basic sub-group",
+ description:
+ 'Visualization is split into sub-groups. Click "Basic" to find the everyday charts (bar, line, pie).',
+ side: "right",
+ align: "start",
+ },
+ title: "Step 5 β Basic sub-group",
+ aiHint:
+ "The Visualization group has nested sub-groups. The user is opening 'Basic' to reveal Bar/Line/Pie chart operators.",
+ advanceOnClick: true,
+ },
+ {
+ element: '.operator-label[data-operator-type="DotPlot"]',
+ popover: {
+ title: "Drag Dot Plot onto the canvas",
+ description:
+ "Grab Dot Plot and drop it on the canvas, somewhere to the right of your Filter box. We're going to feed Filter's output into it.",
+ side: "right",
+ align: "start",
+ },
+ title: "Step 6 β Drag Dot Plot",
+ aiHint:
+ "The user drags the Dot Plot visualization operator onto the canvas. It will be connected to Filter's output in the next step.",
+ autoAdvanceOn: "operatorAdded",
+ },
+ {
+ element: "texera-workflow-editor",
+ popover: {
+ title: "Wire Filter into the chart",
+ description:
+ "Drag from the output port on the right edge of Filter over to the input port on the left edge of Dot Plot. Now the chart will receive the filtered rows.",
+ side: "over",
+ align: "center",
+ },
+ title: "Step 7 β Connect Filter to Dot Plot",
+ aiHint:
+ "The user is dragging an edge from Filter's output to Dot Plot's input so the chart visualizes the filtered rows.",
+ autoAdvanceOn: "linkAdded",
+ },
+ {
+ element: '[model-id^="DotPlot-operator-"]',
+ popover: {
+ title: "Click the chart to configure it",
+ description:
+ "Click the Dot Plot box. The property panel on the right will switch to its settings so you can pick which column to count.",
+ side: "bottom",
+ align: "center",
+ },
+ title: "Step 8 β Select Dot Plot",
+ aiHint:
+ "The user clicks the Dot Plot operator on the canvas so the property panel switches to its single-field config (Count Attribute).",
+ autoAdvanceOn: "operatorSelected",
+ },
+ {
+ element: 'li[data-tutorial="open-property-panel"]',
+ popover: {
+ title: "Open the property panel",
+ description:
+ "If the panel collapsed, click the form icon at the top-right to reopen it. (Already open? Skipping.)",
+ side: "left",
+ align: "center",
+ },
+ title: "Step 9 β Reopen property panel",
+ aiHint:
+ "The user reopens the property panel for the Dot Plot operator. Auto-skipped when the panel is already open.",
+ advanceOnClick: true,
+ },
+ {
+ element: ".property-editor-form",
+ popover: {
+ title: "Pick the column",
+ description:
+ "In the highlighted form, set the only required field:
β’ Count Attribute: runtime
This will show one dot per runtime value, sized by how many movies share it. Click Next once set.",
+ side: "left",
+ align: "center",
+ },
+ title: "Step 10 β Configure Dot Plot",
+ aiHint:
+ "The user fills Dot Plot's single required field: Count Attribute = 'runtime'. The field renders as an nz-select dropdown of column names (AutofillAttributeName), and after selection the operator groups by runtime and counts rows. Spotlight is on .property-editor-form; styles.scss handles overflow / cdk-overlay z-index so the dropdown opens normally.",
+ autoAdvanceOn: "propertyChanged",
+ },
+ {
+ element: "#run-button",
+ popover: {
+ title: "Run it",
+ description: "Hit Run. Texera will pipe the rows through Filter into Dot Plot and render it.",
+ side: "bottom",
+ align: "start",
+ },
+ title: "Step 11 β Run the workflow",
+ aiHint: "The user clicks the Run button to execute the workflow with the new Dot Plot.",
+ advanceOnClick: true,
+ },
+ {
+ element: 'li[data-tutorial="open-result-panel"]',
+ popover: {
+ title: "Open the result panel",
+ description:
+ "Click the square icon at the bottom-left to expand the result panel. Then click the Dot Plot on the canvas to see its rendered output.",
+ side: "top",
+ align: "start",
+ },
+ title: "Step 12 β Open result panel",
+ aiHint: "The user clicks the 'Open Result Panel' icon at the bottom-left to expand the data panel.",
+ advanceOnClick: true,
+ },
+ {
+ popover: {
+ title: "Chart unlocked",
+ description:
+ "Your data is now visual. Click any operator to inspect its output in the result panel. When you're ready for the next level, try the Add a simple ML model tour next.",
+ },
+ title: "Step 13 β Chart celebration",
+ aiHint:
+ "Final step. The user has wired a Dot Plot off Filter and run the workflow. No element highlighted, centered celebratory popover that teases the ML follow-up tour.",
+ },
+];
+
+export const BUILD_COMPLEX_FLOW: TutorialFlow = {
+ id: "build-complex",
+ name: "Add a chart",
+ shortDesc: "Plug a Dot Plot onto a pre-built CSV + Filter workflow and see the data.",
+ difficulty: "medium",
+ estimatedMinutes: 2,
+ prerequisites: ["build-simple"],
+ prebuiltWorkflow: "movies-filter",
+ badge: {
+ id: "chart-maker",
+ emoji: "π",
+ name: "Chart Maker",
+ description: "Visualized a Texera workflow with your first chart.",
+ hue: "#13c2c2",
+ },
+ steps: STEPS,
+};
diff --git a/frontend/src/app/workspace/service/tutorial/flows/build-simple.ts b/frontend/src/app/workspace/service/tutorial/flows/build-simple.ts
new file mode 100644
index 00000000000..dd8cd8cea2f
--- /dev/null
+++ b/frontend/src/app/workspace/service/tutorial/flows/build-simple.ts
@@ -0,0 +1,271 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import type { TutorialFlow, TutorialStep } from "./index";
+
+const STEPS: TutorialStep[] = [
+ {
+ popover: {
+ title: "Let's build your first workflow",
+ description:
+ "We'll wire a tiny pipeline together: CSV File Scan β Limit β Run β see the rows. Should take about 2 minutes. Ready? Click Next.",
+ },
+ title: "Step 1 β Intro",
+ aiHint:
+ "Brief intro for build-simple. Assumes the user has seen (or will skip) the workspace overview tour, so this step does NOT dwell on what the operator panel is β it just states the goal (CSV -> Limit -> Run -> view) and starts. No element highlighted, centered popover.",
+ },
+ {
+ element: 'nz-collapse-panel[data-group-name="Data Input"]',
+ popover: {
+ title: "First, let's get some data",
+ description:
+ 'Click "Data Input" to open the category. Sources are operators that pull data into your workflow β CSV files, databases, APIs.',
+ side: "right",
+ align: "start",
+ },
+ title: "Step 2 β Find a Source",
+ aiHint: "The user is locating the Data Input category to find a source operator.",
+ advanceOnClick: true,
+ },
+ {
+ element: '.operator-label[data-operator-type="CSVFileScan"]',
+ popover: {
+ title: "Drag it onto the canvas",
+ description:
+ "Grab CSV File Scan and drop it onto the empty canvas on the right. This little box's job: read rows from a CSV file.",
+ side: "right",
+ align: "start",
+ },
+ title: "Step 3 β Drag CSV File Scan",
+ aiHint: "The user is dragging the CSV File Scan source operator from the operator panel onto the canvas.",
+ autoAdvanceOn: "operatorAdded",
+ },
+ {
+ element: '[model-id^="CSVFileScan-operator-"]',
+ popover: {
+ title: "Nice! Now give it a click",
+ description:
+ "There's your CSV File Scan on the canvas. Click it once to select it β that's how we tell Texera \"I want to configure this one\".",
+ side: "bottom",
+ align: "center",
+ },
+ title: "Step 4 β Click the Operator",
+ aiHint: "The user needs to click the just-placed CSV File Scan operator on the canvas to open its property editor.",
+ autoAdvanceOn: "operatorSelected",
+ },
+ {
+ element: 'li[data-tutorial="open-property-panel"]',
+ popover: {
+ title: "Open its settings",
+ description:
+ "See the little form icon at the top-right? Click it to slide open the settings panel on the right side. (Already open? We'll just skip ahead.)",
+ side: "left",
+ align: "center",
+ },
+ title: "Step 5 β Open the Property Panel",
+ aiHint:
+ "The user needs to click the small form icon at the top-right of the canvas to expand the (currently collapsed) property panel. Auto-skipped when the panel is already open.",
+ advanceOnClick: true,
+ },
+ {
+ element: "#formly-title",
+ popover: {
+ title: "This is the property panel",
+ description:
+ "Every operator's settings live here. For CSV File Scan, the only thing we need is to pick a file. Click Next.",
+ side: "left",
+ align: "center",
+ },
+ title: "Step 6 β Meet the property panel",
+ aiHint:
+ "Always-shown explainer that introduces the property panel. Runs whether the previous open-property-panel step was clicked or auto-skipped, so users who already had the panel open still get the orientation.",
+ },
+ {
+ element: 'button[data-tutorial="file-select-button"]',
+ popover: {
+ title: "Pick a file",
+ description: "Click Select File to open the dataset browser β that's where your CSVs live.",
+ side: "left",
+ align: "center",
+ },
+ title: "Step 7 β Open the File Picker",
+ aiHint: "The user is about to click the Select File button to open the dataset selection modal.",
+ advanceOnClick: true,
+ },
+ {
+ element: ".ant-modal-content",
+ popover: {
+ title: "Browse your data",
+ description:
+ "Pick a dataset on the left, expand a version, then double-click any .csv. The modal closes itself and the file name auto-fills β no typing required.",
+ side: "top",
+ align: "end",
+ },
+ title: "Step 8 β Pick a CSV File",
+ aiHint:
+ "The user is choosing a CSV file from the dataset selection modal. After they pick one, the modal closes and the fileName property updates.",
+ autoAdvanceOn: "propertyChanged",
+ },
+ {
+ element: 'nz-collapse-panel[data-group-name="Data Cleaning"]',
+ popover: {
+ title: "Time for a second operator",
+ description:
+ 'Back to the left panel. Click "Data Cleaning" to open that category β we\'re about to chain a second operator after our source.',
+ side: "right",
+ align: "start",
+ },
+ title: "Step 9 β Find the Data Cleaning Category",
+ aiHint: "The user needs to expand the Data Cleaning category in the operator panel to find Limit.",
+ advanceOnClick: true,
+ },
+ {
+ element: '.operator-label[data-operator-type="Limit"]',
+ popover: {
+ title: "Drag Limit onto the canvas",
+ description:
+ "Grab Limit and drop it on the canvas next to CSV File Scan. Limit caps your output to the first N rows β perfect for a quick peek.",
+ side: "right",
+ align: "start",
+ },
+ title: "Step 10 β Drag Limit",
+ aiHint: "The user is dragging the Limit operator onto the canvas as a second operator.",
+ autoAdvanceOn: "operatorAdded",
+ },
+ {
+ element: "texera-workflow-editor",
+ popover: {
+ title: "Wire them up",
+ description:
+ 'Drag from the βΆ port on the right edge of CSV File Scan over to the port on the left edge of Limit. That edge tells Texera "send rows this way".',
+ side: "over",
+ align: "center",
+ },
+ title: "Step 11 β Connect Operators",
+ aiHint: "The user is dragging an edge from CSV File Scan's output port to Limit's input port.",
+ autoAdvanceOn: "linkAdded",
+ },
+ {
+ element: '[model-id^="Limit-operator-"]',
+ popover: {
+ title: "Click Limit to configure it",
+ description:
+ "Click the Limit box on the canvas. The property panel on the right will swap over to its settings β each operator has its own.",
+ side: "bottom",
+ align: "center",
+ },
+ title: "Step 12 β Click Limit",
+ aiHint:
+ "The user needs to click the just-connected Limit operator on the canvas to switch the property editor to its fields.",
+ autoAdvanceOn: "operatorSelected",
+ },
+ {
+ element: 'li[data-tutorial="open-property-panel"]',
+ popover: {
+ title: "Open its settings",
+ description:
+ "If the panel collapsed again, click the form icon at the top-right to reopen it. (Already open? Skippingβ¦)",
+ side: "left",
+ align: "center",
+ },
+ title: "Step 13 β Open the Property Panel (Limit)",
+ aiHint:
+ "Same as step 5: the user clicks the form icon to reopen the property panel for the Limit operator. Auto-skipped when the panel is already open.",
+ advanceOnClick: true,
+ },
+ {
+ element: ".property-editor-form",
+ popover: {
+ title: "How many rows?",
+ description:
+ "Type a number into the Limit field β that's the max rows you'll see. Try 10 for a snappy preview.",
+ side: "left",
+ align: "start",
+ },
+ title: "Step 14 β Configure Limit",
+ aiHint: "The user is configuring the Limit operator by typing a number in the limit field (max output rows).",
+ autoAdvanceOn: "propertyChanged",
+ },
+ {
+ element: "#texera-compute-unit-selection",
+ popover: {
+ title: "Almost there β pick a Computing Unit",
+ description:
+ "Before running, click the Computing Unit selector at the top and pick (or start) one. That's the little worker that'll execute your workflow.",
+ side: "bottom",
+ align: "start",
+ },
+ title: "Step 15 β Connect a Computing Unit",
+ aiHint: "The user needs to select/connect a Computing Unit from the top menu before running the workflow.",
+ autoAdvanceOn: "computingUnitConnected",
+ },
+ {
+ element: "#run-button",
+ popover: {
+ title: "Hit Run!",
+ description:
+ "Once the unit shows Connected, smash that βΆ Run button and watch Texera get to work.",
+ side: "bottom",
+ align: "start",
+ },
+ title: "Step 16 β Run the Workflow",
+ aiHint: "The user is clicking the Run button at the top to execute the workflow.",
+ advanceOnClick: true,
+ },
+ {
+ element: 'li[data-tutorial="open-result-panel"]',
+ popover: {
+ title: "Open the result panel",
+ description:
+ "Your workflow finished β the data is ready! Click this little square icon at the bottom-left to slide open the result panel and see your rows.",
+ side: "top",
+ align: "start",
+ },
+ title: "Step 17 β Open the Result Panel",
+ aiHint:
+ "The user just ran the workflow. They need to click the 'Open Result Panel' icon (the square / border icon at the bottom-left of the screen) to expand the result panel and view their data.",
+ advanceOnClick: true,
+ },
+ {
+ popover: {
+ title: "π You did it!",
+ description:
+ "Your CSV rows are now waiting for you in the result panel. You just built and ran your very first Texera workflow β from empty canvas to real data in under two minutes. Welcome aboard!",
+ },
+ title: "Step 18 β Celebration",
+ aiHint:
+ "Final celebratory step. The user has opened the result panel and can now see their workflow's output. No element is highlighted β the popover is centered like the welcome screen for a clean closing moment.",
+ },
+];
+
+export const BUILD_SIMPLE_FLOW: TutorialFlow = {
+ id: "build-simple",
+ name: "Build your first workflow",
+ shortDesc: "CSV β Limit β Run β View. The friendly 18-step intro.",
+ difficulty: "intro",
+ estimatedMinutes: 2,
+ badge: {
+ id: "workflow-builder",
+ emoji: "π§±",
+ name: "Workflow Builder",
+ description: "Built and ran your first Texera workflow.",
+ hue: "#1890ff",
+ },
+ steps: STEPS,
+};
diff --git a/frontend/src/app/workspace/service/tutorial/flows/flows-integrity.spec.ts b/frontend/src/app/workspace/service/tutorial/flows/flows-integrity.spec.ts
new file mode 100644
index 00000000000..6e0666988c8
--- /dev/null
+++ b/frontend/src/app/workspace/service/tutorial/flows/flows-integrity.spec.ts
@@ -0,0 +1,154 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { BONUS_BADGES, FLOWS, getFlowById, GRADUATE_BADGE, SPEED_RUNNER_BADGE, TutorialFlow } from "./index";
+
+describe("FLOWS registry integrity", () => {
+ describe("identifiers", () => {
+ it("every flow has a unique id", () => {
+ const ids = FLOWS.map(f => f.id);
+ expect(new Set(ids).size).toBe(ids.length);
+ });
+
+ it("every flow's badge id is unique across all flows + bonus badges", () => {
+ const ids = [...FLOWS.map(f => f.badge.id), ...BONUS_BADGES.map(b => b.id)];
+ const seen = new Set();
+ const dupes: string[] = [];
+ for (const id of ids) {
+ if (seen.has(id)) dupes.push(id);
+ seen.add(id);
+ }
+ expect(dupes).toEqual([]);
+ });
+
+ it("getFlowById returns the matching flow", () => {
+ for (const flow of FLOWS) {
+ expect(getFlowById(flow.id)).toBe(flow);
+ }
+ });
+
+ it("getFlowById returns null for an unknown id", () => {
+ expect(getFlowById("does-not-exist")).toBeNull();
+ });
+ });
+
+ describe("step content", () => {
+ it("every step in every launchable flow has a non-empty title and aiHint", () => {
+ const offenders: string[] = [];
+ for (const flow of FLOWS.filter(f => !f.comingSoon && f.steps.length > 0)) {
+ flow.steps.forEach((step, i) => {
+ if (!step.title) offenders.push(`${flow.id}[${i}].title`);
+ if (!step.aiHint) offenders.push(`${flow.id}[${i}].aiHint`);
+ });
+ }
+ expect(offenders).toEqual([]);
+ });
+
+ it("flows marked comingSoon have empty steps arrays (convention check)", () => {
+ const violations = FLOWS.filter(f => f.comingSoon && f.steps.length > 0).map(f => f.id);
+ expect(violations).toEqual([]);
+ });
+ });
+
+ describe("skipToStep targets", () => {
+ it("every skipToStep value points to a strictly later step inside the same flow", () => {
+ const offenders: string[] = [];
+ for (const flow of FLOWS) {
+ flow.steps.forEach((step, i) => {
+ if (step.skipToStep === undefined) return;
+ if (step.skipToStep <= i || step.skipToStep >= flow.steps.length) {
+ offenders.push(`${flow.id}[${i}] β ${step.skipToStep}`);
+ }
+ });
+ }
+ expect(offenders).toEqual([]);
+ });
+
+ it("skipToStep is only used together with showDetailsButton (paired branching)", () => {
+ const unpaired: string[] = [];
+ for (const flow of FLOWS) {
+ flow.steps.forEach((step, i) => {
+ if (step.skipToStep !== undefined && step.showDetailsButton !== true) {
+ unpaired.push(`${flow.id}[${i}]`);
+ }
+ });
+ }
+ expect(unpaired).toEqual([]);
+ });
+ });
+
+ describe("chainTo references", () => {
+ it("every chainTo points at a real flow id", () => {
+ const broken: string[] = [];
+ for (const flow of FLOWS) {
+ if (flow.chainTo && getFlowById(flow.chainTo) === null) {
+ broken.push(`${flow.id} β ${flow.chainTo}`);
+ }
+ }
+ expect(broken).toEqual([]);
+ });
+
+ it("no flow chains to itself", () => {
+ const selfLoops = FLOWS.filter(f => f.chainTo === f.id).map(f => f.id);
+ expect(selfLoops).toEqual([]);
+ });
+ });
+
+ describe("prerequisites", () => {
+ it("every prerequisite id resolves to a real flow", () => {
+ const broken: string[] = [];
+ for (const flow of FLOWS) {
+ for (const prereq of flow.prerequisites ?? []) {
+ if (getFlowById(prereq) === null) broken.push(`${flow.id} β ${prereq}`);
+ }
+ }
+ expect(broken).toEqual([]);
+ });
+ });
+
+ describe("bonus badges", () => {
+ it("BONUS_BADGES contains SPEED_RUNNER and GRADUATE", () => {
+ expect(BONUS_BADGES).toContain(SPEED_RUNNER_BADGE);
+ expect(BONUS_BADGES).toContain(GRADUATE_BADGE);
+ });
+ });
+});
+
+describe("overview-workspace branching", () => {
+ let flow: TutorialFlow;
+
+ beforeAll(() => {
+ const found = getFlowById("overview-workspace");
+ expect(found).not.toBeNull();
+ flow = found!;
+ });
+
+ it("every group-overview step jumps over at least one detail step", () => {
+ const offenders: string[] = [];
+ flow.steps.forEach((step, index) => {
+ if (step.skipToStep === undefined) return;
+ if (step.skipToStep <= index + 1) {
+ offenders.push(`${flow.id}[${index}] β ${step.skipToStep} (no skip)`);
+ }
+ const target = flow.steps[step.skipToStep];
+ if (!target?.title) offenders.push(`${flow.id}[${step.skipToStep}] has no title`);
+ });
+ expect(offenders).toEqual([]);
+ });
+});
diff --git a/frontend/src/app/workspace/service/tutorial/flows/index.ts b/frontend/src/app/workspace/service/tutorial/flows/index.ts
new file mode 100644
index 00000000000..cf873325c66
--- /dev/null
+++ b/frontend/src/app/workspace/service/tutorial/flows/index.ts
@@ -0,0 +1,145 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { DriveStep } from "driver.js";
+import { OVERVIEW_WORKSPACE_FLOW } from "./overview-workspace";
+import { BUILD_SIMPLE_FLOW } from "./build-simple";
+import { BUILD_COMPLEX_FLOW } from "./build-complex";
+import { PUBLIC_WORKFLOW_FLOW } from "./public-workflow";
+
+export type AutoAdvanceTrigger =
+ | "operatorAdded"
+ | "operatorSelected"
+ | "linkAdded"
+ | "executionStarted"
+ | "propertyChanged"
+ | "computingUnitConnected";
+
+export interface TutorialStep extends DriveStep {
+ /** Short label used by the AI chat for context. */
+ title: string;
+ /** Prompt fragment given to the AI when the user asks a question on this step. */
+ aiHint: string;
+ /** If set, advance automatically when this event fires on the workflow. */
+ autoAdvanceOn?: AutoAdvanceTrigger;
+ /** If true, clicking the highlighted element advances to the next step. */
+ advanceOnClick?: boolean;
+ /** Default Next jumps to this index instead of `+1`. Pair with `showDetailsButton` for opt-in deep dives. */
+ skipToStep?: number;
+ /** Adds a secondary "Show details" button to the popover that does normal moveNext. Only meaningful with `skipToStep`. */
+ showDetailsButton?: boolean;
+}
+
+export interface BadgeDef {
+ id: string;
+ emoji: string;
+ name: string;
+ description: string;
+ /** Optional palette to tint the locked silhouette / unlocked frame. */
+ hue?: string;
+}
+
+export interface TutorialFlow {
+ id: string;
+ name: string;
+ shortDesc: string;
+ difficulty: "intro" | "easy" | "medium" | "advanced";
+ estimatedMinutes: number;
+ /** Stub flows have empty `steps` arrays and aren't launchable yet. */
+ comingSoon?: boolean;
+ /** Flow ids the user is encouraged to finish first. */
+ prerequisites?: string[];
+ badge: BadgeDef;
+ steps: TutorialStep[];
+ /** Basename of a JSON fixture under `assets/tutorial-workflows/` to load into the canvas before step 0. */
+ prebuiltWorkflow?: string;
+ /**
+ * Flow id to chain into automatically when this one completes.
+ */
+ chainTo?: string;
+}
+
+/** Coming-soon placeholders advertised in the picker but not launchable. */
+const BUILD_ML_FLOW: TutorialFlow = {
+ id: "build-ml",
+ name: "Add a simple ML model",
+ shortDesc: "Train a Logistic Regression classifier on a pre-built workflow.",
+ difficulty: "advanced",
+ estimatedMinutes: 2,
+ prerequisites: ["build-simple"],
+ comingSoon: true,
+ badge: {
+ id: "data-scientist",
+ emoji: "π§ͺ",
+ name: "Data Scientist",
+ description: "Trained your first ML model inside Texera.",
+ hue: "#52c41a",
+ },
+ steps: [],
+};
+
+const HUB_TOUR_FLOW: TutorialFlow = {
+ id: "hub-tour",
+ name: "Tour the Texera hub",
+ shortDesc: "Workflows, datasets, public projects β start here.",
+ difficulty: "intro",
+ estimatedMinutes: 1,
+ comingSoon: true,
+ badge: {
+ id: "first-steps",
+ emoji: "π",
+ name: "First Steps",
+ description: "Took the Texera hub orientation tour.",
+ hue: "#1890ff",
+ },
+ steps: [],
+};
+
+export const FLOWS: TutorialFlow[] = [
+ OVERVIEW_WORKSPACE_FLOW,
+ BUILD_SIMPLE_FLOW,
+ BUILD_COMPLEX_FLOW,
+ BUILD_ML_FLOW,
+ HUB_TOUR_FLOW,
+ PUBLIC_WORKFLOW_FLOW,
+];
+
+export function getFlowById(id: string): TutorialFlow | null {
+ return FLOWS.find(f => f.id === id) ?? null;
+}
+
+/** Special meta-badge granted automatically when every other badge is earned. */
+export const GRADUATE_BADGE: BadgeDef = {
+ id: "graduate",
+ emoji: "π",
+ name: "Texera Graduate",
+ description: "Completed every tutorial flow β true Texera fluency.",
+ hue: "#722ed1",
+};
+
+/** Bonus badge for fast completions. */
+export const SPEED_RUNNER_BADGE: BadgeDef = {
+ id: "speed-runner",
+ emoji: "β‘",
+ name: "Speed Runner",
+ description: "Finished a flow in under 90 seconds.",
+ hue: "#fa8c16",
+};
+
+export const BONUS_BADGES: BadgeDef[] = [SPEED_RUNNER_BADGE, GRADUATE_BADGE];
diff --git a/frontend/src/app/workspace/service/tutorial/flows/overview-workspace.ts b/frontend/src/app/workspace/service/tutorial/flows/overview-workspace.ts
new file mode 100644
index 00000000000..c7f11f48990
--- /dev/null
+++ b/frontend/src/app/workspace/service/tutorial/flows/overview-workspace.ts
@@ -0,0 +1,348 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import type { TutorialFlow, TutorialStep } from "./index";
+
+/**
+ * Workspace orientation tour with branching detail dives.
+ *
+ * The main spine is 8 steps (Operator panel β 3 toolbar group overviews β
+ * Result panel β Mini-map β AI Agent β Hand-off). Each group overview
+ * offers two ways forward via the popover footer:
+ * - Next β skips ahead to the next main step
+ * - Learn more β drills into the group's individual icons one by one
+ *
+ * The 14 detail steps hide their own progress counter (`showProgress: false`)
+ * so the visible "Step X / 8" only ever reflects spine progress β detail
+ * dives feel like an aside instead of inflating the perceived length.
+ */
+const STEPS: TutorialStep[] = [
+ // 0 Β· MAIN 1/8
+ {
+ element: "texera-operator-menu",
+ popover: {
+ title: "Operator panel",
+ description: "The building blocks of every workflow live here. Drag them onto the canvas to use them.",
+ side: "right",
+ align: "start",
+ progressText: "Step 1 / 8",
+ },
+ title: "Step 1 β Operator Panel",
+ aiHint: "Orientation: operator menu on the left.",
+ },
+ // 1 Β· MAIN 2/8 (branch: Next skips to idx 9, Learn more drills in)
+ {
+ element: "#user-buttons",
+ popover: {
+ title: "Toolbar Β· file actions",
+ description: "Save, import, export, and other workflow-file operations.",
+ side: "bottom",
+ align: "start",
+ progressText: "Step 2 / 8",
+ },
+ title: "Step 2 β Left group overview",
+ aiHint:
+ "Left toolbar group overview. Default Next skips past the 7 file-action details (idx 2-8) to the middle overview; 'Learn more' drills in.",
+ skipToStep: 9,
+ showDetailsButton: true,
+ },
+ // 2 Β· DETAIL
+ {
+ element: 'button[title="dashboard"]',
+ popover: {
+ title: "Dashboard",
+ description: "Jump back to your workflow list.",
+ side: "bottom",
+ align: "center",
+ popoverClass: "tutorial-no-progress",
+ },
+ title: "Step β Dashboard",
+ aiHint: "Detail (left group): dashboard button.",
+ },
+ // 3 Β· DETAIL
+ {
+ element: 'button[title="create new"]',
+ popover: {
+ title: "New workflow",
+ description: "Start a blank workflow in a new tab.",
+ side: "bottom",
+ align: "center",
+ popoverClass: "tutorial-no-progress",
+ },
+ title: "Step β New",
+ aiHint: "Detail (left group): create-new button.",
+ },
+ // 4 Β· DETAIL
+ {
+ element: 'button[title="save"]',
+ popover: {
+ title: "Save",
+ description: "Snapshots the workflow now instead of waiting for the next auto-save.",
+ side: "bottom",
+ align: "center",
+ popoverClass: "tutorial-no-progress",
+ },
+ title: "Step β Save",
+ aiHint: "Detail (left group): save button.",
+ },
+ // 5 Β· DETAIL
+ {
+ element: 'button[title="delete all"]',
+ popover: {
+ title: "Delete all",
+ description: "Wipe every operator from the canvas β handy when you want a fresh start.",
+ side: "bottom",
+ align: "center",
+ popoverClass: "tutorial-no-progress",
+ },
+ title: "Step β Delete all",
+ aiHint: "Detail (left group): delete-all-operators button.",
+ },
+ // 6 Β· DETAIL
+ {
+ element: 'button[title="import workflow"]',
+ popover: {
+ title: "Import",
+ description: "Upload a workflow JSON file and load it onto this canvas.",
+ side: "bottom",
+ align: "center",
+ popoverClass: "tutorial-no-progress",
+ },
+ title: "Step β Import",
+ aiHint: "Detail (left group): import-workflow button.",
+ },
+ // 7 Β· DETAIL
+ {
+ element: 'button[title="export workflow"]',
+ popover: {
+ title: "Export",
+ description: "Download the current workflow as a JSON file.",
+ side: "bottom",
+ align: "center",
+ popoverClass: "tutorial-no-progress",
+ },
+ title: "Step β Export",
+ aiHint: "Detail (left group): export-workflow button.",
+ },
+ // 8 Β· DETAIL
+ {
+ element: 'button[title="change description"]',
+ popover: {
+ title: "Description",
+ description: "Edit the workflow's description text.",
+ side: "bottom",
+ align: "center",
+ popoverClass: "tutorial-no-progress",
+ },
+ title: "Step β Description",
+ aiHint: "Detail (left group): change-description button.",
+ },
+ // 9 Β· MAIN 3/8 (branch: Next skips to idx 14, Learn more drills in)
+ {
+ element: "#expanded-utilities nz-space-compact",
+ popover: {
+ title: "Toolbar Β· canvas utilities",
+ description:
+ "Tools for keeping the canvas tidy as your workflow grows β layers, layout, comments, undo / redo, and more.",
+ side: "bottom",
+ align: "center",
+ progressText: "Step 3 / 8",
+ popoverClass: "tutorial-wide-popover",
+ },
+ title: "Step 3 β Middle group overview",
+ aiHint:
+ "Middle toolbar group overview. Default Next skips past auto-layout/comment/undo/redo (idx 10-13) to the right overview; 'Learn more' drills in.",
+ skipToStep: 14,
+ showDetailsButton: true,
+ },
+ // 10 Β· DETAIL
+ {
+ element: 'button[title="auto layout"]',
+ popover: {
+ title: "Auto-layout",
+ description: "Rearranges your operators into a tidy left-to-right pipeline.",
+ side: "bottom",
+ align: "center",
+ popoverClass: "tutorial-no-progress",
+ },
+ title: "Step β Auto-layout",
+ aiHint: "Detail (middle group): auto-layout button.",
+ },
+ // 11 Β· DETAIL
+ {
+ element: 'button[title="add a comment"]',
+ popover: {
+ title: "Add Comment",
+ description: "Drops a sticky-note comment box on the canvas.",
+ side: "bottom",
+ align: "center",
+ popoverClass: "tutorial-no-progress",
+ },
+ title: "Step β Add Comment",
+ aiHint: "Detail (middle group): add-comment button.",
+ },
+ // 12 Β· DETAIL
+ {
+ element: 'button[title="undo"]',
+ popover: {
+ title: "βΆ Undo",
+ description: "Steps back through your last edit.",
+ side: "bottom",
+ align: "center",
+ popoverClass: "tutorial-no-progress",
+ },
+ title: "Step β Undo",
+ aiHint: "Detail (middle group): undo button.",
+ },
+ // 13 Β· DETAIL
+ {
+ element: 'button[title="redo"]',
+ popover: {
+ title: "β· Redo",
+ description: "Replays an undone edit.",
+ side: "bottom",
+ align: "center",
+ popoverClass: "tutorial-no-progress",
+ },
+ title: "Step β Redo",
+ aiHint: "Detail (middle group): redo button.",
+ },
+ // 14 Β· MAIN 4/8 (branch: Next skips to idx 18, Learn more drills in)
+ {
+ element: "#execution-buttons",
+ popover: {
+ title: "Toolbar Β· run controls",
+ description: "Where you launch and watch your workflow execute.",
+ side: "bottom",
+ align: "end",
+ progressText: "Step 4 / 8",
+ },
+ title: "Step 4 β Right group overview",
+ aiHint:
+ "Right toolbar group overview. Default Next skips past Computing Unit / Share / Run (idx 15-17) to the result panel; 'Learn more' drills in.",
+ skipToStep: 18,
+ showDetailsButton: true,
+ },
+ // 15 Β· DETAIL
+ {
+ element: "#texera-compute-unit-selection",
+ popover: {
+ title: "Computing Unit",
+ description: "The worker that runs your workflow. Pick one before hitting Run.",
+ side: "bottom",
+ align: "center",
+ popoverClass: "tutorial-no-progress",
+ },
+ title: "Step β Computing Unit",
+ aiHint: "Detail (right group): computing-unit selector.",
+ },
+ // 16 Β· DETAIL
+ {
+ element: "#share-button",
+ popover: {
+ title: "Share",
+ description: "Invite collaborators to view or co-edit live.",
+ side: "bottom",
+ align: "center",
+ popoverClass: "tutorial-no-progress",
+ },
+ title: "Step β Share",
+ aiHint: "Detail (right group): share button.",
+ },
+ // 17 Β· DETAIL
+ {
+ element: "#run-button",
+ popover: {
+ title: "βΆ Run",
+ description: "Launches your workflow on the selected Computing Unit.",
+ side: "bottom",
+ align: "end",
+ popoverClass: "tutorial-no-progress",
+ },
+ title: "Step β Run",
+ aiHint: "Detail (right group): the Run button.",
+ },
+ // 18 Β· MAIN 5/8
+ {
+ element: 'li[data-tutorial="open-result-panel"]',
+ popover: {
+ title: "Result panel",
+ description: "After a run, click here to see the rows and charts.",
+ side: "top",
+ align: "start",
+ progressText: "Step 5 / 8",
+ },
+ title: "Step 5 β Result Panel",
+ aiHint: "Orientation: result-panel toggle in the bottom-left.",
+ },
+ // 19 Β· MAIN 6/8
+ {
+ element: "texera-mini-map",
+ popover: {
+ title: "Mini-map",
+ description: "Bottom-right helper for navigating large workflows.",
+ side: "top",
+ align: "end",
+ progressText: "Step 6 / 8",
+ },
+ title: "Step 6 β Mini-map",
+ aiHint: "Orientation: mini-map widget in the bottom-right.",
+ },
+ // 20 Β· MAIN 7/8
+ {
+ element: "#agent-docked-button",
+ popover: {
+ title: "π€ AI Agent",
+ description: "Bottom-right chat button. Ask Texera's AI to help you build, debug, or explain your workflow.",
+ side: "left",
+ align: "center",
+ progressText: "Step 7 / 8",
+ },
+ title: "Step 7 β AI Agent",
+ aiHint: "Orientation: docked AI Agent launcher in the bottom-right.",
+ },
+ // 21 Β· MAIN 8/8
+ {
+ popover: {
+ title: "Ready to build?",
+ description: "That's the layout. Click Done when you're ready.",
+ progressText: "Step 8 / 8",
+ },
+ title: "Step 8 β Hand-off",
+ aiHint:
+ "Final narration. Done triggers the chain-confirmation popover that asks the user whether to launch build-simple.",
+ },
+];
+
+export const OVERVIEW_WORKSPACE_FLOW: TutorialFlow = {
+ id: "overview-workspace",
+ name: "Workspace overview",
+ shortDesc: "8-step tour of the workspace. Each toolbar group offers an optional deep dive into individual icons.",
+ difficulty: "intro",
+ estimatedMinutes: 2,
+ badge: {
+ id: "explorer",
+ emoji: "π§",
+ name: "Explorer",
+ description: "Took the workspace overview tour and learned where everything lives.",
+ hue: "#52c41a",
+ },
+ steps: STEPS,
+ chainTo: "build-simple",
+};
diff --git a/frontend/src/app/workspace/service/tutorial/flows/public-workflow.ts b/frontend/src/app/workspace/service/tutorial/flows/public-workflow.ts
new file mode 100644
index 00000000000..3396298004f
--- /dev/null
+++ b/frontend/src/app/workspace/service/tutorial/flows/public-workflow.ts
@@ -0,0 +1,42 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import type { TutorialFlow } from "./index";
+
+/**
+ * Cross-page flow: open a public workflow from the hub, clone it, run it.
+ * Stub for now β needs hub-side selectors and the cross-route resume plumbing.
+ */
+export const PUBLIC_WORKFLOW_FLOW: TutorialFlow = {
+ id: "public-workflow",
+ name: "Run a public workflow",
+ shortDesc: "Browse, clone, and run a community workflow end-to-end.",
+ difficulty: "easy",
+ estimatedMinutes: 2,
+ comingSoon: true,
+ prerequisites: ["hub-tour"],
+ badge: {
+ id: "voyager",
+ emoji: "π",
+ name: "Community Voyager",
+ description: "Cloned and ran your first public workflow.",
+ hue: "#eb2f96",
+ },
+ steps: [],
+};
diff --git a/frontend/src/app/workspace/service/tutorial/tutorial-progress.spec.ts b/frontend/src/app/workspace/service/tutorial/tutorial-progress.spec.ts
new file mode 100644
index 00000000000..93675b715bd
--- /dev/null
+++ b/frontend/src/app/workspace/service/tutorial/tutorial-progress.spec.ts
@@ -0,0 +1,94 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { DEFAULT_PROGRESS, loadProgress, saveProgress, TutorialProgress } from "./tutorial-progress";
+
+const STORAGE_KEY = "texera-tutorial-progress";
+const LEGACY_SEEN_KEY = "texera-tutorial-seen";
+
+describe("tutorial-progress", () => {
+ beforeEach(() => {
+ localStorage.removeItem(STORAGE_KEY);
+ localStorage.removeItem(LEGACY_SEEN_KEY);
+ });
+
+ describe("loadProgress", () => {
+ it("returns DEFAULT_PROGRESS when localStorage is empty", () => {
+ expect(loadProgress()).toEqual(DEFAULT_PROGRESS);
+ });
+
+ it("migrates the legacy `texera-tutorial-seen=1` flag into seenWelcome=true", () => {
+ localStorage.setItem(LEGACY_SEEN_KEY, "1");
+
+ const progress = loadProgress();
+
+ expect(progress.seenWelcome).toBe(true);
+ expect(progress.earnedBadges).toEqual(DEFAULT_PROGRESS.earnedBadges);
+ expect(progress.xp).toBe(DEFAULT_PROGRESS.xp);
+ });
+
+ it("returns DEFAULT_PROGRESS when the legacy flag is anything other than '1'", () => {
+ localStorage.setItem(LEGACY_SEEN_KEY, "0");
+
+ expect(loadProgress().seenWelcome).toBe(false);
+ });
+
+ it("resets to defaults but preserves seenWelcome when schema version is stale", () => {
+ const stale = { version: 0, seenWelcome: true, earnedBadges: ["should-be-dropped"] };
+ localStorage.setItem(STORAGE_KEY, JSON.stringify(stale));
+
+ const progress = loadProgress();
+
+ expect(progress.seenWelcome).toBe(true);
+ expect(progress.earnedBadges).toEqual([]);
+ expect(progress.version).toBe(DEFAULT_PROGRESS.version);
+ });
+
+ it("returns DEFAULT_PROGRESS when localStorage holds malformed JSON", () => {
+ localStorage.setItem(STORAGE_KEY, "{not-json");
+
+ expect(loadProgress()).toEqual(DEFAULT_PROGRESS);
+ });
+ });
+
+ describe("saveProgress + loadProgress round-trip", () => {
+ it("persists every field unchanged", () => {
+ const sample: TutorialProgress = {
+ current: { flowId: "overview-workspace", stepIndex: 3 },
+ completed: { "build-simple": { completedAt: 123456, durationMs: 78000 } },
+ earnedBadges: ["explorer", "speed-runner"],
+ xp: 240,
+ microsEarned: { "build-simple": [0, 1, 2] },
+ seenWelcome: true,
+ version: DEFAULT_PROGRESS.version,
+ };
+
+ saveProgress(sample);
+
+ expect(loadProgress()).toEqual(sample);
+ });
+
+ it("survives an unrelated localStorage write between save and load", () => {
+ saveProgress({ ...DEFAULT_PROGRESS, xp: 50 });
+ localStorage.setItem("some-other-key", "noise");
+
+ expect(loadProgress().xp).toBe(50);
+ });
+ });
+});
diff --git a/frontend/src/app/workspace/service/tutorial/tutorial-progress.ts b/frontend/src/app/workspace/service/tutorial/tutorial-progress.ts
new file mode 100644
index 00000000000..91c5d9ba853
--- /dev/null
+++ b/frontend/src/app/workspace/service/tutorial/tutorial-progress.ts
@@ -0,0 +1,75 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+export interface TutorialProgress {
+ /** In-flight flow + step. Cleared when the user finishes or fully resets. */
+ current?: { flowId: string; stepIndex: number };
+ /** flowId β completion record. */
+ completed: Record;
+ /** Earned badge ids (includes flow badges + bonus badges like speed-runner / graduate). */
+ earnedBadges: string[];
+ /** Total XP across all flows + replays. */
+ xp: number;
+ /** flowId β step indices that have already fired their micro-reward. Prevents
+ * replays from awarding XP again for already-completed steps. */
+ microsEarned: Record;
+ /** Whether the user has dismissed (or completed) the welcome flow picker. */
+ seenWelcome: boolean;
+ /** Schema version β bump when shape changes; older payloads are reset. */
+ version: number;
+}
+
+const STORAGE_KEY = "texera-tutorial-progress";
+const CURRENT_VERSION = 1;
+
+export const DEFAULT_PROGRESS: TutorialProgress = {
+ completed: {},
+ earnedBadges: [],
+ xp: 0,
+ microsEarned: {},
+ seenWelcome: false,
+ version: CURRENT_VERSION,
+};
+
+export function loadProgress(): TutorialProgress {
+ try {
+ const raw = localStorage.getItem(STORAGE_KEY);
+ if (!raw) {
+ // Migrate the v1 "seen" key so returning users aren't re-prompted.
+ const legacy = localStorage.getItem("texera-tutorial-seen") === "1";
+ return { ...DEFAULT_PROGRESS, seenWelcome: legacy };
+ }
+ const parsed = JSON.parse(raw) as Partial;
+ if (parsed.version !== CURRENT_VERSION) {
+ // Older schema β reset gracefully but keep the seen flag if present.
+ return { ...DEFAULT_PROGRESS, seenWelcome: !!parsed.seenWelcome };
+ }
+ return { ...DEFAULT_PROGRESS, ...parsed };
+ } catch {
+ return { ...DEFAULT_PROGRESS };
+ }
+}
+
+export function saveProgress(p: TutorialProgress): void {
+ try {
+ localStorage.setItem(STORAGE_KEY, JSON.stringify(p));
+ } catch {
+ /* localStorage may be unavailable in some environments */
+ }
+}
diff --git a/frontend/src/app/workspace/service/tutorial/tutorial.service.ts b/frontend/src/app/workspace/service/tutorial/tutorial.service.ts
index e142c924e22..0c6ad374ce9 100644
--- a/frontend/src/app/workspace/service/tutorial/tutorial.service.ts
+++ b/frontend/src/app/workspace/service/tutorial/tutorial.service.ts
@@ -26,242 +26,27 @@ import { ExecuteWorkflowService } from "../execute-workflow/execute-workflow.ser
import { ExecutionState } from "../../types/execute-workflow.interface";
import { ComputingUnitStatusService } from "../../../common/service/computing-unit/computing-unit-status/computing-unit-status.service";
import { ComputingUnitState } from "../../../common/type/computing-unit-connection.interface";
-
-type AutoAdvanceTrigger =
- | "operatorAdded"
- | "operatorSelected"
- | "linkAdded"
- | "executionStarted"
- | "propertyChanged"
- | "computingUnitConnected";
-
-export interface TutorialStep extends DriveStep {
- /** Short label used by the AI chat for context */
- title: string;
- /** Prompt fragment given to the AI when the user asks a question on this step */
- aiHint: string;
- /** If set, advance automatically when this event fires on the workflow */
- autoAdvanceOn?: AutoAdvanceTrigger;
- /** If true, clicking the highlighted element advances to the next step */
- advanceOnClick?: boolean;
+import {
+ AutoAdvanceTrigger,
+ BONUS_BADGES,
+ BadgeDef,
+ FLOWS,
+ GRADUATE_BADGE,
+ SPEED_RUNNER_BADGE,
+ TutorialFlow,
+ TutorialStep,
+ getFlowById,
+} from "./flows";
+import { DEFAULT_PROGRESS, TutorialProgress, loadProgress, saveProgress } from "./tutorial-progress";
+const XP_PER_STEP = 10;
+const SPEED_RUNNER_THRESHOLD_MS = 90_000;
+
+export interface BadgeUnlockEvent {
+ badge: BadgeDef;
+ flowName: string;
}
-export const TUTORIAL_STEPS: TutorialStep[] = [
- {
- element: "texera-operator-menu",
- popover: {
- title: "π Welcome to your toolbox",
- description:
- "This panel on the LEFT is your toolbox. Each tile here is an operator β a tiny building block that does one thing to your data. We're going to wire two of them together!",
- side: "right",
- align: "start",
- },
- title: "Step 1 β The Operator Panel",
- aiHint: "The user just opened Texera and is being introduced to the operator panel on the left. Intro only β user clicks Next to advance.",
- },
- {
- element: 'nz-collapse-panel[data-group-name="Data Input"]',
- popover: {
- title: "First, let's get some data π₯",
- description:
- 'Click "Data Input" to open the category. Sources are operators that pull data into your workflow β CSV files, databases, APIs.',
- side: "right",
- align: "start",
- },
- title: "Step 2 β Find a Source",
- aiHint: "The user is locating the Data Input category to find a source operator.",
- advanceOnClick: true,
- },
- {
- element: '.operator-label[data-operator-type="CSVFileScan"]',
- popover: {
- title: "Drag it onto the canvas π―",
- description:
- "Grab CSV File Scan and drop it onto the empty canvas on the right. This little box's job: read rows from a CSV file.",
- side: "right",
- align: "start",
- },
- title: "Step 3 β Drag CSV File Scan",
- aiHint: "The user is dragging the CSV File Scan source operator from the operator panel onto the canvas.",
- autoAdvanceOn: "operatorAdded",
- },
- {
- element: '[model-id^="CSVFileScan-operator-"]',
- popover: {
- title: "Nice! Now give it a click",
- description:
- "There's your CSV File Scan on the canvas. Click it once to select it β that's how we tell Texera \"I want to configure this one\".",
- side: "bottom",
- align: "center",
- },
- title: "Step 4 β Click the Operator",
- aiHint: "The user needs to click the just-placed CSV File Scan operator on the canvas to open its property editor.",
- autoAdvanceOn: "operatorSelected",
- },
- {
- element: 'li[data-tutorial="open-property-panel"]',
- popover: {
- title: "Open its settings βοΈ",
- description:
- "See the little form icon at the top-right? Click it to slide open the settings panel on the right side. (Already open? We'll just skip ahead.)",
- side: "left",
- align: "center",
- },
- title: "Step 5 β Open the Property Panel",
- aiHint: "The user needs to click the small form icon at the top-right of the canvas to expand the (currently collapsed) property panel. Auto-skipped when the panel is already open.",
- advanceOnClick: true,
- },
- {
- element: 'button[data-tutorial="file-select-button"]',
- popover: {
- title: "Pick a file π",
- description: "Click Select File to open the dataset browser β that's where your CSVs live.",
- side: "left",
- align: "center",
- },
- title: "Step 6 β Open the File Picker",
- aiHint: "The user is about to click the Select File button to open the dataset selection modal.",
- advanceOnClick: true,
- },
- {
- element: ".ant-modal-content",
- popover: {
- title: "Browse your data",
- description:
- "Pick a dataset on the left, expand a version, then double-click any .csv. The modal closes itself and the file name auto-fills β no typing required β¨.",
- side: "top",
- align: "end",
- },
- title: "Step 7 β Pick a CSV File",
- aiHint: "The user is choosing a CSV file from the dataset selection modal. After they pick one, the modal closes and the fileName property updates.",
- autoAdvanceOn: "propertyChanged",
- },
- {
- element: 'nz-collapse-panel[data-group-name="Data Cleaning"]',
- popover: {
- title: "Time for a second operator π§°",
- description:
- 'Back to the left panel. Click "Data Cleaning" to open that category β we\'re about to chain a second operator after our source.',
- side: "right",
- align: "start",
- },
- title: "Step 8 β Find the Data Cleaning Category",
- aiHint: "The user needs to expand the Data Cleaning category in the operator panel to find Limit.",
- advanceOnClick: true,
- },
- {
- element: '.operator-label[data-operator-type="Limit"]',
- popover: {
- title: "Drag Limit onto the canvas",
- description:
- "Grab Limit and drop it on the canvas next to CSV File Scan. Limit caps your output to the first N rows β perfect for a quick peek.",
- side: "right",
- align: "start",
- },
- title: "Step 9 β Drag Limit",
- aiHint: "The user is dragging the Limit operator onto the canvas as a second operator.",
- autoAdvanceOn: "operatorAdded",
- },
- {
- element: "texera-workflow-editor",
- popover: {
- title: "Wire them up π",
- description:
- "Drag from the βΆ port on the right edge of CSV File Scan over to the port on the left edge of Limit. That edge tells Texera \"send rows this way\".",
- side: "over",
- align: "center",
- },
- title: "Step 10 β Connect Operators",
- aiHint: "The user is dragging an edge from CSV File Scan's output port to Limit's input port.",
- autoAdvanceOn: "linkAdded",
- },
- {
- element: '[model-id^="Limit-operator-"]',
- popover: {
- title: "Click Limit to configure it",
- description:
- "Click the Limit box on the canvas. The property panel on the right will swap over to its settings β each operator has its own.",
- side: "bottom",
- align: "center",
- },
- title: "Step 11 β Click Limit",
- aiHint: "The user needs to click the just-connected Limit operator on the canvas to switch the property editor to its fields.",
- autoAdvanceOn: "operatorSelected",
- },
- {
- element: 'li[data-tutorial="open-property-panel"]',
- popover: {
- title: "Open its settings",
- description:
- "If the panel collapsed again, click the form icon at the top-right to reopen it. (Already open? Skippingβ¦)",
- side: "left",
- align: "center",
- },
- title: "Step 12 β Open the Property Panel (Limit)",
- aiHint: "Same as step 5: the user clicks the form icon to reopen the property panel for the Limit operator. Auto-skipped when the panel is already open.",
- advanceOnClick: true,
- },
- {
- element: ".property-editor-form",
- popover: {
- title: "How many rows? π’",
- description:
- "Type a number into the Limit field β that's the max rows you'll see. Try 10 for a snappy preview.",
- side: "left",
- align: "start",
- },
- title: "Step 13 β Configure Limit",
- aiHint: "The user is configuring the Limit operator by typing a number in the limit field (max output rows).",
- autoAdvanceOn: "propertyChanged",
- },
- {
- element: "#texera-compute-unit-selection",
- popover: {
- title: "Almost there β pick a Computing Unit β‘",
- description:
- "Before running, click the Computing Unit selector at the top and pick (or start) one. That's the little worker that'll execute your workflow.",
- side: "bottom",
- align: "start",
- },
- title: "Step 14 β Connect a Computing Unit",
- aiHint: "The user needs to select/connect a Computing Unit from the top menu before running the workflow.",
- autoAdvanceOn: "computingUnitConnected",
- },
- {
- element: "#run-button",
- popover: {
- title: "Hit Run! βΆοΈ",
- description: "Once the unit shows Connected, smash that βΆ Run button and watch Texera get to work.",
- side: "bottom",
- align: "start",
- },
- title: "Step 15 β Run the Workflow",
- aiHint: "The user is clicking the Run button at the top to execute the workflow.",
- advanceOnClick: true,
- },
- {
- element: 'li[data-tutorial="open-result-panel"]',
- popover: {
- title: "Open the result panel π",
- description:
- "Your workflow finished β the data is ready! Click this little square icon at the bottom-left to slide open the result panel and see your rows.",
- side: "top",
- align: "start",
- },
- title: "Step 16 β Open the Result Panel",
- aiHint: "The user just ran the workflow. They need to click the 'Open Result Panel' icon (the square / border icon at the bottom-left of the screen) to expand the result panel and view their data.",
- advanceOnClick: true,
- },
- {
- popover: {
- title: "π You did it!",
- description:
- "Your CSV rows are now waiting for you in the result panel. You just built and ran your very first Texera workflow β from empty canvas to real data in under two minutes. Welcome aboard! β¨",
- },
- title: "Step 17 β Celebration",
- aiHint: "Final celebratory step. The user has opened the result panel and can now see their workflow's output. No element is highlighted β the popover is centered like the welcome screen for a clean closing moment.",
- },
-];
+export type { TutorialStep, TutorialFlow, BadgeDef, AutoAdvanceTrigger };
@Injectable({
providedIn: "root",
@@ -269,22 +54,34 @@ export const TUTORIAL_STEPS: TutorialStep[] = [
export class TutorialService implements OnDestroy {
private readonly destroy$ = new Subject();
private driverObj: Driver | null = null;
+ private currentFlow: TutorialFlow | null = null;
private lastActiveIndex = 0;
+ private flowStartedAt = 0;
// One-shot DOM click listener for steps with `advanceOnClick: true`.
private clickAdvanceEl: Element | null = null;
private clickAdvanceHandler: ((ev: Event) => void) | null = null;
+ // ===== Reactive state =====
private readonly isActiveSubject = new BehaviorSubject(false);
public readonly isActive$ = this.isActiveSubject.asObservable();
private readonly currentStepSubject = new BehaviorSubject(0);
public readonly currentStep$ = this.currentStepSubject.asObservable();
- private readonly completedSubject = new Subject();
+ private readonly currentFlowSubject = new BehaviorSubject(null);
+ public readonly currentFlow$ = this.currentFlowSubject.asObservable();
+
+ private readonly completedSubject = new Subject<{ flowId: string }>();
public readonly completed$ = this.completedSubject.asObservable();
- public readonly steps: TutorialStep[] = TUTORIAL_STEPS;
+ private readonly badgeUnlockedSubject = new Subject();
+ public readonly badgeUnlocked$ = this.badgeUnlockedSubject.asObservable();
+
+ private readonly progressSubject = new BehaviorSubject(DEFAULT_PROGRESS);
+ public readonly progress$ = this.progressSubject.asObservable();
+
+ public readonly flows: TutorialFlow[] = FLOWS;
constructor(
private workflowActionService: WorkflowActionService,
@@ -292,9 +89,12 @@ export class TutorialService implements OnDestroy {
private computingUnitStatusService: ComputingUnitStatusService,
private ngZone: NgZone
) {
+ this.progressSubject.next(loadProgress());
this.wireEventListeners();
}
+ // ===== Getters =====
+
get isActive(): boolean {
return this.isActiveSubject.getValue();
}
@@ -304,140 +104,129 @@ export class TutorialService implements OnDestroy {
}
get currentStep(): TutorialStep | null {
- return this.isActive ? (TUTORIAL_STEPS[this.currentStepIndex] ?? null) : null;
+ if (!this.isActive || !this.currentFlow) return null;
+ return this.currentFlow.steps[this.currentStepIndex] ?? null;
+ }
+
+ get currentFlowSnapshot(): TutorialFlow | null {
+ return this.currentFlow;
}
get stepCount(): number {
- return TUTORIAL_STEPS.length;
+ return this.currentFlow?.steps.length ?? 0;
+ }
+
+ get progress(): TutorialProgress {
+ return this.progressSubject.getValue();
}
- start(): void {
+ // ===== Flow control =====
+
+ /** Start a flow. Re-runs of completed flows act as replays (no second badge, sparkles still fire). */
+ start(flowId: string, startAt: number = 0): void {
+ const flow = getFlowById(flowId);
+ if (!flow) {
+ // eslint-disable-next-line no-console
+ console.warn(`[tutorial] unknown flow "${flowId}"`);
+ return;
+ }
+ if (flow.comingSoon || flow.steps.length === 0) {
+ return;
+ }
+
if (this.driverObj) {
this.driverObj.destroy();
this.driverObj = null;
}
- this.lastActiveIndex = 0;
- this.currentStepSubject.next(0);
+ this.resetOperatorMenuCategories();
+ const safeStart = Math.max(0, Math.min(startAt, flow.steps.length - 1));
+ this.currentFlow = flow;
+ this.currentFlowSubject.next(flow);
+ this.lastActiveIndex = safeStart;
+ this.flowStartedAt = Date.now();
+ this.currentStepSubject.next(safeStart);
this.isActiveSubject.next(true);
- const driverSteps: DriveStep[] = TUTORIAL_STEPS.map(step => ({
- element: step.element,
- popover: step.popover,
- }));
+ // Persist the start so a refresh mid-tour can offer to resume.
+ this.updateProgress(p => ({ ...p, current: { flowId, stepIndex: safeStart } }));
+
+ const driverSteps: DriveStep[] = flow.steps.map(step => {
+ // skipToStep redirects the default Next button. driver.js exposes onNextClick on Popover, not DriveStep.
+ const popover =
+ typeof step.skipToStep === "number"
+ ? { ...step.popover, onNextClick: () => this.driverObj?.moveTo(step.skipToStep!) }
+ : step.popover;
+ return {
+ element: step.element,
+ popover,
+ };
+ });
- // Log selector resolution so missing targets are obvious in the console.
- // eslint-disable-next-line no-console
- console.info(
- "[tutorial] starting; selector-resolution report:",
- driverSteps.map((s, i) => ({
- idx: i,
- element: s.element,
- found: typeof s.element === "string" ? !!document.querySelector(s.element) : !!s.element,
- }))
- );
-
- this.driverObj = driver({
- showProgress: true,
- // Keep the top-right X button so the user always has an explicit exit,
- // but disarm overlay clicks so accidental clicks on the dim area don't
- // abort the tour.
- allowClose: true,
- overlayClickBehavior: () => {
- /* no-op: clicking the dim overlay does nothing */
- },
- animate: true,
- smoothScroll: true,
- // Generous padding so small spotlights (operator boxes on canvas,
- // small buttons in panels) have visual breathing room and stay easy
- // to click without nicking the dim overlay edge.
- stagePadding: 16,
- stageRadius: 8,
- disableActiveInteraction: false,
- overlayColor: "#000",
- overlayOpacity: 0.65,
- nextBtnText: "Next β",
- prevBtnText: "β Back",
- doneBtnText: "All done! π",
- progressText: "Step {{current}} / {{total}}",
- steps: driverSteps,
- onHighlightStarted: (el, _step, opts) => {
- const idx = opts?.state?.activeIndex ?? 0;
- this.lastActiveIndex = idx;
- this.ngZone.run(() => this.currentStepSubject.next(idx));
- this.detachClickAdvance();
- const step = TUTORIAL_STEPS[idx];
-
- // Force the spotlight target into view. driver.js's `smoothScroll`
- // sometimes misses nested scroll containers (e.g. the operator menu's
- // inner list when a category is scrolled below the fold). After the
- // browser settles the scroll, ask driver.js to re-measure with
- // `refresh()` so the spotlight + popover land at the new position.
- if (el && typeof (el as HTMLElement).scrollIntoView === "function") {
- (el as HTMLElement).scrollIntoView({ block: "center", inline: "nearest" });
- setTimeout(() => this.driverObj?.refresh(), 60);
- }
+ // Skip prebuilt-workflow load on resume so we don't wipe the user's mid-tour canvas.
+ if (flow.prebuiltWorkflow && safeStart === 0) {
+ this.loadPrebuiltWorkflow(flow.prebuiltWorkflow)
+ .catch(err => {
+ // eslint-disable-next-line no-console
+ console.warn(`[tutorial] failed to load prebuilt workflow "${flow.prebuiltWorkflow}":`, err);
+ })
+ .finally(() => this.launchDriver(driverSteps, safeStart));
+ return;
+ }
- // Auto-skip a step whose target doesn't exist (e.g. step 12's "open
- // the property panel" form icon, which only renders when width=0).
- // Re-query after a short delay to give Angular a tick to render, then
- // moveNext if the element is still missing or zero-sized. Never skip
- // the final step β moveNext() on it ends the tour, which makes the
- // celebratory "you're done" popover flash away instantly.
- const isLastStep = idx === TUTORIAL_STEPS.length - 1;
- if (typeof step?.element === "string" && !isLastStep) {
- const selector = step.element;
- setTimeout(() => {
- if (this.currentStepIndex !== idx || !this.driverObj) return;
- const reEl = document.querySelector(selector) as HTMLElement | null;
- const rect = reEl?.getBoundingClientRect();
- const missing = !reEl || !rect || (rect.width === 0 && rect.height === 0);
- if (missing) {
- // eslint-disable-next-line no-console
- console.info(
- `[tutorial] step ${idx + 1} target "${selector}" not found / zero-size; auto-skipping`
- );
- this.ngZone.run(() => this.driverObj?.moveNext());
- }
- }, 250);
- }
+ this.launchDriver(driverSteps, safeStart);
+ }
- // Debug: log the bounding rect of the spotlight target so
- // mis-positioned popovers can be diagnosed at a glance.
- if (el) {
- const rect = (el as HTMLElement).getBoundingClientRect?.();
- // eslint-disable-next-line no-console
- console.info(
- `[tutorial] step ${idx + 1} highlight:`,
- step?.title,
- "β",
- step?.element,
- rect && {
- x: Math.round(rect.x),
- y: Math.round(rect.y),
- w: Math.round(rect.width),
- h: Math.round(rect.height),
- }
- );
- } else if (step?.element) {
- // Only warn when an element was configured but couldn't be found.
- // Steps without `element` are intentionally centered popovers
- // (e.g. the final celebration) β that's not a failure mode.
- // eslint-disable-next-line no-console
- console.warn(`[tutorial] step ${idx + 1} highlight: NO ELEMENT MATCHED for`, step?.element);
- }
- if (step?.advanceOnClick && el) this.attachClickAdvance(el);
- },
- onDestroyed: () => {
- this.detachClickAdvance();
- this.ngZone.run(() => {
- const wasOnLast = this.lastActiveIndex === TUTORIAL_STEPS.length - 1;
- this.driverObj = null;
- this.isActiveSubject.next(false);
- if (wasOnLast) this.completedSubject.next();
- });
- },
+ /** Load a fixture from `assets/tutorial-workflows/`. Resolves after JointJS has had a tick to paint. */
+ private loadPrebuiltWorkflow(name: string): Promise {
+ return fetch(`assets/tutorial-workflows/${name}.json`)
+ .then(r => {
+ if (!r.ok) throw new Error(`HTTP ${r.status}`);
+ return r.json();
+ })
+ .then(workflow => {
+ this.ngZone.run(() => this.workflowActionService.reloadWorkflow(workflow));
+ // Wait one paint tick for JointJS so spotlight rects measure correctly.
+ return new Promise(resolve => setTimeout(resolve, 150));
+ });
+ }
+
+ private launchDriver(driverSteps: DriveStep[], safeStart: number): void {
+ // Construct driver.js outside Angular's zone β its resize / scroll / mutation listeners would
+ // otherwise re-run change detection on every event and make ng-zorro tooltips/waves jitter.
+ this.ngZone.runOutsideAngular(() => {
+ this.driverObj = driver({
+ showProgress: true,
+ allowClose: true,
+ overlayClickBehavior: () => {
+ /* no-op: clicking the dim overlay does nothing */
+ },
+ animate: false,
+ smoothScroll: true,
+ stagePadding: 16,
+ stageRadius: 8,
+ disableActiveInteraction: false,
+ overlayColor: "#000",
+ overlayOpacity: 0.65,
+ nextBtnText: "Next β",
+ prevBtnText: "β Back",
+ doneBtnText: "All done! π",
+ progressText: "Step {{current}} / {{total}}",
+ steps: driverSteps,
+ onHighlightStarted: (el, _step, opts) => this.handleHighlight(el, opts),
+ onDestroyed: () => this.handleDestroyed(),
+ });
+ this.driverObj.drive(safeStart);
});
- this.driverObj.drive();
+ }
+
+ /** Continue an in-progress flow (resume from saved stepIndex). */
+ resume(): boolean {
+ const cur = this.progress.current;
+ if (!cur) return false;
+ const flow = getFlowById(cur.flowId);
+ if (!flow || flow.comingSoon || flow.steps.length === 0) return false;
+ this.start(cur.flowId, cur.stepIndex);
+ return true;
}
next(): void {
@@ -453,22 +242,259 @@ export class TutorialService implements OnDestroy {
}
restart(): void {
- this.start();
+ if (this.currentFlow) this.start(this.currentFlow.id);
}
- private autoAdvanceIfMatches(trigger: AutoAdvanceTrigger): void {
- if (!this.isActive || !this.driverObj) return;
- const step = TUTORIAL_STEPS[this.currentStepIndex];
- if (step?.autoAdvanceOn !== trigger) return;
- setTimeout(() => this.ngZone.run(() => this.driverObj?.moveNext()), 700);
+ markWelcomeSeen(): void {
+ this.updateProgress(p => ({ ...p, seenWelcome: true }));
+ }
+
+ /** Wipe all progress β useful for demos / workshops. */
+ resetProgress(): void {
+ this.progressSubject.next({ ...DEFAULT_PROGRESS });
+ saveProgress(this.progressSubject.getValue());
+ }
+
+ // ===== Private helpers =====
+
+ /** Collapse every expanded operator-menu category so "Click Data Input to open the category" makes sense regardless of prior state. */
+ private resetOperatorMenuCategories(): void {
+ const menu = document.querySelector("texera-operator-menu");
+ if (!menu) return;
+ menu.querySelectorAll(".ant-collapse-item-active > .ant-collapse-header").forEach(header => {
+ (header as HTMLElement).click();
+ });
+ }
+
+ /** Inject a "Learn more" button next to Next on group-overview steps. Idempotent. */
+ private injectShowDetailsButton(stepIdx: number): void {
+ const popover = document.querySelector(".driver-popover");
+ if (!popover || popover.querySelector(".tutorial-show-details-btn")) return;
+
+ const btn = document.createElement("button");
+ btn.type = "button";
+ btn.className = "tutorial-show-details-btn";
+ btn.textContent = "Learn more";
+ btn.addEventListener("click", () => {
+ if (this.currentStepIndex !== stepIdx) return;
+ this.driverObj?.moveNext();
+ });
+
+ // Prefer sitting in the footer alongside Next/Skip; fall back to the
+ // description block if driver.js's footer markup changes in the future.
+ const navBtns = popover.querySelector(".driver-popover-navigation-btns");
+ if (navBtns) {
+ navBtns.insertBefore(btn, navBtns.firstChild);
+ return;
+ }
+ const description = popover.querySelector(".driver-popover-description");
+ description?.appendChild(btn);
+ }
+
+ /** True if the box is inside the viewport AND every ancestor scroll container's clip rect. */
+ private isFullyVisible(el: HTMLElement): boolean {
+ const r = el.getBoundingClientRect();
+ if (r.top < 0 || r.left < 0 || r.bottom > window.innerHeight || r.right > window.innerWidth) {
+ return false;
+ }
+ let p: HTMLElement | null = el.parentElement;
+ while (p && p !== document.body) {
+ const style = getComputedStyle(p);
+ const scrollsY = /auto|scroll|hidden|clip/.test(style.overflowY);
+ const scrollsX = /auto|scroll|hidden|clip/.test(style.overflowX);
+ if (scrollsY || scrollsX) {
+ const pr = p.getBoundingClientRect();
+ if (
+ (scrollsY && (r.top < pr.top || r.bottom > pr.bottom)) ||
+ (scrollsX && (r.left < pr.left || r.right > pr.right))
+ ) {
+ return false;
+ }
+ }
+ p = p.parentElement;
+ }
+ return true;
+ }
+
+ private updateProgress(updater: (p: TutorialProgress) => TutorialProgress): void {
+ const next = updater(this.progressSubject.getValue());
+ this.progressSubject.next(next);
+ saveProgress(next);
+ }
+
+ private handleHighlight(el: Element | undefined, opts: { state?: { activeIndex?: number } } | undefined): void {
+ const idx = opts?.state?.activeIndex ?? 0;
+ this.lastActiveIndex = idx;
+ this.ngZone.run(() => this.currentStepSubject.next(idx));
+ this.detachClickAdvance();
+ const step = this.currentFlow?.steps[idx];
+ if (!step || !this.currentFlow) return;
+
+ // Collapse expanded operator-menu categories before highlighting a TOP-LEVEL category, so prior
+ // expansions don't push the target down. Skip for nested sub-groups (the parent must stay open,
+ // otherwise the sub-group rect goes 0Γ0 and auto-skip jumps past the step). Refresh after the
+ // ~300ms collapse animation since driver.js measures synchronously.
+ if (typeof step.element === "string" && /nz-collapse-panel\[data-group-name=/.test(step.element)) {
+ const target = document.querySelector(step.element) as HTMLElement | null;
+ const isTopLevel = target?.getAttribute("data-depth") === "0";
+ if (isTopLevel) {
+ this.resetOperatorMenuCategories();
+ setTimeout(() => this.driverObj?.refresh(), 350);
+ }
+ }
+
+ // Persist the new position so refresh mid-tour resumes here.
+ this.updateProgress(p => ({
+ ...p,
+ current: { flowId: this.currentFlow!.id, stepIndex: idx },
+ }));
+
+ if (step.showDetailsButton) {
+ setTimeout(() => this.injectShowDetailsButton(idx), 0);
+ }
+
+ // Scroll only when not already fully visible β keeps fixed toolbar icons flicker-free.
+ if (el && typeof (el as HTMLElement).scrollIntoView === "function") {
+ if (!this.isFullyVisible(el as HTMLElement)) {
+ (el as HTMLElement).scrollIntoView({ block: "center", inline: "nearest" });
+ setTimeout(() => this.driverObj?.refresh(), 60);
+ }
+ }
+
+ // Auto-skip steps whose target is missing / zero-size. Skip the final step (moveNext ends the tour).
+ const isLastStep = idx === this.currentFlow.steps.length - 1;
+ if (typeof step.element === "string" && !isLastStep) {
+ const selector = step.element;
+ setTimeout(() => {
+ if (this.currentStepIndex !== idx || !this.driverObj) return;
+ const reEl = document.querySelector(selector) as HTMLElement | null;
+ const rect = reEl?.getBoundingClientRect();
+ const missing = !reEl || !rect || (rect.width === 0 && rect.height === 0);
+ if (missing) {
+ this.ngZone.run(() => this.driverObj?.moveNext());
+ }
+ }, 250);
+ }
+
+ // Fire a micro-reward (sparkles + XP) β but only the first time the user
+ // hits this step. Replays don't keep stacking XP.
+ this.fireMicroRewardIfFirstTime(idx);
+
+ if (!el && step.element) {
+ // eslint-disable-next-line no-console
+ console.warn(`[tutorial] step ${idx + 1} highlight: NO ELEMENT MATCHED for`, step.element);
+ }
+ if (step.advanceOnClick && el) this.attachClickAdvance(el);
+ }
+
+ private handleDestroyed(): void {
+ this.detachClickAdvance();
+ this.ngZone.run(() => {
+ const flow = this.currentFlow;
+ const wasOnLast = flow ? this.lastActiveIndex === flow.steps.length - 1 : false;
+ this.driverObj = null;
+ this.isActiveSubject.next(false);
+ this.currentFlowSubject.next(null);
+ if (wasOnLast && flow) this.finalizeFlowCompletion(flow);
+ else {
+ // User skipped mid-flow β keep `current` so the resume toast can fire later.
+ }
+ this.currentFlow = null;
+ });
+ }
+
+ private finalizeFlowCompletion(flow: TutorialFlow): void {
+ const durationMs = Date.now() - this.flowStartedAt;
+ const isFirstCompletion = !this.progress.completed[flow.id];
+
+ this.updateProgress(p => {
+ const completed = { ...p.completed, [flow.id]: { completedAt: Date.now(), durationMs } };
+ const earned = new Set(p.earnedBadges);
+ const newlyEarned: BadgeDef[] = [];
+
+ if (isFirstCompletion && !earned.has(flow.badge.id)) {
+ earned.add(flow.badge.id);
+ newlyEarned.push(flow.badge);
+ }
+ // Speed runner bonus
+ if (durationMs < SPEED_RUNNER_THRESHOLD_MS && !earned.has(SPEED_RUNNER_BADGE.id)) {
+ earned.add(SPEED_RUNNER_BADGE.id);
+ newlyEarned.push(SPEED_RUNNER_BADGE);
+ }
+ // Graduate bonus β only when every primary flow badge is earned.
+ const flowBadgeIds = FLOWS.map(f => f.badge.id);
+ const hasAllFlowBadges = flowBadgeIds.every(id => earned.has(id));
+ if (hasAllFlowBadges && !earned.has(GRADUATE_BADGE.id)) {
+ earned.add(GRADUATE_BADGE.id);
+ newlyEarned.push(GRADUATE_BADGE);
+ }
+
+ // Fire badge-unlocked notifications after the state has been written.
+ setTimeout(() => {
+ newlyEarned.forEach(badge => this.badgeUnlockedSubject.next({ badge, flowName: flow.name }));
+ }, 0);
+
+ return {
+ ...p,
+ completed,
+ earnedBadges: Array.from(earned),
+ current: undefined,
+ };
+ });
+
+ this.completedSubject.next({ flowId: flow.id });
+ }
+
+ private fireMicroRewardIfFirstTime(stepIdx: number): void {
+ if (!this.currentFlow) return;
+ const flowId = this.currentFlow.id;
+ const microsForFlow = this.progress.microsEarned[flowId] ?? [];
+ if (microsForFlow.includes(stepIdx)) return; // already rewarded
+
+ this.updateProgress(p => ({
+ ...p,
+ xp: p.xp + XP_PER_STEP,
+ microsEarned: {
+ ...p.microsEarned,
+ [flowId]: [...(p.microsEarned[flowId] ?? []), stepIdx],
+ },
+ }));
+ this.spawnSparkleBurst();
+ }
+
+ /** Pure-DOM sparkle + XP burst, anchored top-right so it never overlaps the spotlight. */
+ private spawnSparkleBurst(): void {
+ const burst = document.createElement("div");
+ burst.className = "tutorial-sparkle-burst";
+
+ // Bias particle trajectories to fly DOWN-LEFT (into the workspace),
+ // not up-right (off-screen) since the burst sits in the top-right corner.
+ const angles = [110, 140, 170, 200, 230, 260];
+ angles.forEach((angle, i) => {
+ const radius = 18 + Math.random() * 8;
+ const dx = Math.cos((angle * Math.PI) / 180) * radius;
+ const dy = Math.sin((angle * Math.PI) / 180) * radius;
+ const sp = document.createElement("span");
+ sp.className = "sparkle-particle";
+ sp.textContent = i % 2 === 0 ? "β¦" : "β§";
+ sp.style.setProperty("--dx", `${dx}px`);
+ sp.style.setProperty("--dy", `${dy}px`);
+ sp.style.animationDelay = `${i * 30}ms`;
+ burst.appendChild(sp);
+ });
+
+ const xp = document.createElement("div");
+ xp.className = "xp-float";
+ xp.textContent = `+${XP_PER_STEP} XP`;
+ burst.appendChild(xp);
+
+ document.body.appendChild(burst);
+ setTimeout(() => burst.remove(), 1300);
}
private attachClickAdvance(el: Element): void {
this.clickAdvanceEl = el;
this.clickAdvanceHandler = () => {
- // Let the click's side-effects finish β collapse panel expand, ng-zorro
- // modal mount animation, etc. β before driver.js measures the next
- // target's bounding rect. 500ms covers ant-modal's ~300ms fade-in.
setTimeout(() => this.ngZone.run(() => this.driverObj?.moveNext()), 500);
};
el.addEventListener("click", this.clickAdvanceHandler, { once: true });
@@ -482,6 +508,20 @@ export class TutorialService implements OnDestroy {
this.clickAdvanceHandler = null;
}
+ private autoAdvanceIfMatches(trigger: AutoAdvanceTrigger): void {
+ if (!this.isActive || !this.driverObj || !this.currentFlow) return;
+ const step = this.currentFlow.steps[this.currentStepIndex];
+ if (step?.autoAdvanceOn !== trigger) return;
+ // When a drag-to-canvas finishes, fold the operator menu category back
+ // immediately β waiting until the next category step is too late: the
+ // category visually stays open during the entire intermediate steps
+ // (click operator, open property panel, configure, ...).
+ if (trigger === "operatorAdded") {
+ this.resetOperatorMenuCategories();
+ }
+ setTimeout(() => this.ngZone.run(() => this.driverObj?.moveNext()), 700);
+ }
+
private wireEventListeners(): void {
this.workflowActionService
.getTexeraGraph()
diff --git a/frontend/src/assets/tutorial-workflows/movies-filter.json b/frontend/src/assets/tutorial-workflows/movies-filter.json
new file mode 100644
index 00000000000..5a00a1acab0
--- /dev/null
+++ b/frontend/src/assets/tutorial-workflows/movies-filter.json
@@ -0,0 +1,102 @@
+{
+ "name": "Tutorial β Movies (filtered)",
+ "description": "Pre-built starter workflow used by the chart-building tour. CSV β Filter(year > 1960).",
+ "wid": null,
+ "creationTime": null,
+ "lastModifiedTime": null,
+ "isPublished": 0,
+ "readonly": false,
+ "content": {
+ "operators": [
+ {
+ "operatorID": "CSVFileScan-operator-171d5ebd-a2cb-4a8c-997c-135eae5a4978",
+ "operatorType": "CSVFileScan",
+ "operatorVersion": "N/A",
+ "operatorProperties": {
+ "fileEncoding": "UTF_8",
+ "customDelimiter": ",",
+ "hasHeader": true,
+ "fileName": "/texera/test/v1/movies (1).csv"
+ },
+ "inputPorts": [],
+ "outputPorts": [
+ {
+ "portID": "output-0",
+ "displayName": "",
+ "disallowMultiInputs": false,
+ "isDynamicPort": false
+ }
+ ],
+ "showAdvanced": false,
+ "isDisabled": false,
+ "customDisplayName": "CSV File Scan",
+ "dynamicInputPorts": false,
+ "dynamicOutputPorts": false
+ },
+ {
+ "operatorID": "Filter-operator-83c55041-a9f9-4a0c-8ceb-c9b63e5e27bc",
+ "operatorType": "Filter",
+ "operatorVersion": "N/A",
+ "operatorProperties": {
+ "predicates": [
+ {
+ "attribute": "year",
+ "condition": ">",
+ "value": "1960"
+ }
+ ]
+ },
+ "inputPorts": [
+ {
+ "portID": "input-0",
+ "displayName": "",
+ "disallowMultiInputs": false,
+ "isDynamicPort": false,
+ "dependencies": []
+ }
+ ],
+ "outputPorts": [
+ {
+ "portID": "output-0",
+ "displayName": "",
+ "disallowMultiInputs": false,
+ "isDynamicPort": false
+ }
+ ],
+ "showAdvanced": false,
+ "isDisabled": false,
+ "customDisplayName": "Filter",
+ "dynamicInputPorts": false,
+ "dynamicOutputPorts": false
+ }
+ ],
+ "operatorPositions": {
+ "CSVFileScan-operator-171d5ebd-a2cb-4a8c-997c-135eae5a4978": {
+ "x": 350,
+ "y": 200
+ },
+ "Filter-operator-83c55041-a9f9-4a0c-8ceb-c9b63e5e27bc": {
+ "x": 500,
+ "y": 200
+ }
+ },
+ "links": [
+ {
+ "linkID": "link-3d2aef7b-0cb5-49b4-9811-71f74e871841",
+ "source": {
+ "operatorID": "CSVFileScan-operator-171d5ebd-a2cb-4a8c-997c-135eae5a4978",
+ "portID": "output-0"
+ },
+ "target": {
+ "operatorID": "Filter-operator-83c55041-a9f9-4a0c-8ceb-c9b63e5e27bc",
+ "portID": "input-0"
+ }
+ }
+ ],
+ "commentBoxes": [],
+ "settings": {
+ "dataTransferBatchSize": 400,
+ "executionMode": "PIPELINED"
+ }
+ }
+}
diff --git a/frontend/src/styles.scss b/frontend/src/styles.scss
index db70acdda56..c060d3b8815 100644
--- a/frontend/src/styles.scss
+++ b/frontend/src/styles.scss
@@ -19,85 +19,12 @@
@import "@ali-hm/angular-tree-component/css/angular-tree-component.css";
-/* driver.js β purely cosmetic. DO NOT override z-index here; driver.js
- uses z-index: 1000000000 by design so the spotlight always wins. */
-.driver-popover {
- max-width: 360px;
-}
-.driver-popover-title {
- font-weight: 600;
-}
-.driver-popover-description b {
- color: #1890ff;
-}
-
-/* Welcome popover β a centered, fancier variant of the standard driver.js
- popover used for the first-time greeting. Wider, with a soft gradient and
- a primary-coloured CTA so "Start building your first workflow" reads as
- the obvious next step. */
-.driver-popover.tutorial-welcome-popover {
- max-width: 460px;
- background: linear-gradient(135deg, #ffffff 0%, #f0f5ff 100%);
- border: 2px solid #1890ff;
- box-shadow: 0 16px 48px rgba(24, 144, 255, 0.32);
- animation: tutorial-welcome-pop 0.5s cubic-bezier(0.18, 1.25, 0.4, 1);
-
- .driver-popover-title {
- font-size: 20px;
- color: #1890ff;
- text-align: center;
- }
-
- .driver-popover-footer button.driver-popover-next-btn {
- background: #1890ff;
- border-color: #1890ff;
- color: #fff;
- font-weight: 600;
- padding: 6px 18px;
- border-radius: 8px;
- box-shadow: 0 4px 14px rgba(24, 144, 255, 0.45);
- text-shadow: none;
- transition: transform 0.15s ease, box-shadow 0.15s ease;
-
- &:hover {
- background: #40a9ff;
- border-color: #40a9ff;
- transform: translateY(-1px);
- box-shadow: 0 6px 18px rgba(24, 144, 255, 0.6);
- }
- }
-
- .tutorial-welcome-emoji {
- font-size: 54px;
- margin-bottom: 8px;
- display: inline-block;
- animation: tutorial-welcome-wave 1.4s ease-in-out infinite;
- transform-origin: 70% 80%;
- }
-}
-
-@keyframes tutorial-welcome-pop {
- 0% { opacity: 0; transform: scale(0.85); }
- 60% { opacity: 1; transform: scale(1.04); }
- 100% { opacity: 1; transform: scale(1); }
-}
-
-@keyframes tutorial-welcome-wave {
- 0%, 100% { transform: rotate(-14deg); }
- 50% { transform: rotate(14deg); }
-}
-
-/* driver.js by default sets pointer-events:none on every element outside the
- highlighted one. That breaks drag-and-drop tutorial steps (user can grab the
- operator label but the canvas refuses the drop). Re-enable interaction
- everywhere while the tour is active β the dim overlay still gives the visual
- cue, but the page stays fully usable. */
-body.driver-active *:not(.driver-overlay) {
- pointer-events: auto !important;
-}
-body.driver-active .driver-overlay {
- pointer-events: none !important;
-}
+/* Tutorial mode β driver.js popover styling, body.driver-active overrides,
+ sparkle-burst animation. All rules are gated by `body.driver-active` or
+ the `.tutorial-*` / `.driver-popover.tutorial-*` namespace, so they have
+ no effect when no tour is running. See the partial for why these rules
+ must live at the global root rather than in component stylesheets. */
+@import "tutorial-driver-overrides";
.ant-menu-item,
.ant-menu-submenu-title,