@stromcom/react-snippet 0.1.0

package/src/__tests__/StromcomHome.test.jsx

@@ -0,0 +1,57 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, cleanup } from '@testing-library/react';
+import { StromcomContext } from '../StromcomProvider.jsx';
+import { StromcomHome } from '../StromcomHome.jsx';
+
+function renderWithLayer(layer, props) {
+  return render(
+    <StromcomContext.Provider value={layer}>
+      <StromcomHome {...props} />
+    </StromcomContext.Provider>,
+  );
+}
+
+afterEach(() => cleanup());
+
+describe('StromcomHome', () => {
+  it('initializes the notification center once on mount with the container element', () => {
+    const layer = { home: vi.fn() };
+    const { container } = renderWithLayer(layer);
+
+    expect(layer.home).toHaveBeenCalledTimes(1);
+    expect(layer.home).toHaveBeenCalledWith(container.firstChild);
+  });
+
+  it('does not re-initialize on re-render', () => {
+    const layer = { home: vi.fn() };
+    const { rerender } = renderWithLayer(layer, { className: 'a' });
+
+    rerender(
+      <StromcomContext.Provider value={layer}>
+        <StromcomHome className="b" />
+      </StromcomContext.Provider>,
+    );
+
+    expect(layer.home).toHaveBeenCalledTimes(1);
+  });
+
+  it('passes className, style and data-* attributes through to the container div', () => {
+    const layer = { home: vi.fn() };
+    const { container } = renderWithLayer(layer, {
+      className: 'my-home',
+      style: { bottom: 24 },
+      'data-testid': 'home',
+    });
+
+    const div = container.firstChild;
+    expect(div.className).toBe('my-home');
+    expect(div.style.bottom).toBe('24px');
+    expect(div.getAttribute('data-testid')).toBe('home');
+  });
+
+  it('does not call home when there is no layer', () => {
+    const { container } = render(<StromcomHome />);
+
+    expect(container.firstChild).toBeInstanceOf(HTMLDivElement);
+  });
+});

package/src/__tests__/StromcomProvider.test.jsx

