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