@x-plat/design-system 0.15.6 → 0.16.1

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.
@@ -0,0 +1,338 @@
1
+ "use strict";
2
+ var __create = Object.create;
3
+ var __defProp = Object.defineProperty;
4
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
5
+ var __getOwnPropNames = Object.getOwnPropertyNames;
6
+ var __getProtoOf = Object.getPrototypeOf;
7
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
8
+ var __export = (target, all) => {
9
+ for (var name in all)
10
+ __defProp(target, name, { get: all[name], enumerable: true });
11
+ };
12
+ var __copyProps = (to, from, except, desc) => {
13
+ if (from && typeof from === "object" || typeof from === "function") {
14
+ for (let key of __getOwnPropNames(from))
15
+ if (!__hasOwnProp.call(to, key) && key !== except)
16
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
17
+ }
18
+ return to;
19
+ };
20
+ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
21
+ // If the importer is in node compatibility mode or this is not an ESM
22
+ // file that has been converted to a CommonJS file using a Babel-
23
+ // compatible transform (i.e. "__esModule" has not been set), then set
24
+ // "default" to the CommonJS "module.exports" for node compatibility.
25
+ isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
26
+ mod
27
+ ));
28
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
29
+
30
+ // src/components/Tour/index.ts
31
+ var Tour_exports = {};
32
+ __export(Tour_exports, {
33
+ Tour: () => Tour_default
34
+ });
35
+ module.exports = __toCommonJS(Tour_exports);
36
+
37
+ // src/components/Tour/Tour.tsx
38
+ var import_react3 = __toESM(require("react"), 1);
39
+
40
+ // src/tokens/hooks/Portal.tsx
41
+ var import_react_dom = __toESM(require("react-dom"), 1);
42
+ var Portal = ({ children, container }) => {
43
+ if (typeof document === "undefined") return null;
44
+ return import_react_dom.default.createPortal(children, container ?? document.body);
45
+ };
46
+ Portal.displayName = "Portal";
47
+ var Portal_default = Portal;
48
+
49
+ // src/tokens/hooks/useAutoPosition.ts
50
+ var import_react = __toESM(require("react"), 1);
51
+ var TRIGGER_GAP = 8;
52
+ var computePlacement = (triggerRect, popW, popH, clip) => {
53
+ const roomBelow = clip.bottom - triggerRect.bottom - TRIGGER_GAP;
54
+ const roomAbove = triggerRect.top - clip.top - TRIGGER_GAP;
55
+ let direction;
56
+ let top;
57
+ let maxHeight = null;
58
+ if (popH <= roomBelow) {
59
+ direction = "bottom";
60
+ top = triggerRect.bottom + TRIGGER_GAP;
61
+ } else if (popH <= roomAbove) {
62
+ direction = "top";
63
+ top = triggerRect.top - TRIGGER_GAP - popH;
64
+ } else {
65
+ const room = Math.max(roomBelow, roomAbove, 0);
66
+ if (roomBelow >= roomAbove) {
67
+ direction = "bottom";
68
+ top = triggerRect.bottom + TRIGGER_GAP;
69
+ } else {
70
+ direction = "top";
71
+ top = triggerRect.top - TRIGGER_GAP - room;
72
+ }
73
+ maxHeight = room;
74
+ }
75
+ let left = triggerRect.left;
76
+ if (left + popW > clip.right - 8) {
77
+ left = triggerRect.right - popW;
78
+ }
79
+ if (left < clip.left + 8) left = clip.left + 8;
80
+ return {
81
+ direction,
82
+ top,
83
+ left,
84
+ maxHeight
85
+ };
86
+ };
87
+
88
+ // src/tokens/hooks/useOverlayKeyboard.ts
89
+ var import_react2 = __toESM(require("react"), 1);
90
+ var FOCUSABLE = [
91
+ "a[href]",
92
+ "button:not([disabled])",
93
+ "input:not([disabled]):not([type='hidden'])",
94
+ "select:not([disabled])",
95
+ "textarea:not([disabled])",
96
+ "[tabindex]:not([tabindex='-1'])"
97
+ ].join(",");
98
+ var focusableIn = (el) => Array.from(el.querySelectorAll(FOCUSABLE)).filter(
99
+ // 화면에 없는 것은 제외 (display:none 등)
100
+ (n) => n.offsetWidth > 0 || n.offsetHeight > 0 || n === document.activeElement
101
+ );
102
+ var useEscapeKey = (enabled, onEscape) => {
103
+ import_react2.default.useEffect(() => {
104
+ if (!enabled) return;
105
+ const onKey = (e) => {
106
+ if (e.key !== "Escape") return;
107
+ if (e.defaultPrevented) return;
108
+ e.preventDefault();
109
+ onEscape();
110
+ };
111
+ document.addEventListener("keydown", onKey);
112
+ return () => document.removeEventListener("keydown", onKey);
113
+ }, [enabled, onEscape]);
114
+ };
115
+ var useFocusTrap = (containerRef, enabled, options = {}) => {
116
+ const { trap = false, initialFocus } = options;
117
+ const restoreRef = import_react2.default.useRef(null);
118
+ import_react2.default.useEffect(() => {
119
+ if (!enabled) return;
120
+ restoreRef.current = document.activeElement;
121
+ const raf = requestAnimationFrame(() => {
122
+ const el = containerRef.current;
123
+ if (!el) return;
124
+ const target = initialFocus?.current ?? focusableIn(el)[0] ?? el;
125
+ if (!target.hasAttribute("tabindex") && !focusableIn(el).includes(target)) {
126
+ target.setAttribute("tabindex", "-1");
127
+ }
128
+ target.focus({ preventScroll: true });
129
+ });
130
+ return () => {
131
+ cancelAnimationFrame(raf);
132
+ const prev = restoreRef.current;
133
+ if (prev && document.contains(prev)) prev.focus({ preventScroll: true });
134
+ };
135
+ }, [enabled, containerRef, initialFocus]);
136
+ import_react2.default.useEffect(() => {
137
+ if (!enabled || !trap) return;
138
+ const onKey = (e) => {
139
+ if (e.key !== "Tab") return;
140
+ const el = containerRef.current;
141
+ if (!el) return;
142
+ const items = focusableIn(el);
143
+ if (items.length === 0) {
144
+ e.preventDefault();
145
+ return;
146
+ }
147
+ const first = items[0];
148
+ const last = items[items.length - 1];
149
+ const active = document.activeElement;
150
+ if (e.shiftKey && (active === first || !el.contains(active))) {
151
+ e.preventDefault();
152
+ last.focus();
153
+ } else if (!e.shiftKey && (active === last || !el.contains(active))) {
154
+ e.preventDefault();
155
+ first.focus();
156
+ }
157
+ };
158
+ document.addEventListener("keydown", onKey);
159
+ return () => document.removeEventListener("keydown", onKey);
160
+ }, [enabled, trap, containerRef]);
161
+ };
162
+
163
+ // ../../node_modules/clsx/dist/clsx.mjs
164
+ function r(e) {
165
+ var t, f, n = "";
166
+ if ("string" == typeof e || "number" == typeof e) n += e;
167
+ else if ("object" == typeof e) if (Array.isArray(e)) {
168
+ var o = e.length;
169
+ for (t = 0; t < o; t++) e[t] && (f = r(e[t])) && (n && (n += " "), n += f);
170
+ } else for (f in e) e[f] && (n && (n += " "), n += f);
171
+ return n;
172
+ }
173
+ function clsx() {
174
+ for (var e, t, f = 0, n = "", o = arguments.length; f < o; f++) (e = arguments[f]) && (t = r(e)) && (n && (n += " "), n += t);
175
+ return n;
176
+ }
177
+ var clsx_default = clsx;
178
+
179
+ // src/components/Tour/Tour.tsx
180
+ var import_jsx_runtime = require("react/jsx-runtime");
181
+ var VIEWPORT_MARGIN = 16;
182
+ var DEFAULT_PADDING = 8;
183
+ var clamp = (v, min, max) => Math.max(min, Math.min(v, max));
184
+ var resolve = (target) => {
185
+ if (typeof target === "string") return document.querySelector(target);
186
+ return target.current;
187
+ };
188
+ var Tour = (props) => {
189
+ const {
190
+ open,
191
+ steps,
192
+ onClose,
193
+ current,
194
+ onStepChange,
195
+ nextLabel = "\uB2E4\uC74C",
196
+ prevLabel = "\uC774\uC804",
197
+ skipLabel = "\uAC74\uB108\uB6F0\uAE30",
198
+ doneLabel = "\uB2E4 \uBD24\uC5B4\uC694"
199
+ } = props;
200
+ const [uncontrolled, setUncontrolled] = import_react3.default.useState(0);
201
+ const index = current ?? uncontrolled;
202
+ const step = steps[index];
203
+ const isLast = index === steps.length - 1;
204
+ const spotRef = import_react3.default.useRef(null);
205
+ const cardRef = import_react3.default.useRef(null);
206
+ const [targetFound, setTargetFound] = import_react3.default.useState(true);
207
+ const goTo = import_react3.default.useCallback(
208
+ (next) => {
209
+ if (current === void 0) setUncontrolled(next);
210
+ onStepChange?.(next);
211
+ },
212
+ [current, onStepChange]
213
+ );
214
+ useEscapeKey(open, () => onClose("skip"));
215
+ useFocusTrap(cardRef, open, { trap: true });
216
+ import_react3.default.useEffect(() => {
217
+ if (!open || !step) return;
218
+ const el = resolve(step.target);
219
+ setTargetFound(!!el);
220
+ el?.scrollIntoView({ block: "center", inline: "nearest", behavior: "smooth" });
221
+ }, [open, step]);
222
+ const place = import_react3.default.useCallback(() => {
223
+ const spot = spotRef.current;
224
+ const card = cardRef.current;
225
+ if (!spot || !card || !step) return;
226
+ const el = resolve(step.target);
227
+ const pad = step.padding ?? DEFAULT_PADDING;
228
+ let hole;
229
+ if (el) {
230
+ const r2 = el.getBoundingClientRect();
231
+ hole = {
232
+ top: r2.top - pad,
233
+ left: r2.left - pad,
234
+ width: r2.width + pad * 2,
235
+ height: r2.height + pad * 2
236
+ };
237
+ spot.style.visibility = "visible";
238
+ } else {
239
+ hole = { top: window.innerHeight / 2, left: window.innerWidth / 2, width: 0, height: 0 };
240
+ spot.style.visibility = "hidden";
241
+ }
242
+ spot.style.top = `${hole.top}px`;
243
+ spot.style.left = `${hole.left}px`;
244
+ spot.style.width = `${hole.width}px`;
245
+ spot.style.height = `${hole.height}px`;
246
+ const placed = computePlacement(
247
+ {
248
+ top: hole.top,
249
+ bottom: hole.top + hole.height,
250
+ left: hole.left,
251
+ right: hole.left + hole.width
252
+ },
253
+ card.offsetWidth,
254
+ Math.max(card.offsetHeight, card.scrollHeight),
255
+ {
256
+ top: VIEWPORT_MARGIN,
257
+ bottom: window.innerHeight - VIEWPORT_MARGIN,
258
+ left: VIEWPORT_MARGIN,
259
+ right: window.innerWidth - VIEWPORT_MARGIN
260
+ }
261
+ );
262
+ const limit = window.innerHeight - VIEWPORT_MARGIN * 2;
263
+ const cardH = Math.min(placed.maxHeight ?? card.offsetHeight, limit);
264
+ const cardW = card.offsetWidth;
265
+ card.style.maxHeight = `${cardH}px`;
266
+ card.style.top = `${clamp(placed.top, VIEWPORT_MARGIN, window.innerHeight - VIEWPORT_MARGIN - cardH)}px`;
267
+ card.style.left = `${clamp(placed.left, VIEWPORT_MARGIN, window.innerWidth - VIEWPORT_MARGIN - cardW)}px`;
268
+ }, [step]);
269
+ import_react3.default.useLayoutEffect(() => {
270
+ if (!open) return;
271
+ place();
272
+ const t = setTimeout(place, 400);
273
+ return () => clearTimeout(t);
274
+ }, [open, place]);
275
+ import_react3.default.useEffect(() => {
276
+ if (!open) return;
277
+ const onMove = () => place();
278
+ window.addEventListener("scroll", onMove, { passive: true, capture: true });
279
+ window.addEventListener("resize", onMove, { passive: true });
280
+ return () => {
281
+ window.removeEventListener("scroll", onMove, true);
282
+ window.removeEventListener("resize", onMove);
283
+ };
284
+ }, [open, place]);
285
+ if (!open || !step) return null;
286
+ return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Portal_default, { children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "lib-xplat-tour", role: "presentation", children: [
287
+ !targetFound && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "lib-xplat-tour-dim" }),
288
+ /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { ref: spotRef, className: "lib-xplat-tour-spotlight", "aria-hidden": true }),
289
+ /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
290
+ "div",
291
+ {
292
+ ref: cardRef,
293
+ className: "lib-xplat-tour-card",
294
+ role: "dialog",
295
+ "aria-modal": "true",
296
+ "aria-label": typeof step.title === "string" ? step.title : "\uD654\uBA74 \uC548\uB0B4",
297
+ children: [
298
+ /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "tour-card-progress", "aria-hidden": true, children: [
299
+ index + 1,
300
+ " / ",
301
+ steps.length
302
+ ] }),
303
+ step.title && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "tour-card-title", children: step.title }),
304
+ step.description && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "tour-card-description", children: step.description }),
305
+ /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "tour-card-actions", children: [
306
+ /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", className: "tour-skip", onClick: () => onClose("skip"), children: skipLabel }),
307
+ /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "tour-card-nav", children: [
308
+ index > 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
309
+ "button",
310
+ {
311
+ type: "button",
312
+ className: clsx_default("tour-nav", "secondary"),
313
+ onClick: () => goTo(index - 1),
314
+ children: prevLabel
315
+ }
316
+ ),
317
+ /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
318
+ "button",
319
+ {
320
+ type: "button",
321
+ className: clsx_default("tour-nav", "primary"),
322
+ onClick: () => isLast ? onClose("done") : goTo(index + 1),
323
+ children: isLast ? doneLabel : nextLabel
324
+ }
325
+ )
326
+ ] })
327
+ ] })
328
+ ]
329
+ }
330
+ )
331
+ ] }) });
332
+ };
333
+ Tour.displayName = "Tour";
334
+ var Tour_default = Tour;
335
+ // Annotate the CommonJS export names for ESM import in node:
336
+ 0 && (module.exports = {
337
+ Tour
338
+ });
@@ -0,0 +1,117 @@
1
+ @charset "UTF-8";
2
+
3
+ /* src/components/Tour/tour.scss */
4
+ .lib-xplat-tour {
5
+ position: fixed;
6
+ inset: 0;
7
+ z-index: 1100;
8
+ pointer-events: none;
9
+ }
10
+ .lib-xplat-tour-dim {
11
+ position: fixed;
12
+ inset: 0;
13
+ background-color: var(--semantic-interaction-overlay-50);
14
+ pointer-events: auto;
15
+ }
16
+ .lib-xplat-tour-spotlight {
17
+ position: fixed;
18
+ border-radius: var(--spacing-radius-md);
19
+ box-shadow: 0 0 0 9999px var(--semantic-interaction-overlay-50);
20
+ pointer-events: auto;
21
+ transition:
22
+ top 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94),
23
+ left 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94),
24
+ width 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94),
25
+ height 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94);
26
+ }
27
+ .lib-xplat-tour-card {
28
+ position: fixed;
29
+ pointer-events: auto;
30
+ box-sizing: border-box;
31
+ width: 320px;
32
+ max-width: calc(100vw - var(--spacing-space-8));
33
+ overflow-y: auto;
34
+ padding: var(--spacing-space-4);
35
+ border-radius: var(--spacing-radius-md);
36
+ background-color: var(--semantic-surface-neutral-primary);
37
+ box-shadow: var(--semantic-shadow-lg);
38
+ }
39
+ .lib-xplat-tour-card .tour-card-progress {
40
+ font-family: var(--semantic-typo-caption-2-r-font);
41
+ font-size: var(--semantic-typo-caption-2-r-size);
42
+ line-height: var(--semantic-typo-caption-2-r-lh);
43
+ font-weight: var(--semantic-typo-caption-2-r-weight);
44
+ letter-spacing: var(--semantic-typo-caption-2-r-ls);
45
+ color: var(--semantic-text-tertiary);
46
+ margin-bottom: var(--spacing-space-1);
47
+ }
48
+ .lib-xplat-tour-card .tour-card-title {
49
+ font-family: var(--semantic-typo-label-1-sb-font);
50
+ font-size: var(--semantic-typo-label-1-sb-size);
51
+ line-height: var(--semantic-typo-label-1-sb-lh);
52
+ font-weight: var(--semantic-typo-label-1-sb-weight);
53
+ letter-spacing: var(--semantic-typo-label-1-sb-ls);
54
+ color: var(--semantic-text-primary);
55
+ margin-bottom: var(--spacing-space-2);
56
+ }
57
+ .lib-xplat-tour-card .tour-card-description {
58
+ font-family: var(--semantic-typo-caption-1-r-font);
59
+ font-size: var(--semantic-typo-caption-1-r-size);
60
+ line-height: var(--semantic-typo-caption-1-r-lh);
61
+ font-weight: var(--semantic-typo-caption-1-r-weight);
62
+ letter-spacing: var(--semantic-typo-caption-1-r-ls);
63
+ color: var(--semantic-text-secondary);
64
+ overflow-wrap: anywhere;
65
+ }
66
+ .lib-xplat-tour-card .tour-card-actions {
67
+ display: flex;
68
+ align-items: center;
69
+ justify-content: space-between;
70
+ gap: var(--spacing-space-2);
71
+ margin-top: var(--spacing-space-4);
72
+ }
73
+ .lib-xplat-tour-card .tour-card-nav {
74
+ display: flex;
75
+ gap: var(--spacing-space-2);
76
+ }
77
+ .lib-xplat-tour-card .tour-skip,
78
+ .lib-xplat-tour-card .tour-nav {
79
+ font-family: inherit;
80
+ cursor: pointer;
81
+ border-radius: var(--spacing-radius-sm);
82
+ padding: var(--spacing-space-1) var(--spacing-space-3);
83
+ font-family: var(--semantic-typo-caption-1-r-font);
84
+ font-size: var(--semantic-typo-caption-1-r-size);
85
+ line-height: var(--semantic-typo-caption-1-r-lh);
86
+ font-weight: var(--semantic-typo-caption-1-r-weight);
87
+ letter-spacing: var(--semantic-typo-caption-1-r-ls);
88
+ border: 1px solid transparent;
89
+ background: none;
90
+ transition: background-color 0.15s ease;
91
+ }
92
+ .lib-xplat-tour-card .tour-skip:focus-visible,
93
+ .lib-xplat-tour-card .tour-nav:focus-visible {
94
+ outline: 2px solid var(--semantic-interaction-focus-ring);
95
+ outline-offset: 2px;
96
+ }
97
+ .lib-xplat-tour-card .tour-skip {
98
+ color: var(--semantic-text-tertiary);
99
+ }
100
+ .lib-xplat-tour-card .tour-skip:hover {
101
+ color: var(--semantic-text-secondary);
102
+ background-color: var(--semantic-surface-neutral-secondary);
103
+ }
104
+ .lib-xplat-tour-card .tour-nav.secondary {
105
+ color: var(--semantic-text-secondary);
106
+ border-color: var(--semantic-border-primary);
107
+ }
108
+ .lib-xplat-tour-card .tour-nav.secondary:hover {
109
+ background-color: var(--semantic-surface-neutral-secondary);
110
+ }
111
+ .lib-xplat-tour-card .tour-nav.primary {
112
+ color: var(--semantic-text-inverse);
113
+ background-color: var(--semantic-surface-brand-default);
114
+ }
115
+ .lib-xplat-tour-card .tour-nav.primary:hover {
116
+ background-color: var(--semantic-surface-brand-strong);
117
+ }
@@ -0,0 +1,79 @@
1
+ import * as react_jsx_runtime from 'react/jsx-runtime';
2
+ import React from 'react';
3
+
4
+ interface TourStep {
5
+ /**
6
+ * 가리킬 대상. CSS 선택자(`"#save"`)나 ref 둘 다 받는다.
7
+ *
8
+ * 선택자는 **단계로 넘어갈 때** 찾는다. 그래서 아직 안 그려진 요소도
9
+ * 가리킬 수 있다 — 앞 단계에서 눌러야 나타나는 것 같은 경우.
10
+ */
11
+ target: string | React.RefObject<HTMLElement | null>;
12
+ title?: React.ReactNode;
13
+ description?: React.ReactNode;
14
+ /** 구멍 둘레 여백 (px). 기본 8 */
15
+ padding?: number;
16
+ }
17
+ interface TourProps {
18
+ /** 띄울지 */
19
+ open: boolean;
20
+ /** 단계 목록. 순서대로 돈다 */
21
+ steps: TourStep[];
22
+ /**
23
+ * 닫힐 때. 끝까지 봤는지(`"done"`) 건너뛴 건지(`"skip"`) 알려 준다.
24
+ *
25
+ * "다시 보지 않기" 를 저장할지는 쓰는 쪽이 정한다 — 그건 화면마다 다르고
26
+ * 저장 자리(로컬·서버)도 DS 가 알 바가 아니다.
27
+ */
28
+ onClose: (reason: "done" | "skip") => void;
29
+ /** 지금 단계. 주면 controlled 가 되므로 onStepChange 와 함께 쓴다 */
30
+ current?: number;
31
+ /** 단계가 바뀔 때 */
32
+ onStepChange?: (index: number) => void;
33
+ /** 버튼 글자 */
34
+ nextLabel?: string;
35
+ prevLabel?: string;
36
+ skipLabel?: string;
37
+ doneLabel?: string;
38
+ }
39
+ /**
40
+ * 화면 안내(투어).
41
+ *
42
+ * 화면을 어둡게 덮고 **가리킬 요소만 밝게 뚫어** 설명을 붙인다. 단계로 이어
43
+ * 가며 "어디를 누르면 무엇이 되는지" 를 보여 줄 때 쓴다.
44
+ *
45
+ * ## 구멍은 그림자로 뚫는다
46
+ *
47
+ * 딤을 네 조각으로 깔거나 `clip-path` 로 오려 내는 방법도 있는데, **퍼지지
48
+ * 않는 큰 그림자**가 제일 간단하다:
49
+ *
50
+ * box-shadow: 0 0 0 9999px <딤색>
51
+ *
52
+ * 요소 자리에 투명한 상자를 놓고 그 바깥을 그림자로 덮으면 구멍이 생긴다.
53
+ * 둥근 모서리도 `border-radius` 한 줄로 끝난다.
54
+ *
55
+ * ## 스크롤
56
+ *
57
+ * 대상이 화면 밖이면 `scrollIntoView` 로 데려온다 — 페이지가 스크롤하든
58
+ * 안쪽 상자가 스크롤하든 브라우저가 알아서 한다.
59
+ *
60
+ * 그 뒤 사용자가 굴리면 구멍이 **한 프레임 늦게** 따라온다. 자리를 JS 로
61
+ * 다시 잡아야 해서인데(`position: fixed` 라 스크롤과 함께 안 움직인다),
62
+ * 화면 전체가 어두운 상태라 고르개 때만큼 눈에 띄지 않는다. 자리를 상태가
63
+ * 아니라 DOM 에 직접 써서 리렌더 한 겹은 덜어 둔다.
64
+ *
65
+ * @example
66
+ * <Tour
67
+ * open={firstVisit}
68
+ * onClose={(why) => { if (why === "done") markSeen(); setFirstVisit(false); }}
69
+ * steps={[
70
+ * { target: "#save", title: "저장", description: "여기를 누르면 바로 반영돼요" },
71
+ * ]}
72
+ * />
73
+ */
74
+ declare const Tour: {
75
+ (props: TourProps): react_jsx_runtime.JSX.Element | null;
76
+ displayName: string;
77
+ };
78
+
79
+ export { Tour, type TourStep };
@@ -0,0 +1,79 @@
1
+ import * as react_jsx_runtime from 'react/jsx-runtime';
2
+ import React from 'react';
3
+
4
+ interface TourStep {
5
+ /**
6
+ * 가리킬 대상. CSS 선택자(`"#save"`)나 ref 둘 다 받는다.
7
+ *
8
+ * 선택자는 **단계로 넘어갈 때** 찾는다. 그래서 아직 안 그려진 요소도
9
+ * 가리킬 수 있다 — 앞 단계에서 눌러야 나타나는 것 같은 경우.
10
+ */
11
+ target: string | React.RefObject<HTMLElement | null>;
12
+ title?: React.ReactNode;
13
+ description?: React.ReactNode;
14
+ /** 구멍 둘레 여백 (px). 기본 8 */
15
+ padding?: number;
16
+ }
17
+ interface TourProps {
18
+ /** 띄울지 */
19
+ open: boolean;
20
+ /** 단계 목록. 순서대로 돈다 */
21
+ steps: TourStep[];
22
+ /**
23
+ * 닫힐 때. 끝까지 봤는지(`"done"`) 건너뛴 건지(`"skip"`) 알려 준다.
24
+ *
25
+ * "다시 보지 않기" 를 저장할지는 쓰는 쪽이 정한다 — 그건 화면마다 다르고
26
+ * 저장 자리(로컬·서버)도 DS 가 알 바가 아니다.
27
+ */
28
+ onClose: (reason: "done" | "skip") => void;
29
+ /** 지금 단계. 주면 controlled 가 되므로 onStepChange 와 함께 쓴다 */
30
+ current?: number;
31
+ /** 단계가 바뀔 때 */
32
+ onStepChange?: (index: number) => void;
33
+ /** 버튼 글자 */
34
+ nextLabel?: string;
35
+ prevLabel?: string;
36
+ skipLabel?: string;
37
+ doneLabel?: string;
38
+ }
39
+ /**
40
+ * 화면 안내(투어).
41
+ *
42
+ * 화면을 어둡게 덮고 **가리킬 요소만 밝게 뚫어** 설명을 붙인다. 단계로 이어
43
+ * 가며 "어디를 누르면 무엇이 되는지" 를 보여 줄 때 쓴다.
44
+ *
45
+ * ## 구멍은 그림자로 뚫는다
46
+ *
47
+ * 딤을 네 조각으로 깔거나 `clip-path` 로 오려 내는 방법도 있는데, **퍼지지
48
+ * 않는 큰 그림자**가 제일 간단하다:
49
+ *
50
+ * box-shadow: 0 0 0 9999px <딤색>
51
+ *
52
+ * 요소 자리에 투명한 상자를 놓고 그 바깥을 그림자로 덮으면 구멍이 생긴다.
53
+ * 둥근 모서리도 `border-radius` 한 줄로 끝난다.
54
+ *
55
+ * ## 스크롤
56
+ *
57
+ * 대상이 화면 밖이면 `scrollIntoView` 로 데려온다 — 페이지가 스크롤하든
58
+ * 안쪽 상자가 스크롤하든 브라우저가 알아서 한다.
59
+ *
60
+ * 그 뒤 사용자가 굴리면 구멍이 **한 프레임 늦게** 따라온다. 자리를 JS 로
61
+ * 다시 잡아야 해서인데(`position: fixed` 라 스크롤과 함께 안 움직인다),
62
+ * 화면 전체가 어두운 상태라 고르개 때만큼 눈에 띄지 않는다. 자리를 상태가
63
+ * 아니라 DOM 에 직접 써서 리렌더 한 겹은 덜어 둔다.
64
+ *
65
+ * @example
66
+ * <Tour
67
+ * open={firstVisit}
68
+ * onClose={(why) => { if (why === "done") markSeen(); setFirstVisit(false); }}
69
+ * steps={[
70
+ * { target: "#save", title: "저장", description: "여기를 누르면 바로 반영돼요" },
71
+ * ]}
72
+ * />
73
+ */
74
+ declare const Tour: {
75
+ (props: TourProps): react_jsx_runtime.JSX.Element | null;
76
+ displayName: string;
77
+ };
78
+
79
+ export { Tour, type TourStep };