Skip to content

Commit

Permalink
udpate docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Harley Alexander committed Feb 13, 2020
1 parent 9c270b7 commit ac90b4d
Show file tree
Hide file tree
Showing 24 changed files with 1,070 additions and 719 deletions.
93 changes: 47 additions & 46 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
## Install

```bash
yarn add use-pusher
yarn add @harelpls/use-pusher
```

## Hooks
Expand All @@ -24,25 +24,25 @@ yarn add use-pusher

You must wrap your app with a `PusherProvider` and pass it config props for [`pusher-js`](https://github.com/pusher/pusher-js) initialisation.

```tsx
import React from "react";
import { PusherProvider } from "@city-dna/use-pusher";
```typescript
import React from 'react';
import { PusherProvider } from '@harelpls/use-pusher';

const config = {
// required config props
clientKey: "client-key",
cluster: "ap4",
clientKey: 'client-key',
cluster: 'ap4',

// optional if you'd like to trigger events. BYO endpoint.
// see "Trigger Server" below for more info
triggerEndpoint: "/pusher/trigger",
triggerEndpoint: '/pusher/trigger',

// required for private/presence channels
// also sends auth headers to trigger endpoint
authEndpoint: "/pusher/auth",
authEndpoint: '/pusher/auth',
auth: {
headers: { Authorization: "Bearer token" }
}
headers: { Authorization: 'Bearer token' },
},
};

