@superwall/studio 1.1.0 → 1.2.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.
Files changed (50) hide show
  1. package/README.md +93 -14
  2. package/dist/assets/index-CVKQ82YR.js +11 -0
  3. package/dist/assets/index-_HCp6gCi.css +1 -0
  4. package/dist/index.html +2 -2
  5. package/dist/lib/StudioApp.d.ts +7 -0
  6. package/dist/lib/components/ActionMenu.d.ts +13 -0
  7. package/dist/lib/components/CompareMenu.d.ts +13 -0
  8. package/dist/lib/components/DeviceChrome.d.ts +12 -0
  9. package/dist/lib/components/DeviceFrame.d.ts +18 -0
  10. package/dist/lib/components/MissingProducts.d.ts +8 -0
  11. package/dist/lib/components/OpenInApp.d.ts +5 -0
  12. package/dist/lib/components/PaywallToasts.d.ts +5 -0
  13. package/dist/lib/components/SidePanel.d.ts +6 -0
  14. package/dist/lib/components/StudioShell.d.ts +4 -0
  15. package/dist/lib/components/SurfaceCard.d.ts +9 -0
  16. package/dist/lib/components/Toolbar.d.ts +6 -0
  17. package/dist/lib/components/TopBar.d.ts +8 -0
  18. package/dist/lib/components/VariablesPanel.d.ts +13 -0
  19. package/dist/lib/components/controls.d.ts +24 -0
  20. package/dist/lib/components/icons.d.ts +20 -0
  21. package/dist/lib/icon.svg +5 -0
  22. package/dist/lib/index.d.ts +14 -0
  23. package/dist/lib/index.js +1746 -0
  24. package/dist/lib/lib/actions.d.ts +4 -0
  25. package/dist/lib/lib/devices.d.ts +26 -0
  26. package/dist/lib/lib/events.d.ts +27 -0
  27. package/dist/lib/lib/preview.d.ts +7 -0
  28. package/dist/lib/lib/products.d.ts +16 -0
  29. package/dist/lib/lib/project.d.ts +12 -0
  30. package/dist/lib/lib/time.d.ts +1 -0
  31. package/dist/lib/lib/types.d.ts +77 -0
  32. package/dist/lib/products.js +51 -0
  33. package/dist/lib/screens/SurfaceEditor.d.ts +9 -0
  34. package/dist/lib/screens/SurfaceList.d.ts +7 -0
  35. package/dist/lib/studio.css +1 -0
  36. package/package.json +15 -4
  37. package/src/StudioApp.tsx +3 -2
  38. package/src/components/ActionMenu.tsx +1 -1
  39. package/src/components/CompareMenu.tsx +1 -1
  40. package/src/components/PaywallToasts.tsx +1 -0
  41. package/src/components/StudioShell.tsx +12 -0
  42. package/src/index.ts +9 -1
  43. package/src/lib/events.ts +10 -1
  44. package/src/lib/preview.ts +10 -0
  45. package/src/lib/products.ts +97 -0
  46. package/src/lib/types.ts +2 -0
  47. package/src/screens/SurfaceEditor.tsx +31 -12
  48. package/src/styles.css +8 -6
  49. package/dist/assets/index-CVKGrx00.js +0 -11
  50. package/dist/assets/index-D4RIpSbg.css +0 -1
package/README.md CHANGED
@@ -1,38 +1,59 @@
1
- # `@superwall/studio`
1
+ <p align="center">
2
+ <a href="https://superwall.com/">
3
+ <img src="https://user-images.githubusercontent.com/3296904/158817914-144c66d0-572d-43a4-9d47-d7d0b711c6d7.png" alt="Superwall" height="100" />
4
+ </a>
5
+ </p>
2
6
 
