Skip to content

Commit

Permalink
Fix docusaurus admonitions
Browse files Browse the repository at this point in the history
  • Loading branch information
duffn authored and floodfx committed Feb 10, 2023
1 parent cbbba3b commit bb293fb
Show file tree
Hide file tree
Showing 165 changed files with 755 additions and 584 deletions.
8 changes: 6 additions & 2 deletions apps/liveviewjs.com/docs/01-overview/paradigm.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,12 @@ receives the events, it runs the business logic for that LiveView, calculates th
the diffs to the client. The client automatically updates the page with the diffs. The server can also send diffs back
to the client based on events on the server or received from other clients (think chat, or other pub/sub scenarios).

:::info **LiveViewJS** solves the complex parts of LiveViews such as connecting and managing web sockets, diffing and
patching the UI, routing events, real-time/multiplayer, file uploads, and more. :::
:::info

**LiveViewJS** solves the complex parts of LiveViews such as connecting and managing web sockets, diffing and
patching the UI, routing events, real-time/multiplayer, file uploads, and more.

:::

## How is this different from SPAs?

Expand Down
16 changes: 12 additions & 4 deletions apps/liveviewjs.com/docs/02-quick-starts/get-liveviewjs-repo.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,12 @@ contains all the examples and configured webserver code for Express (NodeJS) and

Either use `git clone` or `degit` to get the **LiveViewJS** GitHub repository.

:::info `degit` is a lightweight way to clone a repo without the .git parts.
[More info](https://github.com/Rich-Harris/degit). :::
:::info

`degit` is a lightweight way to clone a repo without the .git parts.
[More info](https://github.com/Rich-Harris/degit).

:::

### Clone the **LiveViewJS** GitHub repository:

Expand Down Expand Up @@ -40,8 +44,12 @@ cd liveviewjs
**LiveViewJS** runs on both Node and Deno, but you'll probably want to start down one path or the other depending on what
runtime you are more familiar with or are already using.

:::note The **LiveViewJS** library APIs are the same so you can build your LiveViews on one platform and run them on the
other unless you are using Deno or Node-specific APIs in your LiveView implementation. :::
:::note

The **LiveViewJS** library APIs are the same so you can build your LiveViews on one platform and run them on the
other unless you are using Deno or Node-specific APIs in your LiveView implementation.

:::

### Node

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ browser.

## Setup a new Route

Let's add a route to this LiveView to see it in our browser. Edit `packages/express/src/example/index.ts` and
make the following highlighted changes:
Let's add a route to this LiveView to see it in our browser. Edit `packages/express/src/example/index.ts` and make the
following highlighted changes:

```ts title="packages/express/src/example/index.ts" {3,7}
...
Expand Down Expand Up @@ -60,14 +60,18 @@ Then, start the express server:
npm run start -w packages/express
```
:::info You will probably see a warning from NodeJS about using an experimental feature:
:::info
You will probably see a warning from NodeJS about using an experimental feature:
```
ExperimentalWarning: The Fetch API is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
```
The feature we are using is the built-in `fetch` method. Feel free to ignore this warning. :::
The feature we are using is the built-in `fetch` method. Feel free to ignore this warning.
:::
## See the LiveView in Action
Expand Down Expand Up @@ -105,8 +109,12 @@ should look something like this:
![LiveViewJS Hello World Recording](/img/screenshots/liveviewjs_hello_toggle_liveview_rec.gif)
:::info You'll notice that **LiveViewJS** automatically rebuilds and reloads the server when you make changes to your
LiveView code. This is a great way to iterate quickly on your LiveView. :::
:::info
You'll notice that **LiveViewJS** automatically rebuilds and reloads the server when you make changes to your
LiveView code. This is a great way to iterate quickly on your LiveView.
:::
## Great start!
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,11 @@ to get a feel for the user experience of a LiveView. Let's get started!

[Node.js](https://nodejs.org/en/download/) version 18.x or above.

:::note We rely on the NodeJS Fetch API, which is only available in 18+. :::
:::note

We rely on the NodeJS Fetch API, which is only available in 18+.

:::

If you haven't already, [download the **LiveViewJS** repo](get-liveviewjs-repo).

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,8 +52,12 @@ export const dashboardLiveView = createLiveView<
});
```

:::note The `fetchLatestData` method is not shown here because the implementation is not important. Just assume it
return the latest order, sales, and review data from a database, feed, API, etc. :::
:::note

The `fetchLatestData` method is not shown here because the implementation is not important. Just assume it
return the latest order, sales, and review data from a database, feed, API, etc.

:::

## How it works

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -70,9 +70,13 @@ export const rtCounterLiveView = createLiveView<
});
```

:::info We're using a `SingleProcessPubSub` implementation for simplicity. In a real application, you would use a
:::info

We're using a `SingleProcessPubSub` implementation for simplicity. In a real application, you would use a
`RedisPubSub` implementation in NodeJS or a `BroadcastChannelPubSub` implementation in for Deno. See the
[Pub/Sub docs](/docs/real-time-multi-player-pub-sub/overview) for more details. :::
[Pub/Sub docs](/docs/real-time-multi-player-pub-sub/overview) for more details.

:::

## How it works

Expand Down
16 changes: 12 additions & 4 deletions apps/liveviewjs.com/docs/03-anatomy-of-a-liveview/handle-params.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,16 +40,24 @@ renders:
the LiveView changes. `handleParams` allows developers to access the full `URL` of the LiveView including the `host`,
`path`, `hash`, `pathname`, etc, and then update the `context` of the `socket` or otherwise respond to data in the `URL`.

:::note Worth noting that the http server (e.g., express or oak) handles the routing of the browser to this LiveView. This
:::note

Worth noting that the http server (e.g., express or oak) handles the routing of the browser to this LiveView. This
means that changes in the `URL` for `handleParams` are typically search parameters or hash changes. Changing the host
and/or path of a URL will typically mean the server routes you to a different LiveView (if one exists at that host and
path). :::
path).

