@panyam/tsappkit 0.7.6 → 0.7.7

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/dist/index.js CHANGED
@@ -1408,6 +1408,378 @@ var Port = class {
1408
1408
  }
1409
1409
  };
1410
1410
 
1411
+ // src/tour/geometry.ts
1412
+ function unionRects(rects) {
1413
+ const rs = rects.filter((r) => r.width > 0 && r.height > 0);
1414
+ if (rs.length <= 1) return rs.map((r) => ({ ...r }));
1415
+ const edges = (pick) => [...new Set(rs.flatMap(pick))].sort((a, b) => a - b);
1416
+ const xs = edges((r) => [r.x, r.x + r.width]);
1417
+ const ys = edges((r) => [r.y, r.y + r.height]);
1418
+ const covered = (cx, cy) => rs.some((r) => cx > r.x && cx < r.x + r.width && cy > r.y && cy < r.y + r.height);
1419
+ const out = [];
1420
+ for (let j = 0; j + 1 < ys.length; j++) {
1421
+ const y = ys[j], height = ys[j + 1] - ys[j], cy = y + height / 2;
1422
+ let start = null;
1423
+ for (let i = 0; i + 1 < xs.length; i++) {
1424
+ const inside = covered((xs[i] + xs[i + 1]) / 2, cy);
1425
+ if (inside && start === null) start = xs[i];
1426
+ if (!inside && start !== null) {
1427
+ out.push({ x: start, y, width: xs[i] - start, height });
1428
+ start = null;
1429
+ }
1430
+ }
1431
+ if (start !== null) out.push({ x: start, y, width: xs[xs.length - 1] - start, height });
1432
+ }
1433
+ return mergeBands(out);
1434
+ }
1435
+ function mergeBands(rs) {
1436
+ const out = [];
1437
+ for (const r of rs) {
1438
+ const above = out.find((o) => o.x === r.x && o.width === r.width && o.y + o.height === r.y);
1439
+ if (above) above.height += r.height;
1440
+ else out.push({ ...r });
1441
+ }
1442
+ return out;
1443
+ }
1444
+ function holePath(w, h, holes) {
1445
+ const n = (v) => Math.round(v * 10) / 10;
1446
+ let d = `M0 0H${n(w)}V${n(h)}H0Z`;
1447
+ for (const r of holes) d += `M${n(r.x)} ${n(r.y)}h${n(r.width)}v${n(r.height)}h${n(-r.width)}Z`;
1448
+ return d;
1449
+ }
1450
+ function pad(r, by) {
1451
+ return { x: r.x - by, y: r.y - by, width: r.width + 2 * by, height: r.height + 2 * by };
1452
+ }
1453
+ var overlap = (a, b) => Math.max(0, Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x)) * Math.max(0, Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y));
1454
+ var NARROW = 600;
1455
+ function placePanel(holes, vw, vh, pw, ph, gutter = 16, gap = 12) {
1456
+ const clampX = (x) => Math.max(gutter, Math.min(x, vw - pw - gutter));
1457
+ const clampY = (y) => Math.max(gutter, Math.min(y, vh - ph - gutter));
1458
+ const spots = [];
1459
+ if (vw < NARROW) {
1460
+ spots.push({ x: gutter, y: vh - ph - gutter }, { x: gutter, y: gutter });
1461
+ } else if (holes.length === 0) {
1462
+ return { x: clampX((vw - pw) / 2), y: clampY((vh - ph) / 2) };
1463
+ } else {
1464
+ const left = Math.min(...holes.map((r) => r.x));
1465
+ const top = Math.min(...holes.map((r) => r.y));
1466
+ const right = Math.max(...holes.map((r) => r.x + r.width));
1467
+ const bottom = Math.max(...holes.map((r) => r.y + r.height));
1468
+ if (bottom + gap + ph <= vh - gutter) spots.push({ x: clampX(left), y: bottom + gap });
1469
+ if (top - gap - ph >= gutter) spots.push({ x: clampX(left), y: top - gap - ph });
1470
+ if (right + gap + pw <= vw - gutter) spots.push({ x: right + gap, y: clampY(top) });
1471
+ if (left - gap - pw >= gutter) spots.push({ x: left - gap - pw, y: clampY(top) });
1472
+ const [x0, x1, y0, y1] = [gutter, vw - pw - gutter, gutter, vh - ph - gutter];
1473
+ spots.push({ x: x1, y: y1 }, { x: x0, y: y1 }, { x: x1, y: y0 }, { x: x0, y: y0 });
1474
+ }
1475
+ const covers = (s) => holes.reduce((sum, r) => sum + overlap(r, { x: s.x, y: s.y, width: pw, height: ph }), 0);
1476
+ return spots.find((s) => covers(s) === 0) ?? spots.reduce((a, b) => covers(b) < covers(a) ? b : a);
1477
+ }
1478
+
1479
+ // src/tour/overlay.ts
1480
+ var DEFAULT_LABELS = { next: "Next", done: "Done", showMe: "Show me", close: "End tour" };
1481
+ var STYLE_ATTR = "data-tsappkit-tour-style";
1482
+ var CSS = `
1483
+ .tsappkit-tour { position: fixed; inset: 0; z-index: var(--tsappkit-tour-z, 2147483000); pointer-events: none; }
1484
+ .tsappkit-tour-dim { position: absolute; inset: 0; pointer-events: auto; background: var(--tsappkit-tour-dim, rgba(2, 6, 23, .6)); }
1485
+ .tsappkit-tour-ring { position: absolute; pointer-events: none; border-radius: var(--tsappkit-tour-ring-radius, 6px);
1486
+ box-shadow: 0 0 0 2px var(--tsappkit-tour-accent, #3b82f6); }
1487
+ .tsappkit-tour-panel { position: absolute; pointer-events: auto; box-sizing: border-box;
1488
+ width: min(var(--tsappkit-tour-panel-width, 360px), calc(100vw - 32px)); padding: 12px 16px 14px;
1489
+ border-radius: var(--tsappkit-tour-panel-radius, 10px); font: var(--tsappkit-tour-font, 14px/1.5 system-ui, sans-serif);
1490
+ background: var(--tsappkit-tour-panel-bg, #ffffff); color: var(--tsappkit-tour-panel-fg, #0f172a);
1491
+ box-shadow: 0 12px 32px rgba(0, 0, 0, .35); }
1492
+ .tsappkit-tour-head { display: flex; align-items: center; justify-content: space-between; gap: 8px;
1493
+ font-size: .85em; opacity: .75; }
1494
+ .tsappkit-tour-close { all: unset; cursor: pointer; font-size: 1.4em; line-height: 1; padding: 0 4px; }
1495
+ .tsappkit-tour-close:focus-visible, .tsappkit-tour-actions button:focus-visible {
1496
+ outline: 2px solid var(--tsappkit-tour-accent, #3b82f6); outline-offset: 2px; }
1497
+ .tsappkit-tour-title { font-weight: 600; margin: 4px 0 0; }
1498
+ .tsappkit-tour-text { margin: 4px 0 0; }
1499
+ .tsappkit-tour-actions { display: flex; justify-content: flex-end; gap: 8px; margin-top: 10px; }
1500
+ .tsappkit-tour-actions:empty { display: none; }
1501
+ .tsappkit-tour-actions button { font: inherit; cursor: pointer; padding: 4px 12px; border-radius: 6px;
1502
+ border: 1px solid var(--tsappkit-tour-accent, #3b82f6); background: transparent; color: inherit; }
1503
+ .tsappkit-tour-actions .tsappkit-tour-next { background: var(--tsappkit-tour-accent, #3b82f6); color: var(--tsappkit-tour-accent-fg, #ffffff); }
1504
+ @media (prefers-color-scheme: dark) {
1505
+ .tsappkit-tour-panel { background: var(--tsappkit-tour-panel-bg, #1e293b); color: var(--tsappkit-tour-panel-fg, #e2e8f0); }
1506
+ }
1507
+ `;
1508
+ var SWALLOWED = ["pointerdown", "pointerup", "mousedown", "mouseup", "click", "dblclick", "contextmenu"];
1509
+ var TourOverlay = class {
1510
+ constructor(doc, labels, on) {
1511
+ this.doc = doc;
1512
+ this.labels = labels;
1513
+ this.on = on;
1514
+ this.key = "";
1515
+ if (!doc.head.querySelector(`style[${STYLE_ATTR}]`)) {
1516
+ const style = doc.createElement("style");
1517
+ style.setAttribute(STYLE_ATTR, "");
1518
+ style.textContent = CSS;
1519
+ doc.head.prepend(style);
1520
+ }
1521
+ const el = (tag, cls, parent) => {
1522
+ const e = doc.createElement(tag);
1523
+ e.className = cls;
1524
+ parent?.append(e);
1525
+ return e;
1526
+ };
1527
+ this.root = el("div", "tsappkit-tour");
1528
+ this.dim = el("div", "tsappkit-tour-dim", this.root);
1529
+ this.rings = el("div", "tsappkit-tour-rings", this.root);
1530
+ this.panel = el("div", "tsappkit-tour-panel", this.root);
1531
+ this.panel.setAttribute("role", "dialog");
1532
+ this.panel.setAttribute("aria-label", "Tour");
1533
+ const head = el("div", "tsappkit-tour-head", this.panel);
1534
+ this.count = el("span", "tsappkit-tour-count", head);
1535
+ const close = el("button", "tsappkit-tour-close", head);
1536
+ close.type = "button";
1537
+ close.textContent = "\xD7";
1538
+ close.setAttribute("aria-label", labels.close);
1539
+ close.addEventListener("click", () => this.on.close());
1540
+ this.title = el("div", "tsappkit-tour-title", this.panel);
1541
+ this.text = el("p", "tsappkit-tour-text", this.panel);
1542
+ this.text.setAttribute("aria-live", "polite");
1543
+ this.actions = el("div", "tsappkit-tour-actions", this.panel);
1544
+ for (const type of SWALLOWED) this.root.addEventListener(type, (e) => e.stopPropagation());
1545
+ const block = (e) => e.preventDefault();
1546
+ this.dim.addEventListener("wheel", block, { passive: false });
1547
+ this.dim.addEventListener("touchmove", block, { passive: false });
1548
+ doc.body.append(this.root);
1549
+ }
1550
+ /** Puts a step's text and buttons in the panel. */
1551
+ show(step, view) {
1552
+ this.root.dataset.tourStep = step;
1553
+ this.count.textContent = `${view.index + 1} of ${view.count}`;
1554
+ this.title.textContent = view.title ?? "";
1555
+ this.title.hidden = !view.title;
1556
+ this.text.textContent = view.text;
1557
+ this.actions.replaceChildren();
1558
+ const button = (label, cls, click) => {
1559
+ const b = this.doc.createElement("button");
1560
+ b.type = "button";
1561
+ b.className = cls;
1562
+ b.textContent = label;
1563
+ b.addEventListener("click", click);
1564
+ this.actions.append(b);
1565
+ };
1566
+ if (view.showMe) button(this.labels.showMe, "tsappkit-tour-showme", () => this.on.showMe());
1567
+ if (view.next) {
1568
+ const last = view.index + 1 === view.count;
1569
+ button(last ? this.labels.done : this.labels.next, "tsappkit-tour-next", () => this.on.next());
1570
+ }
1571
+ this.key = "";
1572
+ }
1573
+ /**
1574
+ * Cuts one hole per rect (already padded, in viewport coordinates) and places the panel clear of
1575
+ * them. Cheap to call every frame: it only touches the DOM when the holes, the viewport or the
1576
+ * panel's size changed.
1577
+ */
1578
+ setHoles(rects) {
1579
+ const vw = this.doc.documentElement.clientWidth;
1580
+ const vh = this.doc.documentElement.clientHeight;
1581
+ const pw = this.panel.offsetWidth;
1582
+ const ph = this.panel.offsetHeight;
1583
+ const key = `${vw}x${vh} ${pw}x${ph} ` + rects.map((r) => `${r.x},${r.y},${r.width},${r.height}`).join(" ");
1584
+ if (key === this.key) return;
1585
+ this.key = key;
1586
+ const holes = unionRects(rects);
1587
+ this.dim.style.clipPath = `path(evenodd, "${holePath(vw, vh, holes)}")`;
1588
+ this.root.dataset.tourHoles = String(holes.length);
1589
+ while (this.rings.children.length > holes.length) this.rings.lastElementChild.remove();
1590
+ while (this.rings.children.length < holes.length) {
1591
+ const ring = this.doc.createElement("div");
1592
+ ring.className = "tsappkit-tour-ring";
1593
+ this.rings.append(ring);
1594
+ }
1595
+ holes.forEach((r, i) => {
1596
+ const s = this.rings.children[i].style;
1597
+ s.left = `${r.x}px`;
1598
+ s.top = `${r.y}px`;
1599
+ s.width = `${r.width}px`;
1600
+ s.height = `${r.height}px`;
1601
+ });
1602
+ const at = placePanel(rects, vw, vh, pw, ph);
1603
+ this.panel.style.left = `${at.x}px`;
1604
+ this.panel.style.top = `${at.y}px`;
1605
+ }
1606
+ destroy() {
1607
+ this.root.remove();
1608
+ }
1609
+ };
1610
+
1611
+ // src/tour/Tour.ts
1612
+ var raf = typeof requestAnimationFrame === "function" ? (cb) => requestAnimationFrame(cb) : (cb) => setTimeout(cb, 16);
1613
+ var caf = typeof cancelAnimationFrame === "function" ? (id) => cancelAnimationFrame(id) : (id) => clearTimeout(id);
1614
+ var Tour = class {
1615
+ /** @param steps the steps, in order. A tour with no steps never starts. */
1616
+ constructor(steps, options = {}) {
1617
+ this.steps = steps;
1618
+ this.options = options;
1619
+ this.at = -1;
1620
+ this.overlay = null;
1621
+ this.frame = 0;
1622
+ this.domTypes = [];
1623
+ this.onDom = (e) => {
1624
+ const path = e.composedPath();
1625
+ if (this.resolve().elements.some((el) => path.includes(el))) this.seen({ kind: "dom", type: e.type });
1626
+ };
1627
+ this.onKey = (e) => {
1628
+ if (e.key !== "Escape") return;
1629
+ e.stopPropagation();
1630
+ this.end("cancelled");
1631
+ };
1632
+ this.tick = () => {
1633
+ if (!this.running) return;
1634
+ this.measure();
1635
+ this.frame = raf(this.tick);
1636
+ };
1637
+ this.labels = { ...DEFAULT_LABELS, ...options.labels };
1638
+ }
1639
+ /** Whether the tour is showing a step. */
1640
+ get running() {
1641
+ return this.at >= 0;
1642
+ }
1643
+ /** The live step's index, or -1 when the tour isn't running. */
1644
+ get index() {
1645
+ return this.at;
1646
+ }
1647
+ /** The live step, or undefined when the tour isn't running. */
1648
+ get step() {
1649
+ return this.steps[this.at];
1650
+ }
1651
+ /**
1652
+ * Shows the overlay and step `at` (0 by default). On a running tour it moves to that step. A tour
1653
+ * can be started again after it ends.
1654
+ */
1655
+ start(at = 0) {
1656
+ if (at < 0 || at >= this.steps.length) return;
1657
+ if (!this.overlay) {
1658
+ this.overlay = new TourOverlay(document, this.labels, {
1659
+ close: () => this.end("cancelled"),
1660
+ next: () => this.next(),
1661
+ showMe: () => this.step?.doItForMe?.()
1662
+ });
1663
+ document.addEventListener("keydown", this.onKey, true);
1664
+ }
1665
+ this.go(at);
1666
+ if (!this.frame) this.frame = raf(this.tick);
1667
+ }
1668
+ /** Moves to the next step, or ends the tour as `"done"` after the last one. */
1669
+ next() {
1670
+ if (!this.running) return;
1671
+ if (this.at + 1 >= this.steps.length) this.end("done");
1672
+ else this.go(this.at + 1);
1673
+ }
1674
+ /** Removes the overlay and runs `onEnd`. Does nothing on a tour that isn't running. */
1675
+ end(reason = "cancelled") {
1676
+ if (!this.running) return;
1677
+ const index = this.at;
1678
+ this.listenDom([]);
1679
+ this.at = -1;
1680
+ caf(this.frame);
1681
+ this.frame = 0;
1682
+ document.removeEventListener("keydown", this.onKey, true);
1683
+ this.overlay?.destroy();
1684
+ this.overlay = null;
1685
+ this.options.onEnd?.(reason, this.steps[index], index);
1686
+ }
1687
+ /**
1688
+ * Tells the tour an app event happened, for an app that keeps its own channels rather than an
1689
+ * EventBus. Ignored while the tour isn't running. The live step advances when it matches
1690
+ * `advanceOn`, and otherwise applies `onOffPath` when it matches `offPath`. An event whose payload
1691
+ * is `void` takes no data.
1692
+ */
1693
+ notify(type, ...data) {
1694
+ this.seen({ kind: "app", type, data: data[0] });
1695
+ }
1696
+ /**
1697
+ * Subscribes to every app event any step names (in `advanceOn` or `offPath`) and passes each to
1698
+ * `notify`. The subscriptions last until the returned function is called, across ends and
1699
+ * restarts; events arriving while the tour isn't running are ignored.
1700
+ */
1701
+ attach(source) {
1702
+ const names = /* @__PURE__ */ new Set();
1703
+ for (const s of this.steps) {
1704
+ for (const t of [s.advanceOn, ...triggers(s.offPath)]) if (t && "event" in t) names.add(t.event);
1705
+ }
1706
+ const handlers = [...names].map((type) => {
1707
+ const h = (data) => this.seen({ kind: "app", type, data });
1708
+ source.on(type, h);
1709
+ return [type, h];
1710
+ });
1711
+ return () => handlers.forEach(([type, h]) => source.off(type, h));
1712
+ }
1713
+ go(at) {
1714
+ this.at = at;
1715
+ const step = this.steps[at];
1716
+ this.listenDom(
1717
+ [step.advanceOn, ...triggers(step.offPath)].flatMap((t) => t && "dom" in t ? [t.dom] : [])
1718
+ );
1719
+ this.overlay.show(step.id, {
1720
+ index: at,
1721
+ count: this.steps.length,
1722
+ title: step.title,
1723
+ text: step.text,
1724
+ next: !step.advanceOn,
1725
+ showMe: !!step.doItForMe
1726
+ });
1727
+ this.measure();
1728
+ this.options.onStep?.(step, at);
1729
+ }
1730
+ seen(e) {
1731
+ const step = this.step;
1732
+ if (!step) return;
1733
+ if (step.advanceOn && matches(step.advanceOn, e)) this.next();
1734
+ else if (triggers(step.offPath).some((t) => matches(t, e)) && (step.onOffPath ?? "end") === "end") {
1735
+ this.end("offPath");
1736
+ }
1737
+ }
1738
+ // DOM triggers listen on the document in the capture phase and check the event's path against the
1739
+ // step's targets as they are now, so a target that re-renders between frames still counts, and a
1740
+ // non-bubbling event (pointerenter) is still seen.
1741
+ listenDom(types) {
1742
+ for (const t of this.domTypes) document.removeEventListener(t, this.onDom, true);
1743
+ this.domTypes = [...new Set(types)];
1744
+ for (const t of this.domTypes) document.addEventListener(t, this.onDom, true);
1745
+ }
1746
+ // Re-measured every frame while a step is live, which covers a resize, a scroll and a layout that
1747
+ // moves under the overlay alike; the overlay only touches the DOM when something changed.
1748
+ measure() {
1749
+ const by = this.options.padding ?? 4;
1750
+ this.overlay?.setHoles(this.resolve().rects.map((r) => pad(r, by)));
1751
+ }
1752
+ resolve() {
1753
+ const elements = [];
1754
+ const rects = [];
1755
+ const add = (t) => {
1756
+ if (isElement(t)) {
1757
+ elements.push(t);
1758
+ const r = t.getBoundingClientRect();
1759
+ if (r.width > 0 && r.height > 0) rects.push({ x: r.x, y: r.y, width: r.width, height: r.height });
1760
+ } else {
1761
+ rects.push({ x: t.x, y: t.y, width: t.width, height: t.height });
1762
+ }
1763
+ };
1764
+ const target = this.step?.target?.();
1765
+ if (target == null) return { elements, rects };
1766
+ if (isElement(target) || !isIterable(target)) add(target);
1767
+ else for (const t of target) add(t);
1768
+ return { elements, rects };
1769
+ }
1770
+ };
1771
+ function triggers(t) {
1772
+ if (!t) return [];
1773
+ return Array.isArray(t) ? t : [t];
1774
+ }
1775
+ function matches(t, e) {
1776
+ if ("dom" in t) return e.kind === "dom" && e.type === t.dom;
1777
+ const app = t;
1778
+ return e.kind === "app" && e.type === app.event && (!app.where || app.where(e.data));
1779
+ }
1780
+ var isElement = (t) => typeof Element !== "undefined" && t instanceof Element;
1781
+ var isIterable = (t) => Symbol.iterator in t;
1782
+
1411
1783
  // src/page/load.ts