3
- The Superwall studio: a standalone vite + React + Tailwind app that is also
4
- a component library. One codebase, two hosts:
7
+ <h1 align="center">@superwall/studio</h1>
8
+
9
+ <p align="center">
10
+ The studio <code>superwall dev</code> opens: every paywall and funnel as a
11
+ live card, and a device-frame editor with theme, locale, and variable
12
+ overrides.
13
+ </p>
14
+
15
+ ## Install
16
+
17
+ ```bash
18
+ npm install @superwall/studio
19
+ ```
20
+
21
+ You will not usually install this directly: the
22
+ [`superwall`](https://www.npmjs.com/package/superwall) framework depends on
23
+ it and `superwall dev` serves it. It is a standalone vite + React + Tailwind
24
+ app that is also a component library — one codebase, two hosts:
5
25
 
6
26
  - **`superwall dev`** serves the BUILT app (`dist/`, assets under
7
27
  `/__studio/`) plus the data endpoint and preview mounts — the local studio.
8
- - **The hosted dashboard** either embeds the built app (the way it embeds the
9
- editor) or imports the components directly over platform data.
28
+ - **The hosted studio** in the dashboard imports the component library
29
+ (`dist/lib/`, the package's `.` export, plus the compiled
30
+ `@superwall/studio/studio.css`) and renders `SurfaceEditor` over published
31
+ snapshots and platform data. See [Hosting](#hosting).
10
32
 
11
- ## App structure
33
+ ## Package layout
12
34
 
13
35
  ```
14
36
  packages/studio/
15
37
  ├── index.html the app shell (fonts, favicon)
16
38
  ├── vite.config.ts vite + react + tailwind; /__studio/ base for builds
39
+ ├── vite.lib.config.ts the library build: dist/lib/index.js + studio.css
40
+ ├── tsconfig.lib.json declarations for the library build
17
41
  ├── src/
18
42
  │ ├── main.tsx entry: fetch /__studio/project.json → <StudioApp/>
19
43
  │ ├── index.ts the component-library barrel a hosted studio imports
20
44
  │ ├── StudioApp.tsx URL-driven router (list ⇄ editor)
21
45
  │ ├── screens/ SurfaceList, SurfaceEditor
22
- │ ├── components/ TopBar, Toolbar, DeviceFrame, VariablesPanel,
46
+ │ ├── components/ StudioShell, TopBar, Toolbar, DeviceFrame, VariablesPanel,
23
47
  │ │ ActionMenu, CompareMenu, SidePanel, controls, icons, …
24
48
  │ ├── lib/ project.ts (wire-format parser, untrusted JSON,
25
49
  │ │ cast-free), preview.ts (preview URL builder),
26
50
  │ │ devices.ts (viewport + mock-device catalog),
27
51
  │ │ actions.ts, events.ts, time.ts, types.ts
28
52
  │ └── styles.css tailwind @theme tokens + stateful primitives
29
- └── dist/ built by the workspace postinstall
53
+ └── dist/ built by the workspace postinstall: the app, and
54
+ the library under dist/lib/
30
55
  ```
31
56
 
32
- Working on the studio: `bun dev` here (port 6200) proxies `/preview` and
33
- `/__studio/project.json` to a running `superwall dev` (port 6100) in any
34
- project — edit studio code with HMR against real paywalls.
35
-
36
57
  ## Data seam
37
58
 
38
59
  Everything renders from a `StudioSource` — `{ title, surfaces, diagnostics?,
@@ -43,8 +64,40 @@ swaps the fetch, nothing else. `previewUrl(surface, overrides)` decides what
43
64
  the preview iframes load: `/preview/<kind>/<id>` mounts locally, published
44
65
  snapshot URLs in the dashboard. Overrides travel as query params (`theme`,
45
66
  `locale`, `sw_device`, `sw_user`, `sw_params`, `sw_products`, `sw_trial`) —
46
- the same channel published snapshots accept, so preview behavior is
47
- identical in both hosts.
67
+ the same channel published snapshots accept once opted in with
68
+ `?sw_preview=1`, so preview behavior is identical in both hosts.
69
+
70
+ ## Hosting
71
+
72
+ The dashboard opens a code-first paywall in this studio instead of the visual
73
+ editor. What the library gives a host:
74
+
75
+ - `snapshotPreviewUrl(urlOf)` — a `previewUrl` that resolves each surface to
76
+ its published snapshot URL, opts it into simulation (`sw_preview=1`), and
77
+ appends the overrides. Every built snapshot boots through the framework's
78
+ `PreviewHost`, which reads that channel, exposes `__swPreviewApply` for
79
+ instant re-application (same origin only — cross-origin frames reload), and
80
+ drives the studio bridge: paywall events and purchase/permission/callback
81
+ prompts reach the host's toasts, and a `hello` message carries the
82
+ paywall's locales, so `SurfaceEditor` fills its locale switcher when the
83
+ host passes `locales: []`.
84
+ - One `StudioSurface` per version, told apart by `label` (`"v12 · live"`);
85
+ `StudioSource.compareHint` names what the compare menu offers, and
86
+ `SurfaceEditor`'s `actions` slot takes the host's own controls (a version
87
+ switcher, say). With no `capabilities`, there is no push/promote UI.
88
+ - `StudioShell` (`position="absolute"` when the host owns the viewport) is
89
+ the ink stage every screen expects, and it carries the `sw-studio` class
90
+ the stylesheet scopes its base rules to.
91
+ - `@superwall/studio/studio.css` is compiled Tailwind v4 output including a
92
+ preflight. Mount it in a shadow root (or an iframe) rather than beside
93
+ another design system — the dashboard does exactly that, and re-registers
94
+ the sheet's `@property` rules at document level, where browsers expect them.
95
+ - `@superwall/studio/products` is the pure mapping from a dashboard product
96
+ (the v2 API shape) to the variables a paywall reads (`price`, `periodly`,
97
+ `trialPeriodDays`, …). The CLI and the hosted studio share it, so the
98
+ Variables panel shows the same numbers in both.
99
+ `@superwall/studio/styles.css` is the Tailwind source for hosts that run
100
+ their own v4 pipeline.
48
101
 
49
102
  ## Screens
50
103
 
@@ -76,3 +129,29 @@ components, and only stateful primitives (`.sw-btn`, `.sw-chip`,
76
129
  `.sw-select`, `.sw-segmented`, `.sw-switch`, `.sw-input`) as component
77
130
  classes. Runtime dependencies are React (a peer) and `sonner` for toasts —
78
131
  icons are inlined Lucide-geometry SVGs.
132
+
133
+ ## Develop
134
+
135
+ This package lives in the [`superwall/superwall`](https://github.com/superwall/superwall)
136
+ monorepo. **Read [AGENTS.md](https://github.com/superwall/superwall/blob/main/AGENTS.md)
137
+ first** - the conventions in it are decided, not suggested.
138
+
139
+ ```bash
140
+ bun install
141
+ bun dev # the studio alone on port 6200, proxied to a running
142
+ # `superwall dev` (port 6100) in any project — HMR against
143
+ # real paywalls
144
+ bun run build # dist/ (what `superwall dev` serves) and dist/lib/ (the library)
145
+ bun run test
146
+ bun run typecheck
147
+ ```
148
+
149
+ The workspace `postinstall` builds `dist/`, so a fresh clone of the monorepo
150
+ has a studio to serve from the first `superwall dev`.
151
+
152
+ ## License
153
+
154
+ [Functional Source License](https://github.com/superwall/superwall/blob/main/packages/superwall/LICENSE)
155
+ (FSL-1.1-ALv2): use it, modify it, embed it, ship it — anything except
156
+ building a competing product with it — and every release becomes Apache 2.0
157
+ two years after publication.