// Wrap app in provider
Expand All @@ -57,16 +57,16 @@ const App = () => {

Use this hook to subscribe to a channel.

```tsx
```typescript
// returns channel instance.
const channel = useChannel("channel-name");
const channel = useChannel('channel-name');
```

## `usePresenceChannel`

Augments a regular channel with member functionality.

```tsx
```typescript
const Example = () => {
const { members, myID } = usePresenceChannel('presence-awesome');

Expand All @@ -89,13 +89,13 @@ const Example = () => {

Bind to events on a channel with a callback.

```tsx
```typescript
const Example = () => {
const [message, setMessages] = useState();
const channel = useChannel("channel-name");
const channel = useChannel('channel-name');
useEvent(
channel,
"message",
'message',
({ data }) => setMessages(messages => [...messages, data]),
// optional dependencies array. Passed through to useCallback. Defaults to [].
[]
Expand All @@ -107,8 +107,8 @@ const Example = () => {

A helper function to create a **server triggered** event. BYO server (See [Trigger Server](#trigger-server) below). Pass in `triggerEndpoint` prop to `<PusherProvider />`. Any auth headers from `config.auth.headers` automatically get passed to the `fetch` call.

```tsx
import {useTrigger} from 'use-pusher';
```typescript
import { useTrigger } from '@harelpls/use-pusher';

const Example = () => {.
const trigger = useTrigger();
Expand All @@ -125,12 +125,12 @@ const Example = () => {.

Get access to the Pusher instance to do other things.

```tsx
import { usePusher } from "use-pusher";
```typescript
import { usePusher } from '@harelpls/use-pusher';

const Example = () => {
const { client } = usePusher();
client.log("Look ma, logs!");
client.log('Look ma, logs!');

return null;
};
Expand All @@ -140,14 +140,14 @@ const Example = () => {

In order to trigger an event, you'll have to create a simple lambda (or an express server if that's your thing). Below is a short lambda that can handle triggered events from `useTrigger`.

```tsx
import Pusher from "pusher";
```typescript
import Pusher from 'pusher';

const pusher = new Pusher({
appId: "app-id",
key: "client-key",
secret: "mad-secret",
cluster: "ap4"
appId: 'app-id',
key: 'client-key',
secret: 'mad-secret',
cluster: 'ap4',
});

export async function handler(event) {
Expand All @@ -159,15 +159,16 @@ export async function handler(event) {

> _I don't want a server though_
I hear ya. If you're feeling audacious, you can use [client events](https://pusher.com/docs/channels/using_channels/events#triggering-client-events) to push directly from the client, though this isn't recommended (thus no hook):
I hear ya. If you're feeling audacious, you can use [client events](https://pusher.com/docs/channels/using_channels/events#triggering-client-events) to push directly from the client:

```tsx
import { useChannel } from "use-pusher";
```typescript
import { useChannel, useClientTrigger } from '@harelpls/use-pusher';

const Example = () => {
const channel = useChannel("danger-zone");
const channel = useChannel('presence-danger-zone');
const trigger = useClientTrigger(channel);
const handleClientEvent = () => {
channel.trigger("Pew pew");
trigger('Pew pew');
};

return <button onClick={handleClientEvent}>Fire</button>;
Expand All @@ -184,33 +185,33 @@ Typed `PusherMock`, `PusherChannelMock` and `PusherPresenceChannelMock` utils ar

Testing emitted events with jest can be achieved using `jest.mock` and `react-testing-library` (or `enzyme`, though your tests should reflect what the user should see **NOT** how the component handles events internally):

```tsx
```typescript
// Example.tsx
import React from "react";
import { useChannel, useEvent } from "use-pusher";
import React from 'react';
import { useChannel, useEvent } from '@harelpls/use-pusher';

const Example = () => {
const [title, setTitle] = useState();
const channel = useChannel("my-channel");
useEvent(channel, "title", ({ data }) => setTitle(data));
const channel = useChannel('my-channel');
useEvent(channel, 'title', ({ data }) => setTitle(data));

return <span>{title}</span>;
};

// Example.test.tsx
import { render, act } from "@testing-library/react";
import { PusherMock, PusherChannelMock } from "use-pusher";
import { render, act } from '@testing-library/react';
import { PusherMock, PusherChannelMock } from '@harelpls/use-pusher';

// mock out the result of the useChannel hook
const mockChannel = new PusherChannelMock();
jest.mock("use-pusher", () => ({
...require.requireActual("use-pusher"),
useChannel: () => mockChannel
jest.mock('@harelpls/use-pusher', () => ({
...require.requireActual('@harelpls/use-pusher'),
useChannel: () => mockChannel,
}));

test("should show a title when it receives a title event", async () => {
test('should show a title when it receives a title event', async () => {
// mock the client
const client = { current: new PusherMock("client-key", { cluster: "ap4" }) };
const client = { current: new PusherMock('client-key', { cluster: 'ap4' }) };

// render component and provider with a mocked context value
const { findByText } = render(
Expand All @@ -220,10 +221,10 @@ test("should show a title when it receives a title event", async () => {
);

// emit an event on the mocked channel
act(() => mockChannel.emit("title", { data: "Hello world" }));
act(() => mockChannel.emit('title', { data: 'Hello world' }));

// assert expectations
expect(await findByText("Hello world")).toBeInTheDocument();
expect(await findByText('Hello world')).toBeInTheDocument();
});
```

Expand Down
104 changes: 46 additions & 58 deletions docs/assets/css/main.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -492,6 +492,8 @@ ul.tsd-descriptions > li > :last-child > :last-child > :last-child {
padding-bottom: 200px; }

.row {
display: -ms-flexbox;
display: flex;
position: relative;
margin: 0 -10px; }
.row:after {
Expand Down Expand Up @@ -585,7 +587,7 @@ ul.tsd-descriptions > li > :last-child > :last-child > :last-child {
height: 17px;
margin: 0 3px 2px 0;
background-image: url(../images/icons.png); }
@media (-webkit-min-device-pixel-ratio: 1.5), (min-device-pixel-ratio: 1.5), (min-resolution: 144dpi) {
@media (-webkit-min-device-pixel-ratio: 1.5), (min-resolution: 144dpi) {
.tsd-kind-icon:before {
background-image: url(../images/icons@2x.png);
background-size: 238px 204px; } }
Expand Down Expand Up @@ -1556,7 +1558,6 @@ pre {
position: fixed !important;
overflow: auto;
-webkit-overflow-scrolling: touch;
overflow-scrolling: touch;
z-index: 1024;
top: 0 !important;
bottom: 0 !important;
Expand Down Expand Up @@ -1645,7 +1646,6 @@ html.minimal .tsd-navigation {
position: fixed !important;
overflow: auto;
-webkit-overflow-scrolling: touch;
overflow-scrolling: touch;
box-sizing: border-box;
z-index: 1;
left: 0;
Expand Down Expand Up @@ -1823,11 +1823,6 @@ footer {
-o-column-count: 2;
column-count: 2; } }
.tsd-index-panel ul.tsd-index-list li {
-webkit-column-break-inside: avoid;
-moz-column-break-inside: avoid;
-ms-column-break-inside: avoid;
-o-column-break-inside: avoid;
column-break-inside: avoid;
-webkit-page-break-inside: avoid;
-moz-page-break-inside: avoid;
-ms-page-break-inside: avoid;
Expand Down Expand Up @@ -1884,7 +1879,7 @@ footer {
border-bottom: none; }

.tsd-navigation {
padding: 0 0 0 40px; }
margin: 0 0 0 40px; }
.tsd-navigation a {
display: block;
padding-top: 2px;
Expand Down Expand Up @@ -1934,56 +1929,45 @@ footer {
.tsd-navigation.primary li.globals + li > a {
padding-top: 20px; }

.tsd-navigation.secondary ul {
transition: opacity 0.2s; }
.tsd-navigation.secondary ul li a {
padding-left: 25px; }
.tsd-navigation.secondary ul li li a {
padding-left: 45px; }
.tsd-navigation.secondary ul li li li a {
padding-left: 65px; }
.tsd-navigation.secondary ul li li li li a {
padding-left: 85px; }
.tsd-navigation.secondary ul li li li li li a {
padding-left: 105px; }
.tsd-navigation.secondary ul li li li li li li a {
padding-left: 125px; }
.tsd-navigation.secondary ul.current a {
.tsd-navigation.secondary {
max-height: calc(100vh - 1rem - 40px);
overflow: auto;
position: -webkit-sticky;
position: sticky;
top: calc(.5rem + 40px);
transition: .3s; }
.tsd-navigation.secondary.tsd-navigation--toolbar-hide {
max-height: calc(100vh - 1rem);
top: .5rem; }
.tsd-navigation.secondary ul {
transition: opacity 0.2s; }
.tsd-navigation.secondary ul li a {
padding-left: 25px; }
.tsd-navigation.secondary ul li li a {
padding-left: 45px; }
.tsd-navigation.secondary ul li li li a {
padding-left: 65px; }
.tsd-navigation.secondary ul li li li li a {
padding-left: 85px; }
.tsd-navigation.secondary ul li li li li li a {
padding-left: 105px; }
.tsd-navigation.secondary ul li li li li li li a {
padding-left: 125px; }
.tsd-navigation.secondary ul.current a {
border-left-color: #eee; }
.tsd-navigation.secondary li.focus > a,
.tsd-navigation.secondary ul.current li.focus > a {
border-left-color: #000; }
.tsd-navigation.secondary li.current {
margin-top: 20px;
margin-bottom: 20px;
border-left-color: #eee; }

.tsd-navigation.secondary li.focus > a,
.tsd-navigation.secondary ul.current li.focus > a {
border-left-color: #000; }

.tsd-navigation.secondary li.current {
margin-top: 20px;
margin-bottom: 20px;
border-left-color: #eee; }
.tsd-navigation.secondary li.current > a {
font-weight: bold; }
.tsd-navigation.secondary li.current > a {
font-weight: bold; }

@media (min-width: 901px) {
.menu-sticky-wrap {
position: static; }
.no-csspositionsticky .menu-sticky-wrap.sticky {
position: fixed; }
.no-csspositionsticky .menu-sticky-wrap.sticky-current {
position: fixed; }
.no-csspositionsticky .menu-sticky-wrap.sticky-current ul.before-current,
.no-csspositionsticky .menu-sticky-wrap.sticky-current ul.after-current {
opacity: 0; }
.no-csspositionsticky .menu-sticky-wrap.sticky-bottom {
position: absolute;
top: auto !important;
left: auto !important;
bottom: 0;
right: 0; }
.csspositionsticky .menu-sticky-wrap.sticky {
position: -webkit-sticky;
position: sticky; }
.csspositionsticky .menu-sticky-wrap.sticky-current {
position: -webkit-sticky;
position: sticky; } }
position: static; } }

.tsd-panel {
margin: 20px 0;
Expand Down Expand Up @@ -2204,15 +2188,16 @@ ul.tsd-type-parameters {
padding: 0; }

.tsd-page-toolbar {
position: absolute;
position: fixed;
z-index: 1;
top: 0;
left: 0;
width: 100%;
height: 40px;
color: #333;
background: #fff;
border-bottom: 1px solid #eee; }
border-bottom: 1px solid #eee;
transition: transform .3s linear; }
.tsd-page-toolbar a {
color: #333;
text-decoration: none; }
Expand All @@ -2232,6 +2217,9 @@ ul.tsd-type-parameters {
.tsd-page-toolbar .table-cell:first-child {
width: 100%; }

.tsd-page-toolbar--hide {
transform: translateY(-100%); }

.tsd-widget:before, .tsd-select .tsd-select-label:before, .tsd-select .tsd-select-list li:before {
content: '';
display: inline-block;
Expand All @@ -2242,7 +2230,7 @@ ul.tsd-type-parameters {
background-repeat: no-repeat;
text-indent: -1024px;
vertical-align: bottom; }
@media (-webkit-min-device-pixel-ratio: 1.5), (min-device-pixel-ratio: 1.5), (min-resolution: 144dpi) {
@media (-webkit-min-device-pixel-ratio: 1.5), (min-resolution: 144dpi) {
.tsd-widget:before, .tsd-select .tsd-select-label:before, .tsd-select .tsd-select-list li:before {
background-image: url(../images/widgets@2x.png);
background-size: 320px 40px; } }
Expand Down
2 changes: 1 addition & 1 deletion docs/assets/js/main.js
View file

Large diffs are not rendered by default.

Loading

0 comments on commit ac90b4d

Please sign in to comment.