1412
1784
  function parseLoad(load) {
1413
1785
  switch (load ?? "") {
@@ -1537,7 +1909,7 @@ function message(err) {
1537
1909
 
1538
1910
  // src/page/overlay.ts
1539
1911
  var STYLE_ID = "island-overlay-style";
1540
- var CSS = `
1912
+ var CSS2 = `
1541
1913
  [data-island-debug] { position: relative; outline: 2px dashed #1565c0; outline-offset: -2px; }
1542
1914
  [data-island-debug]::after {
1543
1915
  content: attr(data-island-debug); position: absolute; top: 0; right: 0; z-index: 2147483647;
@@ -1555,7 +1927,7 @@ var IslandOverlay = class {
1555
1927
  if (!doc.getElementById(STYLE_ID)) {
1556
1928
  const style = doc.createElement("style");
1557
1929
  style.id = STYLE_ID;
1558
- style.textContent = CSS;
1930
+ style.textContent = CSS2;
1559
1931
  doc.head.appendChild(style);
1560
1932
  }
1561
1933
  }
@@ -2034,6 +2406,7 @@ exports.SplashScreen = SplashScreen;
2034
2406
  exports.TemplateLoader = TemplateLoader;
2035
2407
  exports.ThemeManager = ThemeManager;
2036
2408
  exports.ToastManager = ToastManager;
2409
+ exports.Tour = Tour;
2037
2410
  exports.hasModifierKeys = hasModifierKeys;
2038
2411
  exports.isInInputContext = isInInputContext;
2039
2412
  exports.lazy = lazy;