seeonwall 0.1.0 → 0.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.
package/README.md CHANGED
@@ -15,7 +15,51 @@ npm install seeonwall
15
15
 
16
16
  You need a shop id from the [SeeOnWall dashboard](https://seeonwall.com).
17
17
 
18
- ## Use
18
+ ## React
19
+
20
+ ```tsx
21
+ import { useSeeOnWall, SeeOnWallButton } from 'seeonwall/react'
22
+
23
+ function ProductPage({ product }) {
24
+ useSeeOnWall({ shopId: 'YOUR_SHOP_ID' })
25
+
26
+ return (
27
+ <SeeOnWallButton
28
+ posterUrl={product.image}
29
+ posterTitle={product.title}
30
+ posterWidth={50}
31
+ posterHeight={70}
32
+ posterSizes={['30x40', '50x70', '70x100']}
33
+ />
34
+ )
35
+ }
36
+ ```
37
+
38
+ `useSeeOnWall` loads the widget and stops it when the last component using it
39
+ unmounts. It counts its callers, so calling it in several components is safe, and
40
+ it survives StrictMode's double-invoked effects.
41
+
42
+ `SeeOnWallButton` renders an empty mount and lets the widget put the button
43
+ inside. It deliberately does not render its own button — that keeps the logo,
44
+ the allowed-domain check, the theme match and the localised label in the code
45
+ that already implements all four.
46
+
47
+ React is a peer dependency, so you use whichever version you already have.
48
+
49
+ ### Button props
50
+
51
+ Everything in `PosterParams`, plus:
52
+
53
+ | prop | | |
54
+ |---|---|---|
55
+ | `posterSizes` | `string[]` or `string` | An array is joined with commas for you. |
56
+ | `className`, `style` | | Applied to the mount element. |
57
+ | `backgroundColor`, `textColor`, `borderRadius`, `borderColor` | | Button appearance. |
58
+ | `buttonClassName` | | Your theme's classes, added after the widget's own. |
59
+ | `matchButton` | selector | Copies shape and typography from one of your own buttons. |
60
+ | `matchColors` | boolean | Also copies its colours. |
61
+
62
+ ## Vanilla JavaScript
19
63
 
20
64
  ```js
21
65
  import { load } from 'seeonwall'
@@ -79,6 +123,13 @@ the part of your app that uses SeeOnWall.
79
123
  | `destroy()` | Stops the widget and removes everything it added. |
80
124
  | `snippetVersion()` | The loaded widget version, or `null`. Useful in bug reports. |
81
125
 
126
+ From `seeonwall/react`:
127
+
128
+ | | |
129
+ |---|---|
130
+ | `useSeeOnWall(options)` | Loads the widget for as long as a component needs it. Same options as `load()`. |
131
+ | `SeeOnWallButton` | Renders a mount for the widget's button. |
132
+
82
133
  ### `load(options)`
83
134
 
84
135
  | option | | |
@@ -0,0 +1,64 @@
1
+ import type { CSSProperties, ReactElement } from 'react';
2
+ import type { LoadOptions, PosterParams } from './index.js';
3
+ export type { LoadOptions, PosterParams };
4
+ /**
5
+ * Loads the widget while a component is on the page.
6
+ *
7
+ * Call this hook one time, high in your application. You can also call it in
8
+ * each component that shows a button: the hook counts its users, thus more than
9
+ * one call is safe.
10
+ *
11
+ * The hook obeys the lifecycle of React. It loads the widget when the component
12
+ * arrives and stops the widget when the last one goes away. React StrictMode
13
+ * runs this sequence two times in development. The result is the same.
14
+ */
15
+ export declare function useSeeOnWall(options: LoadOptions): void;
16
+ /** The appearance settings that a merchant can set for one button. */
17
+ export interface SeeOnWallButtonStyleProps {
18
+ /** The background colour of the button, for example `"#b5502a"`. */
19
+ backgroundColor?: string;
20
+ /** The text colour of the button. */
21
+ textColor?: string;
22
+ /** The corner radius of the button, for example `"4px"`. */
23
+ borderRadius?: string;
24
+ /** The border colour of the button. */
25
+ borderColor?: string;
26
+ /**
27
+ * The classes of your own theme to put on the button. The widget adds them
28
+ * after its own class, thus your styles win where they are more specific.
29
+ */
30
+ buttonClassName?: string;
31
+ /**
32
+ * A CSS selector for a button of your theme to copy. The widget copies the
33
+ * shape and the typography of that button. It does not copy the colours.
34
+ */
35
+ matchButton?: string;
36
+ /** Copies the colours of the button named in `matchButton` as well. */
37
+ matchColors?: boolean;
38
+ }
39
+ export interface SeeOnWallButtonProps extends Omit<PosterParams, 'posterSizes'>, SeeOnWallButtonStyleProps {
40
+ /**
41
+ * The sizes that the shopper can select. Give an array, for example
42
+ * `['30x40', '50x70']`. A string with commas also works.
43
+ *
44
+ * The widget shows a size selector when there is more than one size.
45
+ */
46
+ posterSizes?: string[] | string;
47
+ /** Classes for the element that holds the button. */
48
+ className?: string;
49
+ /** Styles for the element that holds the button. */
50
+ style?: CSSProperties;
51
+ }
52
+ /**
53
+ * A place for the "See on wall" button.
54
+ *
55
+ * The component gives the widget an empty element and the widget puts the
56
+ * button inside it. The component does not draw a button itself. This keeps the
57
+ * logo, the permitted domains, the theme match and the language of the label in
58
+ * the widget, which already does all four.
59
+ *
60
+ * Your application must also call {@link useSeeOnWall} one time, or no button
61
+ * arrives.
62
+ */
63
+ export declare function SeeOnWallButton(props: SeeOnWallButtonProps): ReactElement;
64
+ //# sourceMappingURL=react.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AAExD,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE3D,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,CAAA;AAYzC;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAwBvD;AAED,sEAAsE;AACtE,MAAM,WAAW,yBAAyB;IACxC,oEAAoE;IACpE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uEAAuE;IACvE,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED,MAAM,WAAW,oBACf,SAAQ,IAAI,CAAC,YAAY,EAAE,aAAa,CAAC,EACvC,yBAAyB;IAC3B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;IAC/B,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oDAAoD;IACpD,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB;AAiBD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,YAAY,CA2DzE"}
package/dist/react.js ADDED
@@ -0,0 +1,95 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { useEffect } from 'react';
3
+ import { load, destroy } from './index.js';
4
+ /**
5
+ * The number of components that use the widget at this moment.
6
+ *
7
+ * The count is necessary because a page can have many buttons, but the widget
8
+ * is one object for the full page. The widget stops only when the last
9
+ * component goes away. A stop after the first component goes away would remove
10
+ * the buttons of all the others.
11
+ */
12
+ let consumers = 0;
13
+ /**
14
+ * Loads the widget while a component is on the page.
15
+ *
16
+ * Call this hook one time, high in your application. You can also call it in
17
+ * each component that shows a button: the hook counts its users, thus more than
18
+ * one call is safe.
19
+ *
20
+ * The hook obeys the lifecycle of React. It loads the widget when the component
21
+ * arrives and stops the widget when the last one goes away. React StrictMode
22
+ * runs this sequence two times in development. The result is the same.
23
+ */
24
+ export function useSeeOnWall(options) {
25
+ const { shopId, embedUrl, lang, sizeUnit, scriptUrl } = options;
26
+ useEffect(() => {
27
+ consumers += 1;
28
+ void load({
29
+ shopId,
30
+ ...(embedUrl !== undefined ? { embedUrl } : {}),
31
+ ...(lang !== undefined ? { lang } : {}),
32
+ ...(sizeUnit !== undefined ? { sizeUnit } : {}),
33
+ ...(scriptUrl !== undefined ? { scriptUrl } : {}),
34
+ }).catch((err) => {
35
+ console.error('[seeonwall] The widget did not load.', err);
36
+ });
37
+ return () => {
38
+ consumers -= 1;
39
+ if (consumers === 0) {
40
+ destroy();
41
+ }
42
+ };
43
+ // Each option is a dependency. A change to one of them starts the widget
44
+ // again with the new value.
45
+ }, [shopId, embedUrl, lang, sizeUnit, scriptUrl]);
46
+ }
47
+ /**
48
+ * Adds a value to the map of attributes, but only when the value is present.
49
+ * An absent attribute and an empty attribute do not mean the same thing to the
50
+ * widget.
51
+ */
52
+ function attr(target, name, value) {
53
+ if (value !== undefined && value !== '') {
54
+ target[name] = String(value);
55
+ }
56
+ }
57
+ /**
58
+ * A place for the "See on wall" button.
59
+ *
60
+ * The component gives the widget an empty element and the widget puts the
61
+ * button inside it. The component does not draw a button itself. This keeps the
62
+ * logo, the permitted domains, the theme match and the language of the label in
63
+ * the widget, which already does all four.
64
+ *
65
+ * Your application must also call {@link useSeeOnWall} one time, or no button
66
+ * arrives.
67
+ */
68
+ export function SeeOnWallButton(props) {
69
+ const { posterUrl, posterTitle, sizeUnit, posterWidth, posterHeight, posterSizes, posterInset, productPageUrl, lang, frameDefaultCm, frameDefaultColor, backgroundColor, textColor, borderRadius, borderColor, buttonClassName, matchButton, matchColors, className, style, } = props;
70
+ const attributes = {};
71
+ attr(attributes, 'data-poster-url', posterUrl);
72
+ attr(attributes, 'data-poster-title', posterTitle);
73
+ attr(attributes, 'data-size-unit', sizeUnit);
74
+ attr(attributes, 'data-poster-width', posterWidth);
75
+ attr(attributes, 'data-poster-height', posterHeight);
76
+ attr(attributes, 'data-poster-sizes', Array.isArray(posterSizes) ? posterSizes.join(',') : posterSizes);
77
+ attr(attributes, 'data-poster-inset', posterInset);
78
+ attr(attributes, 'data-product-page-url', productPageUrl);
79
+ attr(attributes, 'data-lang', lang);
80
+ attr(attributes, 'data-frame-default-cm', frameDefaultCm);
81
+ attr(attributes, 'data-frame-default-color', frameDefaultColor);
82
+ attr(attributes, 'data-bg-color', backgroundColor);
83
+ attr(attributes, 'data-text-color', textColor);
84
+ attr(attributes, 'data-border-radius', borderRadius);
85
+ attr(attributes, 'data-border-color', borderColor);
86
+ attr(attributes, 'data-button-class', buttonClassName);
87
+ attr(attributes, 'data-match-button', matchButton);
88
+ if (matchColors === true) {
89
+ attributes['data-match-colors'] = 'true';
90
+ }
91
+ // The element stays empty. The widget puts a button inside it, and React does
92
+ // not touch a child that React did not make.
93
+ return (_jsx("div", { className: className ? `seeonwall-button ${className}` : 'seeonwall-button', style: style, ...attributes }));
94
+ }
95
+ //# sourceMappingURL=react.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "seeonwall",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Show shoppers a poster on their own wall, at true scale. The seeonwall.com widget for React and headless storefronts.",
5
5
  "keywords": [
6
6
  "seeonwall",
@@ -30,7 +30,11 @@
30
30
  "types": "./dist/index.d.ts",
31
31
  "default": "./dist/index.js"
32
32
  },
33
- "./package.json": "./package.json"
33
+ "./package.json": "./package.json",
34
+ "./react": {
35
+ "types": "./dist/react.d.ts",
36
+ "default": "./dist/react.js"
37
+ }
34
38
  },
35
39
  "files": [
36
40
  "dist",
@@ -52,8 +56,21 @@
52
56
  "prepublishOnly": "npm run build"
53
57
  },
54
58
  "devDependencies": {
59
+ "@testing-library/dom": "^10.4.1",
60
+ "@testing-library/react": "^16.3.2",
61
+ "@types/react": "^19.2.18",
55
62
  "jsdom": "^30.0.1",
63
+ "react": "^19.2.8",
64
+ "react-dom": "^19.2.8",
56
65
  "typescript": "~6.0.3",
57
66
  "vitest": "^4.1.10"
67
+ },
68
+ "peerDependencies": {
69
+ "react": ">=18"
70
+ },
71
+ "peerDependenciesMeta": {
72
+ "react": {
73
+ "optional": true
74
+ }
58
75
  }
59
76
  }