@umituz/web-dashboard 8.8.0 → 8.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +4 -1
- package/src/domains/calendar/components/Calendar.test.tsx +12 -0
- package/src/domains/calendar/components/Calendar.tsx +1 -1
- package/src/domains/layouts/components/DashboardHeader.tsx +3 -1
- package/src/domains/layouts/types/layout.ts +3 -0
- package/src/domains/layouts/types/sidebar.ts +3 -0
- package/src/domains/layouts/types/user.ts +3 -0
- package/src/domains/layouts/utils/dashboard.test.ts +48 -1
- package/src/domains/layouts/utils/dashboard.ts +61 -10
- package/src/domains/tour/index.ts +3 -0
- package/src/domains/tour/tour.css +187 -0
- package/src/domains/tour/tourEngine.test.ts +40 -0
- package/src/domains/tour/tourEngine.ts +174 -0
- package/src/domains/tour/types.ts +102 -0
- package/src/domains/tour/useProductTour.ts +141 -0
- package/src/index.ts +3 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@umituz/web-dashboard",
|
|
3
|
-
"version": "8.
|
|
3
|
+
"version": "8.9.0",
|
|
4
4
|
"description": "Installable app skeleton for the fleet — layouts, analytics (dependency-free SVG charts), calendar, onboarding flow permissions/module registry; udb-* stylesheet on design-system tokens",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./src/index.ts",
|
|
@@ -47,6 +47,8 @@
|
|
|
47
47
|
"./settings/utils": "./src/domains/settings/utils/index.ts",
|
|
48
48
|
"./timing": "./src/domains/timing/index.ts",
|
|
49
49
|
"./timing/hooks": "./src/domains/timing/hooks/index.ts",
|
|
50
|
+
"./tour": "./src/domains/tour/index.ts",
|
|
51
|
+
"./tour/tour.css": "./src/domains/tour/tour.css",
|
|
50
52
|
"./search": "./src/domains/search/index.ts",
|
|
51
53
|
"./search/utils": "./src/domains/search/searchItems.ts",
|
|
52
54
|
"./styles.css": "./src/styles/dashboard.css"
|
|
@@ -76,6 +78,7 @@
|
|
|
76
78
|
}
|
|
77
79
|
},
|
|
78
80
|
"dependencies": {
|
|
81
|
+
"driver.js": "^1.10.2",
|
|
79
82
|
"lucide-react": "^0.577.0"
|
|
80
83
|
},
|
|
81
84
|
"devDependencies": {
|
|
@@ -49,6 +49,18 @@ describe('Calendar', () => {
|
|
|
49
49
|
expect(screen.getByText('Sunday, March 15, 2026')).toBeTruthy();
|
|
50
50
|
});
|
|
51
51
|
|
|
52
|
+
it('stays in the month view when the day view is not offered', () => {
|
|
53
|
+
render(
|
|
54
|
+
<Calendar
|
|
55
|
+
items={[{ id: 'Expiry', dayKey: '2026-03-15', title: 'Expiry' }]}
|
|
56
|
+
initialCursor="2026-03-10"
|
|
57
|
+
views={['month', 'agenda']}
|
|
58
|
+
/>,
|
|
59
|
+
);
|
|
60
|
+
fireEvent.click(screen.getByRole('button', { name: '2026-03-15' }));
|
|
61
|
+
expect(screen.getByText('March 2026')).toBeTruthy();
|
|
62
|
+
});
|
|
63
|
+
|
|
52
64
|
it('respects a controlled view', () => {
|
|
53
65
|
mount({ view: 'day' });
|
|
54
66
|
expect(screen.getByText('Tuesday, March 10, 2026')).toBeTruthy();
|
|
@@ -106,7 +106,7 @@ export const Calendar = ({
|
|
|
106
106
|
|
|
107
107
|
const handleSelectDay = (dayKey: string) => {
|
|
108
108
|
applyCursor(dayKey);
|
|
109
|
-
if (activeView !== 'day') applyView('day');
|
|
109
|
+
if (activeView !== 'day' && views.includes('day')) applyView('day');
|
|
110
110
|
onSelectDay?.(dayKey);
|
|
111
111
|
};
|
|
112
112
|
|
|
@@ -15,6 +15,7 @@ import type {
|
|
|
15
15
|
} from "../types/layout";
|
|
16
16
|
import type { DashboardNotification } from "../types/notification";
|
|
17
17
|
import type { DashboardUser } from "../types/user";
|
|
18
|
+
import { filterProfileItems } from "../utils/dashboard";
|
|
18
19
|
|
|
19
20
|
interface DashboardHeaderPropsExtended extends DashboardHeaderProps {
|
|
20
21
|
user?: DashboardUser;
|
|
@@ -63,7 +64,8 @@ export const DashboardHeader = ({
|
|
|
63
64
|
const navigate = useNavigate();
|
|
64
65
|
|
|
65
66
|
const unreadCount = notifications.filter((n) => !n.read).length;
|
|
66
|
-
const
|
|
67
|
+
const rawCustomItems = profileItems ?? extraProfileItems;
|
|
68
|
+
const customItems = filterProfileItems(rawCustomItems, user);
|
|
67
69
|
|
|
68
70
|
const handleLogout = async () => {
|
|
69
71
|
try {
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { describe, expect, it } from "vitest";
|
|
2
|
-
import { getActiveSidebarItem, getPageTitle, isPathActive } from "./dashboard";
|
|
2
|
+
import { filterSidebarItems, getActiveSidebarItem, getPageTitle, isPathActive } from "./dashboard";
|
|
3
3
|
|
|
4
4
|
describe("isPathActive", () => {
|
|
5
5
|
it("matches exact paths regardless of end", () => {
|
|
@@ -63,3 +63,50 @@ describe("getPageTitle", () => {
|
|
|
63
63
|
expect(getActiveSidebarItem("/nowhere", nested)).toBeNull();
|
|
64
64
|
});
|
|
65
65
|
});
|
|
66
|
+
|
|
67
|
+
describe("filterSidebarItems & filterProfileItems (Role & Permission Control)", () => {
|
|
68
|
+
it("filters items based on role access", () => {
|
|
69
|
+
const items = [
|
|
70
|
+
{ path: "/overview", label: "Overview" },
|
|
71
|
+
{ path: "/studio", label: "Teacher Studio", roles: ["teacher", "admin"] },
|
|
72
|
+
{ path: "/admin", label: "Admin Panel", roles: ["admin"] },
|
|
73
|
+
];
|
|
74
|
+
|
|
75
|
+
// Student user
|
|
76
|
+
const studentUser = { id: "1", role: "student" };
|
|
77
|
+
const studentItems = items.filter((item) =>
|
|
78
|
+
filterSidebarItems([item], studentUser).length > 0
|
|
79
|
+
);
|
|
80
|
+
expect(studentItems.map((i) => i.path)).toEqual(["/overview"]);
|
|
81
|
+
|
|
82
|
+
// Teacher user
|
|
83
|
+
const teacherUser = { id: "2", role: "teacher" };
|
|
84
|
+
const teacherItems = items.filter((item) =>
|
|
85
|
+
filterSidebarItems([item], teacherUser).length > 0
|
|
86
|
+
);
|
|
87
|
+
expect(teacherItems.map((i) => i.path)).toEqual(["/overview", "/studio"]);
|
|
88
|
+
|
|
89
|
+
// Admin user
|
|
90
|
+
const adminUser = { id: "3", role: "admin" };
|
|
91
|
+
const adminItems = items.filter((item) =>
|
|
92
|
+
filterSidebarItems([item], adminUser).length > 0
|
|
93
|
+
);
|
|
94
|
+
expect(adminItems.map((i) => i.path)).toEqual(["/overview", "/studio", "/admin"]);
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
it("filters items based on explicit permissions", () => {
|
|
98
|
+
const items = [
|
|
99
|
+
{ path: "/public", label: "Public" },
|
|
100
|
+
{ path: "/billing", label: "Billing", permission: "billing.manage" },
|
|
101
|
+
];
|
|
102
|
+
|
|
103
|
+
expect(filterSidebarItems(items, { permissions: [] }).map((i) => i.path)).toEqual(["/public"]);
|
|
104
|
+
expect(
|
|
105
|
+
filterSidebarItems(items, { permissions: ["billing.manage"] }).map((i) => i.path)
|
|
106
|
+
).toEqual(["/public", "/billing"]);
|
|
107
|
+
expect(filterSidebarItems(items, { permissions: ["*"] }).map((i) => i.path)).toEqual([
|
|
108
|
+
"/public",
|
|
109
|
+
"/billing",
|
|
110
|
+
]);
|
|
111
|
+
});
|
|
112
|
+
});
|
|
@@ -65,19 +65,70 @@ export function getPageTitle(
|
|
|
65
65
|
return null;
|
|
66
66
|
}
|
|
67
67
|
|
|
68
|
-
export
|
|
68
|
+
export interface AccessControllableItem {
|
|
69
|
+
enabled?: boolean;
|
|
70
|
+
requiredApp?: "mobile" | "web";
|
|
71
|
+
roles?: readonly string[];
|
|
72
|
+
permission?: string;
|
|
73
|
+
permissions?: readonly string[];
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
export interface AccessControllableUser {
|
|
77
|
+
role?: string;
|
|
78
|
+
roles?: readonly string[];
|
|
79
|
+
permissions?: readonly string[];
|
|
80
|
+
hasMobileApp?: boolean;
|
|
81
|
+
hasWebApp?: boolean;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export function isItemPermitted(
|
|
85
|
+
item: AccessControllableItem,
|
|
86
|
+
user?: AccessControllableUser
|
|
87
|
+
): boolean {
|
|
88
|
+
if (item.enabled === false) return false;
|
|
89
|
+
|
|
90
|
+
if (item.requiredApp === "mobile" && !user?.hasMobileApp) return false;
|
|
91
|
+
if (item.requiredApp === "web" && !user?.hasWebApp) return false;
|
|
92
|
+
|
|
93
|
+
if (item.roles && item.roles.length > 0) {
|
|
94
|
+
const userRoles = [
|
|
95
|
+
...(user?.role ? [user.role] : []),
|
|
96
|
+
...(user?.roles ?? []),
|
|
97
|
+
];
|
|
98
|
+
const hasRole = item.roles.some((r) => userRoles.includes(r));
|
|
99
|
+
if (!hasRole) return false;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
if (item.permission) {
|
|
103
|
+
const userPerms = user?.permissions ?? [];
|
|
104
|
+
if (!userPerms.includes("*") && !userPerms.includes(item.permission)) {
|
|
105
|
+
return false;
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
if (item.permissions && item.permissions.length > 0) {
|
|
110
|
+
const userPerms = user?.permissions ?? [];
|
|
111
|
+
if (!userPerms.includes("*")) {
|
|
112
|
+
const hasAny = item.permissions.some((p) => userPerms.includes(p));
|
|
113
|
+
if (!hasAny) return false;
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
return true;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
export function filterSidebarItems<T extends AccessControllableItem>(
|
|
69
121
|
items: T[],
|
|
70
|
-
user?:
|
|
122
|
+
user?: AccessControllableUser
|
|
71
123
|
): T[] {
|
|
72
|
-
return items.filter((item) =>
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
if (!item.requiredApp) return true;
|
|
76
|
-
if (item.requiredApp === "mobile") return user?.hasMobileApp ?? false;
|
|
77
|
-
if (item.requiredApp === "web") return user?.hasWebApp ?? false;
|
|
124
|
+
return items.filter((item) => isItemPermitted(item, user));
|
|
125
|
+
}
|
|
78
126
|
|
|
79
|
-
|
|
80
|
-
|
|
127
|
+
export function filterProfileItems<T extends AccessControllableItem>(
|
|
128
|
+
items: T[],
|
|
129
|
+
user?: AccessControllableUser
|
|
130
|
+
): T[] {
|
|
131
|
+
return items.filter((item) => isItemPermitted(item, user));
|
|
81
132
|
}
|
|
82
133
|
|
|
83
134
|
export function generateNotificationId(): string {
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
@import "driver.js/dist/driver.css";
|
|
2
|
+
|
|
3
|
+
/* ==========================================================================
|
|
4
|
+
Driver.js Popover Styling — Design System Token Integration
|
|
5
|
+
========================================================================== */
|
|
6
|
+
|
|
7
|
+
.driver-popover {
|
|
8
|
+
background-color: var(--color-surface, #ffffff);
|
|
9
|
+
color: var(--color-ink, #0f172a);
|
|
10
|
+
border-radius: 1rem;
|
|
11
|
+
padding: 1.25rem;
|
|
12
|
+
box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04), 0 0 0 1px rgba(0, 0, 0, 0.08);
|
|
13
|
+
border: 1px solid var(--color-line, rgba(0, 0, 0, 0.08));
|
|
14
|
+
max-width: 380px;
|
|
15
|
+
min-width: 280px;
|
|
16
|
+
font-family: inherit;
|
|
17
|
+
z-index: 1000000000;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
.dark .driver-popover {
|
|
21
|
+
background-color: var(--color-surface, #1e293b);
|
|
22
|
+
color: var(--color-ink, #f8fafc);
|
|
23
|
+
border-color: var(--color-line, rgba(255, 255, 255, 0.12));
|
|
24
|
+
box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.5), 0 10px 10px -5px rgba(0, 0, 0, 0.3), 0 0 0 1px rgba(255, 255, 255, 0.1);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
.driver-popover-title {
|
|
28
|
+
font-size: 1rem;
|
|
29
|
+
font-weight: 700;
|
|
30
|
+
line-height: 1.35;
|
|
31
|
+
color: var(--color-ink, #0f172a);
|
|
32
|
+
margin-bottom: 0.5rem;
|
|
33
|
+
display: flex;
|
|
34
|
+
align-items: center;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
.dark .driver-popover-title {
|
|
38
|
+
color: var(--color-ink, #f8fafc);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
.driver-popover-description {
|
|
42
|
+
font-size: 0.875rem;
|
|
43
|
+
line-height: 1.5;
|
|
44
|
+
color: var(--color-ink-2, #475569);
|
|
45
|
+
margin-bottom: 1.25rem;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
.dark .driver-popover-description {
|
|
49
|
+
color: var(--color-ink-2, #94a3b8);
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
.driver-popover-close-btn {
|
|
53
|
+
top: 1rem;
|
|
54
|
+
right: 1rem;
|
|
55
|
+
color: var(--color-ink-3, #94a3b8);
|
|
56
|
+
font-size: 1.25rem;
|
|
57
|
+
width: 24px;
|
|
58
|
+
height: 24px;
|
|
59
|
+
display: flex;
|
|
60
|
+
align-items: center;
|
|
61
|
+
justify-content: center;
|
|
62
|
+
border-radius: 9999px;
|
|
63
|
+
transition: all 150ms ease;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
.driver-popover-close-btn:hover {
|
|
67
|
+
color: var(--color-ink, #0f172a);
|
|
68
|
+
background-color: rgba(0, 0, 0, 0.05);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
.dark .driver-popover-close-btn:hover {
|
|
72
|
+
color: #ffffff;
|
|
73
|
+
background-color: rgba(255, 255, 255, 0.1);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
.driver-popover-footer {
|
|
77
|
+
display: flex;
|
|
78
|
+
align-items: center;
|
|
79
|
+
justify-content: space-between;
|
|
80
|
+
margin-top: 0.5rem;
|
|
81
|
+
padding-top: 0.75rem;
|
|
82
|
+
border-top: 1px solid var(--color-line, rgba(0, 0, 0, 0.06));
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
.dark .driver-popover-footer {
|
|
86
|
+
border-top-color: var(--color-line, rgba(255, 255, 255, 0.08));
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
.driver-popover-progress-text {
|
|
90
|
+
font-size: 0.75rem;
|
|
91
|
+
font-weight: 600;
|
|
92
|
+
color: var(--color-ink-3, #94a3b8);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
.dark .driver-popover-progress-text {
|
|
96
|
+
color: var(--color-ink-3, #64748b);
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
.driver-popover-navigation-btns {
|
|
100
|
+
display: flex;
|
|
101
|
+
align-items: center;
|
|
102
|
+
gap: 0.5rem;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
.driver-popover-footer-btn {
|
|
106
|
+
font-size: 0.8125rem;
|
|
107
|
+
font-weight: 600;
|
|
108
|
+
padding: 0.4rem 0.85rem;
|
|
109
|
+
border-radius: 9999px;
|
|
110
|
+
cursor: pointer;
|
|
111
|
+
transition: all 150ms cubic-bezier(0.4, 0, 0.2, 1);
|
|
112
|
+
border: 1px solid transparent;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
.driver-popover-prev-btn {
|
|
116
|
+
background-color: transparent;
|
|
117
|
+
color: var(--color-ink-2, #475569);
|
|
118
|
+
border-color: var(--color-line, rgba(0, 0, 0, 0.12));
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
.driver-popover-prev-btn:hover {
|
|
122
|
+
background-color: rgba(0, 0, 0, 0.04);
|
|
123
|
+
color: var(--color-ink, #0f172a);
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
.dark .driver-popover-prev-btn {
|
|
127
|
+
color: var(--color-ink-2, #94a3b8);
|
|
128
|
+
border-color: var(--color-line, rgba(255, 255, 255, 0.15));
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
.dark .driver-popover-prev-btn:hover {
|
|
132
|
+
background-color: rgba(255, 255, 255, 0.06);
|
|
133
|
+
color: #ffffff;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
.driver-popover-next-btn {
|
|
137
|
+
background-color: var(--color-primary, #3b7a5e);
|
|
138
|
+
color: #ffffff;
|
|
139
|
+
border: none;
|
|
140
|
+
box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
.driver-popover-next-btn:hover {
|
|
144
|
+
filter: brightness(1.08);
|
|
145
|
+
transform: translateY(-0.5px);
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
.dark .driver-popover-next-btn {
|
|
149
|
+
background-color: var(--color-primary, #448f6e);
|
|
150
|
+
color: #ffffff;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
.driver-popover-arrow {
|
|
154
|
+
border-color: var(--color-surface, #ffffff);
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
.driver-popover-arrow-side-left {
|
|
158
|
+
border-left-color: var(--color-surface, #ffffff);
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
.driver-popover-arrow-side-right {
|
|
162
|
+
border-right-color: var(--color-surface, #ffffff);
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
.driver-popover-arrow-side-top {
|
|
166
|
+
border-top-color: var(--color-surface, #ffffff);
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
.driver-popover-arrow-side-bottom {
|
|
170
|
+
border-bottom-color: var(--color-surface, #ffffff);
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
.dark .driver-popover-arrow-side-left {
|
|
174
|
+
border-left-color: var(--color-surface, #1e293b);
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
.dark .driver-popover-arrow-side-right {
|
|
178
|
+
border-right-color: var(--color-surface, #1e293b);
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
.dark .driver-popover-arrow-side-top {
|
|
182
|
+
border-top-color: var(--color-surface, #1e293b);
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
.dark .driver-popover-arrow-side-bottom {
|
|
186
|
+
border-bottom-color: var(--color-surface, #1e293b);
|
|
187
|
+
}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import { describe, expect, it } from "vitest";
|
|
2
|
+
import { isTourCompleted, markTourCompleted, resetTourCompletion } from "./tourEngine";
|
|
3
|
+
|
|
4
|
+
describe("Tour Engine & User Isolation", () => {
|
|
5
|
+
it("defaults to false and toggles completed state", () => {
|
|
6
|
+
const tourId = "onboarding_test_tour";
|
|
7
|
+
resetTourCompletion(tourId);
|
|
8
|
+
expect(isTourCompleted(tourId)).toBe(false);
|
|
9
|
+
|
|
10
|
+
markTourCompleted(tourId);
|
|
11
|
+
expect(isTourCompleted(tourId)).toBe(true);
|
|
12
|
+
|
|
13
|
+
resetTourCompletion(tourId);
|
|
14
|
+
expect(isTourCompleted(tourId)).toBe(false);
|
|
15
|
+
});
|
|
16
|
+
|
|
17
|
+
it("isolates tour completion per user", () => {
|
|
18
|
+
const tourId = "role_isolated_tour";
|
|
19
|
+
const userA = "user_student_123";
|
|
20
|
+
const userB = "user_teacher_456";
|
|
21
|
+
|
|
22
|
+
resetTourCompletion(tourId, userA);
|
|
23
|
+
resetTourCompletion(tourId, userB);
|
|
24
|
+
|
|
25
|
+
expect(isTourCompleted(tourId, userA)).toBe(false);
|
|
26
|
+
expect(isTourCompleted(tourId, userB)).toBe(false);
|
|
27
|
+
|
|
28
|
+
markTourCompleted(tourId, userA);
|
|
29
|
+
expect(isTourCompleted(tourId, userA)).toBe(true);
|
|
30
|
+
expect(isTourCompleted(tourId, userB)).toBe(false);
|
|
31
|
+
|
|
32
|
+
markTourCompleted(tourId, userB);
|
|
33
|
+
expect(isTourCompleted(tourId, userA)).toBe(true);
|
|
34
|
+
expect(isTourCompleted(tourId, userB)).toBe(true);
|
|
35
|
+
|
|
36
|
+
resetTourCompletion(tourId, userA);
|
|
37
|
+
expect(isTourCompleted(tourId, userA)).toBe(false);
|
|
38
|
+
expect(isTourCompleted(tourId, userB)).toBe(true);
|
|
39
|
+
});
|
|
40
|
+
});
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
import { driver } from "driver.js";
|
|
2
|
+
import type { Config as DriverConfig, Driver, DriveStep } from "driver.js";
|
|
3
|
+
import type { TourConfig, TourEngineInstance } from "./types";
|
|
4
|
+
|
|
5
|
+
const STORAGE_PREFIX = "umituz_tour_";
|
|
6
|
+
const memoryTourStore = new Map<string, string>();
|
|
7
|
+
|
|
8
|
+
function getStorageKey(tourId: string, userId?: string): string {
|
|
9
|
+
return userId ? `${STORAGE_PREFIX}${userId}_${tourId}` : `${STORAGE_PREFIX}${tourId}`;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Checks whether a given tour has been completed or dismissed by the user.
|
|
14
|
+
*/
|
|
15
|
+
export function isTourCompleted(tourId: string, userId?: string): boolean {
|
|
16
|
+
const key = getStorageKey(tourId, userId);
|
|
17
|
+
if (typeof window === "undefined" || !window.localStorage) {
|
|
18
|
+
return memoryTourStore.get(key) === "completed";
|
|
19
|
+
}
|
|
20
|
+
try {
|
|
21
|
+
return window.localStorage.getItem(key) === "completed";
|
|
22
|
+
} catch {
|
|
23
|
+
return memoryTourStore.get(key) === "completed";
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Marks a tour as completed in localStorage (with in-memory fallback).
|
|
29
|
+
*/
|
|
30
|
+
export function markTourCompleted(tourId: string, userId?: string): void {
|
|
31
|
+
const key = getStorageKey(tourId, userId);
|
|
32
|
+
memoryTourStore.set(key, "completed");
|
|
33
|
+
if (typeof window === "undefined" || !window.localStorage) return;
|
|
34
|
+
try {
|
|
35
|
+
window.localStorage.setItem(key, "completed");
|
|
36
|
+
} catch {
|
|
37
|
+
// ignore storage errors
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Resets the tour completion state so it can be re-run.
|
|
43
|
+
*/
|
|
44
|
+
export function resetTourCompletion(tourId: string, userId?: string): void {
|
|
45
|
+
const key = getStorageKey(tourId, userId);
|
|
46
|
+
memoryTourStore.delete(key);
|
|
47
|
+
if (typeof window === "undefined" || !window.localStorage) return;
|
|
48
|
+
try {
|
|
49
|
+
window.localStorage.removeItem(key);
|
|
50
|
+
} catch {
|
|
51
|
+
// ignore storage errors
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
let activeDriverInstance: Driver | null = null;
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Instantiates and returns a TourEngineInstance wrapping driver.js.
|
|
59
|
+
*/
|
|
60
|
+
export function createProductTour(config: TourConfig): TourEngineInstance {
|
|
61
|
+
const {
|
|
62
|
+
tourId,
|
|
63
|
+
steps,
|
|
64
|
+
labels = {},
|
|
65
|
+
overlayOpacity = 0.65,
|
|
66
|
+
stagePadding = 8,
|
|
67
|
+
stageRadius = 12,
|
|
68
|
+
animate = true,
|
|
69
|
+
smoothScroll = true,
|
|
70
|
+
allowClose = true,
|
|
71
|
+
popoverClass,
|
|
72
|
+
onComplete,
|
|
73
|
+
onSkip,
|
|
74
|
+
onStepChange,
|
|
75
|
+
} = config;
|
|
76
|
+
|
|
77
|
+
const nextBtnDefault = labels.next ?? "İleri";
|
|
78
|
+
const prevBtnDefault = labels.prev ?? "Geri";
|
|
79
|
+
const doneBtnDefault = labels.done ?? "Tamamla";
|
|
80
|
+
const progressTextTemplate = labels.progress ?? "{{current}} / {{total}}";
|
|
81
|
+
|
|
82
|
+
let completedSuccessfully = false;
|
|
83
|
+
|
|
84
|
+
const driveSteps: DriveStep[] = steps.map((step, index) => {
|
|
85
|
+
const isLast = index === steps.length - 1;
|
|
86
|
+
const targetSelector = step.target && step.target !== "body" ? step.target : undefined;
|
|
87
|
+
|
|
88
|
+
const formattedTitle = step.badge
|
|
89
|
+
? `<span style="display:inline-block;padding:2px 8px;font-size:11px;font-weight:700;border-radius:9999px;background-color:rgba(59,122,94,0.15);color:#3b7a5e;margin-right:6px;vertical-align:middle;">${step.badge}</span>${step.title}`
|
|
90
|
+
: step.title;
|
|
91
|
+
|
|
92
|
+
return {
|
|
93
|
+
element: targetSelector,
|
|
94
|
+
popover: {
|
|
95
|
+
title: formattedTitle,
|
|
96
|
+
description: step.description,
|
|
97
|
+
side: step.placement && step.placement !== "center" ? step.placement : undefined,
|
|
98
|
+
align: step.align ?? "center",
|
|
99
|
+
nextBtnText: isLast ? doneBtnDefault : nextBtnDefault,
|
|
100
|
+
prevBtnText: prevBtnDefault,
|
|
101
|
+
showProgress: true,
|
|
102
|
+
progressText: progressTextTemplate,
|
|
103
|
+
onNextClick: (_element, _step, opts) => {
|
|
104
|
+
if (isLast) {
|
|
105
|
+
completedSuccessfully = true;
|
|
106
|
+
markTourCompleted(tourId, config.userId);
|
|
107
|
+
opts.driver.destroy();
|
|
108
|
+
onComplete?.();
|
|
109
|
+
} else {
|
|
110
|
+
opts.driver.moveNext();
|
|
111
|
+
}
|
|
112
|
+
},
|
|
113
|
+
},
|
|
114
|
+
};
|
|
115
|
+
});
|
|
116
|
+
|
|
117
|
+
const driverConfig: DriverConfig = {
|
|
118
|
+
steps: driveSteps,
|
|
119
|
+
animate,
|
|
120
|
+
smoothScroll,
|
|
121
|
+
allowClose,
|
|
122
|
+
overlayOpacity,
|
|
123
|
+
stagePadding,
|
|
124
|
+
stageRadius,
|
|
125
|
+
popoverClass: popoverClass ? `driver-popover ${popoverClass}` : "driver-popover",
|
|
126
|
+
showProgress: true,
|
|
127
|
+
progressText: progressTextTemplate,
|
|
128
|
+
nextBtnText: nextBtnDefault,
|
|
129
|
+
prevBtnText: prevBtnDefault,
|
|
130
|
+
doneBtnText: doneBtnDefault,
|
|
131
|
+
onHighlightStarted: (_element, _step, opts) => {
|
|
132
|
+
const activeIdx = opts.state.activeIndex ?? 0;
|
|
133
|
+
const currentTourStep = steps[activeIdx];
|
|
134
|
+
if (currentTourStep) {
|
|
135
|
+
onStepChange?.(activeIdx, currentTourStep);
|
|
136
|
+
}
|
|
137
|
+
},
|
|
138
|
+
onDestroyed: () => {
|
|
139
|
+
activeDriverInstance = null;
|
|
140
|
+
if (!completedSuccessfully) {
|
|
141
|
+
markTourCompleted(tourId, config.userId);
|
|
142
|
+
onSkip?.();
|
|
143
|
+
}
|
|
144
|
+
},
|
|
145
|
+
};
|
|
146
|
+
|
|
147
|
+
const driverObj = driver(driverConfig);
|
|
148
|
+
|
|
149
|
+
return {
|
|
150
|
+
start: () => {
|
|
151
|
+
if (activeDriverInstance) {
|
|
152
|
+
try {
|
|
153
|
+
activeDriverInstance.destroy();
|
|
154
|
+
} catch {
|
|
155
|
+
// ignore
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
activeDriverInstance = driverObj;
|
|
159
|
+
completedSuccessfully = false;
|
|
160
|
+
driverObj.drive();
|
|
161
|
+
},
|
|
162
|
+
destroy: () => {
|
|
163
|
+
driverObj.destroy();
|
|
164
|
+
},
|
|
165
|
+
next: () => {
|
|
166
|
+
driverObj.moveNext();
|
|
167
|
+
},
|
|
168
|
+
previous: () => {
|
|
169
|
+
driverObj.movePrevious();
|
|
170
|
+
},
|
|
171
|
+
isActive: () => driverObj.isActive(),
|
|
172
|
+
getCurrentStepIndex: () => driverObj.getActiveIndex() ?? 0,
|
|
173
|
+
};
|
|
174
|
+
}
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
export type TourPlacement = "top" | "right" | "bottom" | "left" | "center";
|
|
2
|
+
export type TourAlign = "start" | "center" | "end";
|
|
3
|
+
|
|
4
|
+
export interface TourStep {
|
|
5
|
+
/**
|
|
6
|
+
* DOM selector to attach popover to (e.g. `[data-tour="search-bar"]` or `header`).
|
|
7
|
+
* When omitted or set to `'body'`, the step centers as a modal.
|
|
8
|
+
*/
|
|
9
|
+
target?: string;
|
|
10
|
+
/**
|
|
11
|
+
* Step title displayed in bold in the popover header.
|
|
12
|
+
*/
|
|
13
|
+
title: string;
|
|
14
|
+
/**
|
|
15
|
+
* Step description or HTML body.
|
|
16
|
+
*/
|
|
17
|
+
description: string;
|
|
18
|
+
/**
|
|
19
|
+
* Optional placement side. Defaults to `'center'` if target is omitted, otherwise auto/bottom.
|
|
20
|
+
*/
|
|
21
|
+
placement?: TourPlacement;
|
|
22
|
+
/**
|
|
23
|
+
* Alignment along the side (start, center, end).
|
|
24
|
+
*/
|
|
25
|
+
align?: TourAlign;
|
|
26
|
+
/**
|
|
27
|
+
* Optional small badge text displayed before the title (e.g. "Yeni", "Adım 1").
|
|
28
|
+
*/
|
|
29
|
+
badge?: string;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export interface TourLabels {
|
|
33
|
+
next?: string;
|
|
34
|
+
prev?: string;
|
|
35
|
+
done?: string;
|
|
36
|
+
skip?: string;
|
|
37
|
+
progress?: string; // e.g. "{{current}} / {{total}}"
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
export interface TourConfig {
|
|
41
|
+
tourId: string;
|
|
42
|
+
/**
|
|
43
|
+
* Optional user ID to isolate completion status per user on the same client.
|
|
44
|
+
*/
|
|
45
|
+
userId?: string;
|
|
46
|
+
/**
|
|
47
|
+
* Optional external completion flag (e.g. from backend/database).
|
|
48
|
+
*/
|
|
49
|
+
isCompleted?: boolean;
|
|
50
|
+
steps: TourStep[];
|
|
51
|
+
labels?: TourLabels;
|
|
52
|
+
overlayOpacity?: number;
|
|
53
|
+
stagePadding?: number;
|
|
54
|
+
stageRadius?: number;
|
|
55
|
+
animate?: boolean;
|
|
56
|
+
smoothScroll?: boolean;
|
|
57
|
+
allowClose?: boolean;
|
|
58
|
+
popoverClass?: string;
|
|
59
|
+
onComplete?: () => void;
|
|
60
|
+
onSkip?: () => void;
|
|
61
|
+
onStepChange?: (index: number, step: TourStep) => void;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export interface TourEngineInstance {
|
|
65
|
+
start: () => void;
|
|
66
|
+
destroy: () => void;
|
|
67
|
+
next: () => void;
|
|
68
|
+
previous: () => void;
|
|
69
|
+
isActive: () => boolean;
|
|
70
|
+
getCurrentStepIndex: () => number;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
export interface UseProductTourOptions extends Omit<TourConfig, "onComplete" | "onSkip" | "onStepChange"> {
|
|
74
|
+
/**
|
|
75
|
+
* If true, starts the tour automatically on mount when not yet completed.
|
|
76
|
+
*/
|
|
77
|
+
autoStart?: boolean;
|
|
78
|
+
/**
|
|
79
|
+
* Delay in milliseconds before auto-starting the tour (default: 600ms).
|
|
80
|
+
*/
|
|
81
|
+
autoStartDelayMs?: number;
|
|
82
|
+
/**
|
|
83
|
+
* Optional callback when completed.
|
|
84
|
+
*/
|
|
85
|
+
onComplete?: () => void;
|
|
86
|
+
/**
|
|
87
|
+
* Optional callback when skipped/closed.
|
|
88
|
+
*/
|
|
89
|
+
onSkip?: () => void;
|
|
90
|
+
/**
|
|
91
|
+
* Optional callback when step changes.
|
|
92
|
+
*/
|
|
93
|
+
onStepChange?: (index: number, step: TourStep) => void;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
export interface UseProductTourReturn {
|
|
97
|
+
startTour: (options?: { force?: boolean }) => void;
|
|
98
|
+
restartTour: () => void;
|
|
99
|
+
destroyTour: () => void;
|
|
100
|
+
hasCompleted: boolean;
|
|
101
|
+
isTourActive: boolean;
|
|
102
|
+
}
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
|
|
2
|
+
import type { TourConfig, TourEngineInstance, UseProductTourOptions, UseProductTourReturn } from "./types";
|
|
3
|
+
import { createProductTour, isTourCompleted, resetTourCompletion } from "./tourEngine";
|
|
4
|
+
|
|
5
|
+
export function useProductTour(options: UseProductTourOptions): UseProductTourReturn {
|
|
6
|
+
const {
|
|
7
|
+
tourId,
|
|
8
|
+
userId,
|
|
9
|
+
isCompleted,
|
|
10
|
+
steps,
|
|
11
|
+
labels,
|
|
12
|
+
overlayOpacity,
|
|
13
|
+
stagePadding,
|
|
14
|
+
stageRadius,
|
|
15
|
+
animate,
|
|
16
|
+
smoothScroll,
|
|
17
|
+
allowClose,
|
|
18
|
+
autoStart = false,
|
|
19
|
+
autoStartDelayMs = 600,
|
|
20
|
+
onComplete,
|
|
21
|
+
onSkip,
|
|
22
|
+
onStepChange,
|
|
23
|
+
} = options;
|
|
24
|
+
|
|
25
|
+
const [hasCompleted, setHasCompleted] = useState<boolean>(() => {
|
|
26
|
+
return Boolean(isCompleted) || isTourCompleted(tourId, userId);
|
|
27
|
+
});
|
|
28
|
+
const [isTourActive, setIsTourActive] = useState<boolean>(false);
|
|
29
|
+
const engineRef = useRef<TourEngineInstance | null>(null);
|
|
30
|
+
|
|
31
|
+
useEffect(() => {
|
|
32
|
+
setHasCompleted(Boolean(isCompleted) || isTourCompleted(tourId, userId));
|
|
33
|
+
}, [isCompleted, tourId, userId]);
|
|
34
|
+
|
|
35
|
+
const onCompleteRef = useRef(onComplete);
|
|
36
|
+
onCompleteRef.current = onComplete;
|
|
37
|
+
const onSkipRef = useRef(onSkip);
|
|
38
|
+
onSkipRef.current = onSkip;
|
|
39
|
+
const onStepChangeRef = useRef(onStepChange);
|
|
40
|
+
onStepChangeRef.current = onStepChange;
|
|
41
|
+
|
|
42
|
+
const config: TourConfig = useMemo(
|
|
43
|
+
() => ({
|
|
44
|
+
tourId,
|
|
45
|
+
userId,
|
|
46
|
+
isCompleted,
|
|
47
|
+
steps,
|
|
48
|
+
labels,
|
|
49
|
+
overlayOpacity,
|
|
50
|
+
stagePadding,
|
|
51
|
+
stageRadius,
|
|
52
|
+
animate,
|
|
53
|
+
smoothScroll,
|
|
54
|
+
allowClose,
|
|
55
|
+
onComplete: () => {
|
|
56
|
+
setHasCompleted(true);
|
|
57
|
+
setIsTourActive(false);
|
|
58
|
+
onCompleteRef.current?.();
|
|
59
|
+
},
|
|
60
|
+
onSkip: () => {
|
|
61
|
+
setHasCompleted(true);
|
|
62
|
+
setIsTourActive(false);
|
|
63
|
+
onSkipRef.current?.();
|
|
64
|
+
},
|
|
65
|
+
onStepChange: (index, step) => {
|
|
66
|
+
onStepChangeRef.current?.(index, step);
|
|
67
|
+
},
|
|
68
|
+
}),
|
|
69
|
+
[
|
|
70
|
+
tourId,
|
|
71
|
+
userId,
|
|
72
|
+
isCompleted,
|
|
73
|
+
steps,
|
|
74
|
+
labels,
|
|
75
|
+
overlayOpacity,
|
|
76
|
+
stagePadding,
|
|
77
|
+
stageRadius,
|
|
78
|
+
animate,
|
|
79
|
+
smoothScroll,
|
|
80
|
+
allowClose,
|
|
81
|
+
],
|
|
82
|
+
);
|
|
83
|
+
|
|
84
|
+
const startTour = useCallback(
|
|
85
|
+
(startOptions?: { force?: boolean }) => {
|
|
86
|
+
const force = startOptions?.force ?? false;
|
|
87
|
+
const alreadyDone = Boolean(isCompleted) || isTourCompleted(tourId, userId);
|
|
88
|
+
if (!force && alreadyDone) {
|
|
89
|
+
return;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
if (engineRef.current?.isActive()) {
|
|
93
|
+
engineRef.current.destroy();
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
const instance = createProductTour(config);
|
|
97
|
+
engineRef.current = instance;
|
|
98
|
+
setIsTourActive(true);
|
|
99
|
+
instance.start();
|
|
100
|
+
},
|
|
101
|
+
[config, tourId, userId, isCompleted],
|
|
102
|
+
);
|
|
103
|
+
|
|
104
|
+
const restartTour = useCallback(() => {
|
|
105
|
+
resetTourCompletion(tourId, userId);
|
|
106
|
+
setHasCompleted(false);
|
|
107
|
+
startTour({ force: true });
|
|
108
|
+
}, [tourId, userId, startTour]);
|
|
109
|
+
|
|
110
|
+
const destroyTour = useCallback(() => {
|
|
111
|
+
if (engineRef.current) {
|
|
112
|
+
engineRef.current.destroy();
|
|
113
|
+
setIsTourActive(false);
|
|
114
|
+
}
|
|
115
|
+
}, []);
|
|
116
|
+
|
|
117
|
+
useEffect(() => {
|
|
118
|
+
if (!autoStart) return;
|
|
119
|
+
const alreadyDone = Boolean(isCompleted) || isTourCompleted(tourId, userId);
|
|
120
|
+
if (alreadyDone) return;
|
|
121
|
+
|
|
122
|
+
const timer = window.setTimeout(() => {
|
|
123
|
+
startTour();
|
|
124
|
+
}, autoStartDelayMs);
|
|
125
|
+
|
|
126
|
+
return () => {
|
|
127
|
+
window.clearTimeout(timer);
|
|
128
|
+
if (engineRef.current?.isActive()) {
|
|
129
|
+
engineRef.current.destroy();
|
|
130
|
+
}
|
|
131
|
+
};
|
|
132
|
+
}, [autoStart, autoStartDelayMs, tourId, userId, isCompleted, startTour]);
|
|
133
|
+
|
|
134
|
+
return {
|
|
135
|
+
startTour,
|
|
136
|
+
restartTour,
|
|
137
|
+
destroyTour,
|
|
138
|
+
hasCompleted,
|
|
139
|
+
isTourActive,
|
|
140
|
+
};
|
|
141
|
+
}
|
package/src/index.ts
CHANGED
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
export * from './domains/layouts';
|
|
2
2
|
export * from './domains/settings';
|
|
3
3
|
export * from './domains/calendar';
|
|
4
|
+
export * from './domains/permissions';
|
|
5
|
+
export * from './domains/organization';
|
|
6
|
+
export * from './domains/tour';
|
|
4
7
|
export {
|
|
5
8
|
useAnalytics,
|
|
6
9
|
MetricCard,
|