@@ -0,0 +1,137 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, cleanup } from '@testing-library/react';
+import { StromcomProvider, useStromcom } from '../StromcomProvider.jsx';
+
+function scriptFor(clientKey) {
+  return document.querySelector(`script[data-ck="${clientKey}"][data-type="stromcom"]`);
+}
+
+afterEach(() => {
+  cleanup();
+  document.querySelectorAll('script[data-type="stromcom"]').forEach((el) => el.remove());
+  delete window.stromCom;
+  delete window.stromComDL;
+  delete window.customLayer;
+  delete window.customLayerDL;
+});
+
+describe('StromcomProvider', () => {
+  it('renders its children', () => {
+    const { getByText } = render(
+      <StromcomProvider clientKey="ck_1" clientSecret="cs_1">
+        <div>hello</div>
+      </StromcomProvider>,
+    );
+    expect(getByText('hello')).toBeInTheDocument();
+  });
+
+  it('injects a script tag with the expected dataset and default (production) src', () => {
+    render(
+      <StromcomProvider clientKey="ck_1" clientSecret="cs_1">
+        <div />
+      </StromcomProvider>,
+    );
+
+    const script = scriptFor('ck_1');
+    expect(script).not.toBeNull();
+    expect(script.dataset.l).toBe('stromCom');
+    expect(script.dataset.dl).toBe('stromComDL');
+    expect(script.dataset.cs).toBe('cs_1');
+    expect(script.src).toBe('https://cdn.stromcom.cz/loader.js?ck_1');
+  });
+
+  it('points at the staging loader when environment="staging"', () => {
+    render(
+      <StromcomProvider clientKey="ck_2" clientSecret="cs_2" environment="staging">
+        <div />
+      </StromcomProvider>,
+    );
+
+    expect(scriptFor('ck_2').src).toBe('https://cdn.staging.stromcom.cz/loader.js?ck_2');
+  });
+
+  it('treats an unknown environment value as a custom loader URL', () => {
+    render(
+      <StromcomProvider
+        clientKey="ck_3"
+        clientSecret="cs_3"
+        environment="https://loader.example.com/custom.js"
+      >
+        <div />
+      </StromcomProvider>,
+    );
+
+    expect(scriptFor('ck_3').src).toBe('https://loader.example.com/custom.js?ck_3');
+  });
+
+  it('does not inject a second script for the same clientKey', () => {
+    const { rerender } = render(
+      <StromcomProvider clientKey="ck_4" clientSecret="cs_4">
+        <div />
+      </StromcomProvider>,
+    );
+    rerender(
+      <StromcomProvider clientKey="ck_4" clientSecret="cs_4">
+        <div>changed</div>
+      </StromcomProvider>,
+    );
+
+    expect(document.querySelectorAll('script[data-ck="ck_4"]')).toHaveLength(1);
+  });
+
+  it('removes the script on unmount', () => {
+    const { unmount } = render(
+      <StromcomProvider clientKey="ck_5" clientSecret="cs_5">
+        <div />
+      </StromcomProvider>,
+    );
+    expect(scriptFor('ck_5')).not.toBeNull();
+
+    unmount();
+
+    expect(scriptFor('ck_5')).toBeNull();
+  });
+
+  it('respects a custom dataLayer name', () => {
+    render(
+      <StromcomProvider clientKey="ck_6" clientSecret="cs_6" dataLayer="customLayer">
+        <div />
+      </StromcomProvider>,
+    );
+
+    expect(window.customLayer).toBeDefined();
+    expect(window.customLayerDL).toBeDefined();
+    expect(scriptFor('ck_6').dataset.l).toBe('customLayer');
+  });
+
+  it('exposes a stub layer with the expected queueing methods via useStromcom', () => {
+    let layer;
+    function Probe() {
+      layer = useStromcom();
+      return null;
+    }
+
+    render(
+      <StromcomProvider clientKey="ck_7" clientSecret="cs_7">
+        <Probe />
+      </StromcomProvider>,
+    );
+
+    expect(layer).toBeTruthy();
+    expect(typeof layer.initUser).toBe('function');
+    expect(typeof layer.thread).toBe('function');
+    expect(typeof layer.conf).toBe('function');
+    expect(typeof layer.home).toBe('function');
+  });
+
+  it('returns null from useStromcom outside of a provider', () => {
+    let layer = 'not-set';
+    function Probe() {
+      layer = useStromcom();
+      return null;
+    }
+    render(<Probe />);
+
+    expect(layer).toBeNull();
+  });
+});

package/src/__tests__/StromcomThread.test.jsx