:::

## `handleParams` Signature

```ts
handleParams(url: URL, socket: LiveViewSocket<TContext, TInfos>): void | Promise<void>;
```

:::info The `URL` passed to the `handleParams` method is the standard `URL` object, not a **LiveViewJS** specific `URL`
object. See the [MDN URL documentation](https://developer.mozilla.org/en-US/docs/Web/API/URL) for more information. :::
:::info

The `URL` passed to the `handleParams` method is the standard `URL` object, not a **LiveViewJS** specific `URL`
object. See the [MDN URL documentation](https://developer.mozilla.org/en-US/docs/Web/API/URL) for more information.

:::
13 changes: 10 additions & 3 deletions apps/liveviewjs.com/docs/03-anatomy-of-a-liveview/liveview-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,13 @@ sidebar_position: 1

# LiveView API

:::note We are going to be using Typescript in our examples because **LiveViewJS** is very thoroughly typed, which
:::note

We are going to be using Typescript in our examples because **LiveViewJS** is very thoroughly typed, which
provides great type hints, autocompletion, etc. If the typescript syntax is confusing, just ignore it and focus on the
code. :::
code.

:::

## LiveView API is Five Methods

Expand All @@ -15,7 +19,9 @@ The **LiveViewJS** API is extremely simple but very flexible. There are only fiv
four methods (`mount`, `handleEvent`, `handleInfo`, `handleParams`) are optional but usually `mount` and at least one
other `handle` method is defined to enable a dynamic experience.

:::info The smallest, valid LiveView only defines `render` like so:
:::info

The smallest, valid LiveView only defines `render` like so:

```ts
const helloLiveView = createLiveView({
Expand All @@ -24,6 +30,7 @@ const helloLiveView = createLiveView({
```

While "valid" a LiveView like this is not very useful nor particularly exciting. Let's look at a more useful example.

:::

## Example LiveView Implementation
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -63,5 +63,9 @@ export const counterLiveView = createLiveView<
});
```

:::info The `LiveViewSocket` is passed into all methods except for `render`. `LiveViewSocket` is the swiss army knife of
LiveViewJS. We will cover its [API in more detail](/docs/liveview-socket/liveviewsocket-api) shortly. :::
:::info

The `LiveViewSocket` is passed into all methods except for `render`. `LiveViewSocket` is the swiss army knife of
LiveViewJS. We will cover its [API in more detail](/docs/liveview-socket/liveviewsocket-api) shortly.

:::
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,11 @@ export const counterLiveView = createLiveView<
});
```

:::info You might have noticed the `phx-click` attributes present in the `<button>` elements in the example above. These
:::info

You might have noticed the `phx-click` attributes present in the `<button>` elements in the example above. These
are examples of attributes (a.k.a "bindings") that are added to HTML elements that initiate server events based on user
interaction. There are four main types of bindings: click, form, key, focus/blur. We will cover them in more detail
in the [section on User Events](/docs/user-events-slash-bindings/overview). :::
in the [section on User Events](/docs/user-events-slash-bindings/overview).

:::
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,11 @@ socket.pageTitle("My New Page Title");
...
```

:::note The `pageTitle` method does not update the `prefix` or `suffix` part of the `live_title_tag`. :::
:::note

The `pageTitle` method does not update the `prefix` or `suffix` part of the `live_title_tag`.

:::

## `putFlash` Method

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,11 @@ socket.pushEvent({
});
```

:::note Event names are prefixed with `phx:` so an event with the type `my-event` will be sent as `phx:my-event`. :::
:::note

Event names are prefixed with `phx:` so an event with the type `my-event` will be sent as `phx:my-event`.