@@ -0,0 +1,75 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, cleanup } from '@testing-library/react';
+import { StromcomContext } from '../StromcomProvider.jsx';
+import { StromcomThread } from '../StromcomThread.jsx';
+
+function renderWithLayer(layer, props) {
+  return render(
+    <StromcomContext.Provider value={layer}>
+      <StromcomThread {...props} />
+    </StromcomContext.Provider>,
+  );
+}
+
+afterEach(() => cleanup());
+
+describe('StromcomThread', () => {
+  it('initializes the thread once on mount with the container element', () => {
+    const layer = { thread: vi.fn() };
+    const { container } = renderWithLayer(layer, { code: 'hashed-thread-1' });
+
+    expect(layer.thread).toHaveBeenCalledTimes(1);
+    expect(layer.thread).toHaveBeenCalledWith(container.firstChild, { code: 'hashed-thread-1' });
+  });
+
+  it('includes optional props that are provided', () => {
+    const layer = { thread: vi.fn() };
+    renderWithLayer(layer, {
+      code: 'hashed-thread-2',
+      name: 'Order #42',
+      url: 'https://example.com/orders/42',
+      userHint: false,
+    });
+
+    expect(layer.thread).toHaveBeenCalledWith(expect.anything(), {
+      code: 'hashed-thread-2',
+      name: 'Order #42',
+      url: 'https://example.com/orders/42',
+      userHint: false,
+    });
+  });
+
+  it('does not re-initialize when props change after mount', () => {
+    const layer = { thread: vi.fn() };
+    const { rerender } = renderWithLayer(layer, { code: 'hashed-thread-3', name: 'A' });
+
+    rerender(
+      <StromcomContext.Provider value={layer}>
+        <StromcomThread code="hashed-thread-3" name="B" />
+      </StromcomContext.Provider>,
+    );
+
+    expect(layer.thread).toHaveBeenCalledTimes(1);
+  });
+
+  it('passes className, style and data-* attributes through to the container div', () => {
+    const layer = { thread: vi.fn() };
+    const { container } = renderWithLayer(layer, {
+      code: 'hashed-thread-4',
+      className: 'my-thread',
+      style: { height: 400 },
+      'data-testid': 'thread-4',
+    });
+
+    const div = container.firstChild;
+    expect(div.className).toBe('my-thread');
+    expect(div.style.height).toBe('400px');
+    expect(div.getAttribute('data-testid')).toBe('thread-4');
+  });
+
+  it('does not call thread and renders an (uninitialized) div when there is no layer', () => {
+    const { container } = render(<StromcomThread code="hashed-thread-5" />);
+
+    expect(container.firstChild).toBeInstanceOf(HTMLDivElement);
+  });
+});

package/src/__tests__/StromcomUser.test.jsx

@@ -0,0 +1,63 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, cleanup } from '@testing-library/react';
+import { StromcomContext } from '../StromcomProvider.jsx';
+import { StromcomUser } from '../StromcomUser.jsx';
+
+function renderWithLayer(layer, props) {
+  return render(
+    <StromcomContext.Provider value={layer}>
+      <StromcomUser {...props} />
+    </StromcomContext.Provider>,
+  );
+}
+
+afterEach(() => cleanup());
+
+describe('StromcomUser', () => {
+  it('calls initUser with only the code when no optional props are given', () => {
+    const layer = { initUser: vi.fn() };
+    renderWithLayer(layer, { code: 'hashed-user-1' });
+
+    expect(layer.initUser).toHaveBeenCalledTimes(1);
+    expect(layer.initUser).toHaveBeenCalledWith({ code: 'hashed-user-1' });
+  });
+
+  it('includes optional props that are provided', () => {
+    const layer = { initUser: vi.fn() };
+    renderWithLayer(layer, {
+      code: 'hashed-user-2',
+      name: 'Jane',
+      emailAddress: 'jane@example.com',
+      readOnly: true,
+      avatarURL: 'https://example.com/avatar.png',
+    });
+
+    expect(layer.initUser).toHaveBeenCalledWith({
+      code: 'hashed-user-2',
+      name: 'Jane',
+      emailAddress: 'jane@example.com',
+      readOnly: true,
+      avatarURL: 'https://example.com/avatar.png',
+    });
+  });
+
+  it('re-calls initUser when a prop changes', () => {
+    const layer = { initUser: vi.fn() };
+    const { rerender } = renderWithLayer(layer, { code: 'hashed-user-3', name: 'Jane' });
+
+    rerender(
+      <StromcomContext.Provider value={layer}>
+        <StromcomUser code="hashed-user-3" name="Janet" />
+      </StromcomContext.Provider>,
+    );
+
+    expect(layer.initUser).toHaveBeenCalledTimes(2);
+    expect(layer.initUser).toHaveBeenLastCalledWith({ code: 'hashed-user-3', name: 'Janet' });
+  });
+
+  it('does not call initUser and renders nothing when there is no layer', () => {
+    const { container } = render(<StromcomUser code="hashed-user-4" />);
+
+    expect(container.firstChild).toBeNull();
+  });
+});

package/src/index.d.ts

@@ -0,0 +1,85 @@
+import type { CSSProperties, ReactNode } from 'react';
+
+export type StromcomEnvironment = 'production' | 'staging' | (string & {});
+
+export interface StromcomLayer {
+  initUser: (options: StromcomUserOptions) => void;
+  thread: (target: HTMLElement, options: StromcomThreadOptions) => void;
+  conf: (options: StromcomConfOptions) => void;
+  home: (target: HTMLElement) => void;
+  [key: string]: any;
+}
+
+export interface StromcomProviderProps {
+  /** Project client key from the Stromcom dashboard. */
+  clientKey: string;
+  /** Bearer token / client secret from the Stromcom dashboard. */
+  clientSecret: string;
+  /** Global JS variable name. Default `"stromCom"`. */
+  dataLayer?: string;
+  /** `"production"`, `"staging"`, or a full custom loader URL. Default `"production"`. */
+  environment?: StromcomEnvironment;
+  children?: ReactNode;
+}
+
+export function StromcomProvider(props: StromcomProviderProps): JSX.Element;
+
+/** Returns the global stromCom object once the loader is set up (or `null` server-side). */
+export function useStromcom(): StromcomLayer | null;
+
+export interface StromcomUserOptions {
+  /** Hashed unique user identifier (max 100 chars, [a-zA-Z0-9-_]). Hash server-side. */
+  code: string;
+  name?: string;
+  emailAddress?: string;
+  readOnly?: boolean;
+  avatarURL?: string;
+}
+
+export function StromcomUser(props: StromcomUserOptions): null;
+
+export interface StromcomThreadOptions {
+  /** Hashed unique thread identifier (max 100 chars, [a-zA-Z0-9-_]). Hash server-side. */
+  code: string;
+  name?: string;
+  url?: string;
+  /** Enable @mention suggestions. Default `true`. */
+  userHint?: boolean;
+}
+
+export interface StromcomThreadProps extends StromcomThreadOptions {
+  className?: string;
+  style?: CSSProperties;
+  [key: `data-${string}`]: string | number | boolean | undefined;
+}
+
+export function StromcomThread(props: StromcomThreadProps): JSX.Element;
+
+export interface StromcomHomeProps {
+  className?: string;
+  style?: CSSProperties;
+  [key: `data-${string}`]: string | number | boolean | undefined;
+}
+
+export function StromcomHome(props: StromcomHomeProps): JSX.Element;
+
+export interface StromcomConfOptions {
+  notificationRenderer?: (notification: unknown) => unknown;
+  onNotification?: (count: number) => void;
+  pageCSSPath?: string;
+  notificationElementTargetElement?:
+    (() => HTMLElement | Promise<HTMLElement>) | HTMLElement | Promise<HTMLElement>;
+  notificationElementShowAlways?: boolean;
+  /** Icon position: 1=top-left, 2=top-right, 3=bottom-right, 4=bottom-left. */
+  notificationElementPosition?: 1 | 2 | 3 | 4;
+  notificationElementStyles?: Record<string, string | number | null>;
+  notificationElementCSSPath?: string;
+  notificationElementNoShadowRoot?: boolean;
+  homeBeforeRender?: () => void | Promise<void>;
+  notificationElementBeforeRender?: () => void | Promise<void>;
+  notificationElementAfterRender?: () => void;
+  /** Theme: `"stromcom-light"`, `"stromcom-dark"`, or `null` to follow browser preference. */
+  theme?: 'stromcom-light' | 'stromcom-dark' | null;
+}
+
+export function StromcomConf(props: StromcomConfOptions): null;

package/src/index.js

@@ -0,0 +1,5 @@
+export { StromcomProvider, useStromcom } from './StromcomProvider.jsx';
+export { StromcomUser } from './StromcomUser.jsx';
+export { StromcomConf } from './StromcomConf.jsx';
+export { StromcomThread } from './StromcomThread.jsx';
+export { StromcomHome } from './StromcomHome.jsx';