:::

### Listening for Events on the Client

Expand Down
8 changes: 6 additions & 2 deletions apps/liveviewjs.com/docs/05-lifecycle-of-a-liveview/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,11 +65,15 @@ Below is a sequence diagram showing the "Websocket Join" phase:

![Websocket Join](/img/diagrams/liveview-lifecycle-websocket-join.svg)

:::info You may have noticed both the HTTP request phase and the Websocket Join phase run the same methods. This is
:::info

You may have noticed both the HTTP request phase and the Websocket Join phase run the same methods. This is
because the LiveView is initialized (`mount` => `handleParams` => `render`) in both phases. The HTTP phase doesn't
retain any state but the Websocket phase does keep state in memory so needs to re-run the initialization methods.
Importantly, you may also want to handle HTTP vs Websocket differently in your LiveView so calling the initialization
methods in both phases is important. :::
methods in both phases is important.

:::

#### Interactive Phase

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,15 @@ sidebar_position: 4

Here is a table of all the bindings available in Phoenix LiveView and whether they are available in LiveViewJS.

:::info These bindings actually come from [Phoenix LiveView](https://hexdocs.pm/phoenix_live_view/bindings.html) since
:::info

These bindings actually come from [Phoenix LiveView](https://hexdocs.pm/phoenix_live_view/bindings.html) since
we use the same client-side JavaScript library. The table below denotes which bindings are "Supported" in **LiveViewJS**
and which are not. Bindings below marked with ✅ are working and tested and most of them have example usage in the
`examples` codebase. Those with `?`, we have not gotten around to testing so not sure if they work. Those marked with ❌
are not yet implemented and known not to work. :::
are not yet implemented and known not to work.

:::

| Binding | Attribute | Supported |
| --------------- | -------------------- | --------- |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -62,10 +62,14 @@ submission.
Adding `phx-submit` to a form means that when the user submits the form, the `save` event will be sent to the server
along with all the form values.

:::info In LiveViewJS, Forms are typically used in conjunction with
:::info

In LiveViewJS, Forms are typically used in conjunction with
[`LiveViewChangeset`](/docs/forms-and-changesets/changesets)s. `LiveViewChangeset`s are designed to work together with
form events to make form validation and submission easy and powerful. We'll dive into more details later on in the next
section. :::
section.

:::

### Key Events

Expand Down
16 changes: 12 additions & 4 deletions apps/liveviewjs.com/docs/07-forms-and-changesets/changesets.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,15 @@ with static type inference" library.

Let's go through the steps of creating a changeset helper for a Book data model.

:::info The [basics of Zod](https://github.com/colinhacks/zod#basic-usage) are pretty easy to pick up especially if you
:::info

The [basics of Zod](https://github.com/colinhacks/zod#basic-usage) are pretty easy to pick up especially if you
are familiar with Typescript. Even if you are not too familiar with Zod or Typescript, the concept is Zod is pretty
straight forward. Essentially you are defining a schema and then parsing the input data against the schema. If the input
data matches the schema then the data is valid. If the input data does not match the schema then the data is invalid and
you can use the error messages to display validation errors to the user. :::
you can use the error messages to display validation errors to the user.

:::

## Create a Zod Schema

Expand Down Expand Up @@ -159,8 +163,12 @@ impact the `valid` property of the `LiveViewChangeset` returned by the `LiveView
string is NOT set** the `valid` property will always return `true`. **If the action string IS set** the `valid` property
will return `true` if the data is valid and `false` if the data is invalid.

:::note We pass "empty" (i.e., no action string) changesets to form helpers in the `render` function otherwise there
would be errors on the form when the page is first loaded. "Empty" changesets are always valid. :::
:::note

We pass "empty" (i.e., no action string) changesets to form helpers in the `render` function otherwise there
would be errors on the form when the page is first loaded. "Empty" changesets are always valid.

:::

## Next Steps

Expand Down
8 changes: 6 additions & 2 deletions apps/liveviewjs.com/docs/07-forms-and-changesets/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,13 @@ We have not yet discussed the concept of a "changeset" in LiveViewJS. At a high
validate that incoming JSON data maps to the expected constraints. You will see it is a very powerful concept that
allows you to build and validate complex forms with ease.

:::note Changesets are a concept that is taken from an Elixir library called
:::note

Changesets are a concept that is taken from an Elixir library called
[Ecto](https://hexdocs.pm/ecto/Ecto.Changeset.html). Ecto changesets are used to validate and persist data to a
database. While **LiveViewJS** changeset are not ORM or DB releated, we've taken the concept of a changeset and adapted
it to the Typescript world for parsing and validation. :::
it to the Typescript world for parsing and validation.

:::

We will take a deep dive into Changesets in a more detail in the next section.
Loading

0 comments on commit bb293fb

Please sign in to comment.