Skip to content

Commit

Permalink
docs
Browse files Browse the repository at this point in the history
  • Loading branch information
stereobooster committed Dec 4, 2024
1 parent efd81b3 commit ba74e2f
Show file tree
Hide file tree
Showing 16 changed files with 228 additions and 38 deletions.
4 changes: 0 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,3 @@ Ideas for other diagrams: [Text to Diagram](https://stereobooster.com/posts/text
## Logo

The logo is an illustration from [Oliver Byrne's Elements of Euclid: The First Six Books with Coloured Diagrams and Symbols](https://www.c82.net/euclid/).

## TODO

- online example for pan-zoom
7 changes: 6 additions & 1 deletion packages/demo/astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,15 @@ export default defineConfig({
{
label: "Start here",
autogenerate: { directory: "start-here" },
},{
},
{
label: "Diagrams",
autogenerate: { directory: "diagrams" },
},
{
label: "Other",
autogenerate: { directory: "other" },
},
{
label: "Notes",
autogenerate: { directory: "notes" },
Expand Down
14 changes: 13 additions & 1 deletion packages/demo/src/content/docs/diagrams/d2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -57,8 +57,20 @@ Check out other [options](/start-here/configuration/).

### Configuration

You probaly want to use `file` strategy and one of dark schemes (`class` or `media`). Unless you need interactivity.
You probaly want to use [`file`](/start-here/strategy/#file) strategy and one of dark schemes (`class` or `media`). Unless you need [interactivity](/start-here/interactivity/).

## Tips

### Note about Netlify

You can create small Netlify plugin to install D2. See example [here](https://github.com/stereobooster/beoe/tree/main/plugins/netlify-plugin-d2)

## Issues

- [ ] [Support links in connections](https://github.com/terrastruct/d2/pull/1955)
- [ ] [JS package](https://github.com/terrastruct/d2/discussions/234#discussioncomment-11286029)
- [ ] [Remove embeded fonts](https://github.com/terrastruct/d2/discussions/132)
- [ ] [Smaller embeded icons](https://github.com/terrastruct/d2/discussions/2223)
- [ ] [Export JSON graph](https://github.com/terrastruct/d2/discussions/2224)
- [ ] [Class-based dark mode](https://github.com/terrastruct/d2/discussions/2225)
- [ ] Link resolution callback
2 changes: 1 addition & 1 deletion packages/demo/src/content/docs/diagrams/gnuplot.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ Check out other [options](/start-here/configuration/).

### Configuration

You probaly want to use `file` strategy. This tool doesn't support dark scheme.
You probaly want to use [`file`](/start-here/strategy/#file) strategy. This tool doesn't support dark scheme.

## Bonus: XKCD-style

Expand Down
2 changes: 1 addition & 1 deletion packages/demo/src/content/docs/diagrams/mermaid.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Check out other [options](/start-here/configuration/).

### Configuration

You probaly want to use `file` strategy and one of dark schemes (`class` or `media`). Unless you need interactivity.
You probaly want to use [`file`](/start-here/strategy/#file) strategy and one of dark schemes (`class` or `media`). Unless you need [interactivity](/start-here/interactivity/).

## How is it different from `rehype-mermaid`?

Expand Down
8 changes: 4 additions & 4 deletions packages/demo/src/content/docs/diagrams/vizdom.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -175,8 +175,8 @@ You probaly want to use `inline` strategy and implement dark scheme via CSS:

`inline` strategy allows to use [interactivity](/start-here/interactivity/).

## Notes
## Issues

- HTML classes are not supported
- Text is transformed to path, so <kbd>Cmd</kbd> + <kbd>F</kbd> doesn't work
- Doesn't support some unicode chars, like `label="∅"`
- [ ] [HTML classes are not supported](https://github.com/vizdom-dev/vizdom/issues/11)
- [ ] [Text is transformed to path, so <kbd>Cmd</kbd> + <kbd>F</kbd> doesn't work](https://github.com/vizdom-dev/vizdom/issues/12)
- [ ] Doesn't support some unicode chars, like `label="∅"`
4 changes: 4 additions & 0 deletions packages/demo/src/content/docs/other/cache.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: "@beoe/cache"
draft: true
---
4 changes: 4 additions & 0 deletions packages/demo/src/content/docs/other/fenceparser.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: "@beoe/fenceparser"
draft: true
---
10 changes: 0 additions & 10 deletions packages/demo/src/content/docs/other/index.md

This file was deleted.

181 changes: 181 additions & 0 deletions packages/demo/src/content/docs/other/pan-zoom.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,181 @@
---
title: "@beoe/pan-zoom"
---

```gnuplot
set grid nopolar
set grid xtics nomxtics ytics nomytics noztics nomztics nortics nomrtics \
nox2tics nomx2tics noy2tics nomy2tics nocbtics nomcbtics
set grid layerdefault lt 0 linecolor 0 linewidth 0.500, lt 0 linecolor 0 linewidth 0.500
set samples 21, 21
set isosamples 11, 11
set style data lines
set title "3D surface from a function"
set xlabel "X axis"
set xlabel offset character -3, -2, 0 font "" textcolor lt -1 norotate
set xrange [ -10.0000 : 10.0000 ] noreverse nowriteback
set x2range [ * : * ] noreverse writeback
set ylabel "Y axis"
set ylabel offset character 3, -2, 0 font "" textcolor lt -1 rotate
set yrange [ -10.0000 : 10.0000 ] noreverse nowriteback
set y2range [ * : * ] noreverse writeback
set zlabel "Z axis"
set zlabel offset character -5, 0, 0 font "" textcolor lt -1 norotate
set zrange [ * : * ] noreverse writeback
set cbrange [ * : * ] noreverse writeback
set rrange [ * : * ] noreverse writeback
set colorbox vertical origin screen 0.9, 0.2 size screen 0.05, 0.6 front noinvert bdefault
NO_ANIMATION = 1
## Last datafile plotted: "$grid"
splot x**2+y**2, x**2-y**2
```

Small JS library to add **pan and zoom** functionality to **SVG** (inline or image). It supports **gestures** for all types of devices:

| intention | mouse | trackpad/touchpad | touchscren |
| --------- | ----------------------- | ----------------- | --------------- |
| pan | click + move | click + move | two finger drag |
| zoom | <kbd>Ctrl</kbd> + wheel | pinch | pinch |
| reset | double click | double click | double tap |
| | | | |
| scroll | wheel | two finger drag | one finger drag |

Pay attention:

- gestures intentionally selected to not interfere with the system's default scroll gestures, **to avoid "scroll traps"**
- all actions are available through gestures, so it works without UI. You can add UI, though. Library exposes methods for this, like `pan(dx, dy)` and `zoom(scale)`
- <kbd>Cmd</kbd> + click - zoom in
- <kbd>Alt</kbd> + click - zoom out
- First double click (tap) - zoom in x2

## Usage

There are two flavors:

- Headless - without UI
- Default UI

### Headless

If you **have container** element in HTML:

```ts
import { PanZoom } from "@beoe/pan-zoom";

document.querySelectorAll(".beoe").forEach((container) => {
const element = container.firstElementChild;
if (!element) return;
new PanZoom({ element, container }).on();
});
```

If you **don't have** container element in HTML:

```ts
import { PanZoom } from "@beoe/pan-zoom";

document.querySelectorAll("svg, img[src$='.svg' i]").forEach((element) => {
if (element.parentElement?.tagName === "PICTURE") {
element = element.parentElement;
}
const container = document.createElement("div");
container.className = "beoe";
element.replaceWith(container);
container.append(element);
new PanZoom({ element, container }).on();
});
```

Additionally following CSS is required:

```css
.beoe {
overflow: hidden;
touch-action: pan-x pan-y;
user-select: none;
cursor: grab;
}

.beoe svg,
.beoe img {
/* need to center smaller images to fix bug in zoom functionality */
margin: auto;
display: block;
/* need to fit bigger images */
max-width: 100%;
height: auto;
}

.beoe img {
pointer-events: none;
}
```

Instance methods:

- `on()` - adds event listeners
- `off()` - removes event listeners
- `pan(dx, dy)` - pans image
- `zoom(scale)` - zooms image
- `reset()` - resets pan and zoom values

### Default UI

```ts
import "@beoe/pan-zoom/css/PanZoomUi.css";
import { PanZoomUi } from "@beoe/pan-zoom";

document.querySelectorAll(".beoe").forEach((container) => {
const element = container.firstElementChild;
if (!element) return;
new PanZoomUi({ element, container }).on();
});
```

Additionally, CSS to style UI required (for example with Tailwind):

```css
.beoe .buttons {
@apply inline-flex;
}
.beoe .zoom-in {
@apply bg-gray-300 hover:bg-gray-400 text-gray-800 font-bold py-2 px-4 rounded-l;
}
.beoe .reset {
@apply bg-gray-300 hover:bg-gray-400 text-gray-800 font-bold py-2 px-4;
}
.beoe .zoom-out {
@apply bg-gray-300 hover:bg-gray-400 text-gray-800 font-bold py-2 px-4 rounded-r;
}
```

You can configure HTML classes used by UI:

```ts
const classes = {
zoomIn: "zoom-in",
reset: "reset",
zoomOut: "zoom-out",
buttons: "buttons",
tsWarning: "touchscreen-warning",
tsWarningActive: "active",
};

new PanZoomUi({ element, container, classes });
```

and message with instructions for the touchscreen:

```ts
const message = "Use two fingers to pan and zoom";

new PanZoomUi({ element, container, message });
```

## Pixelation in Safari

Be aware that some CSS will cause pixelation of SVG on zoom (bug in Safari), for example:

- `will-change: transform;`
- `transform: matrix3d(...);`
- `transition-property: transform;` (it setles after animation, though)
4 changes: 4 additions & 0 deletions packages/demo/src/content/docs/other/rehype-code-hook.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: "@beoe/rehype-code-hook"
draft: true
---
4 changes: 4 additions & 0 deletions packages/demo/src/content/docs/other/remark-code-hook.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: "@beoe/remark-code-hook"
draft: true
---
4 changes: 4 additions & 0 deletions packages/demo/src/content/docs/other/sqlitecache.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: "@beoe/sqlitecache"
draft: true
---
Original file line number Diff line number Diff line change
Expand Up @@ -453,5 +453,5 @@ document.querySelectorAll(".vizdom.ants").forEach((container) => {
### Notes

- JS and CSS for those examples are not included in Vizdom Rehype plugin, but feel free to copy (from this website) and modify them
- Graphviz Rehype plugin also provides option for `data` (`dataGraph=dagre`), but ids in SVG are consistent with ids in JSON. So it doesn't really work
- Graphviz Rehype plugin also provides option for `data` (`dataGraph=dagre`), but ids in SVG are not consistent with ids in JSON. So it doesn't really work
- [Request to support JSON representation for D2](https://github.com/terrastruct/d2/discussions/2224)
6 changes: 1 addition & 5 deletions packages/pan-zoom/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,11 +27,7 @@ Pay attention:

## Demo

**TODO**: update demo - this is an old one

[![Netlify Status](https://api.netlify.com/api/v1/badges/4bdb3997-ed5f-4506-bb77-95595d2e6562/deploy-status)](https://app.netlify.com/sites/svg-pan-zoom/deploys)

[pan-zoom demo](https://svg-pan-zoom.stereobooster.com/)
[pan-zoom demo](https://beoe.stereobooster.com/other/pan-zoom/)

## Usage

Expand Down
10 changes: 0 additions & 10 deletions packages/rehype-d2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,3 @@ const html = await unified()
```

[Online documentation](https://beoe.stereobooster.com/diagrams/d2/) provides more details.

## Awaited features

- [ ] [Support link in connections](https://github.com/terrastruct/d2/pull/1955)
- [ ] [JS package](https://github.com/terrastruct/d2/discussions/234#discussioncomment-11286029)
- [ ] [Remove embeded fonts](https://github.com/terrastruct/d2/discussions/132)
- [ ] [Smaller embeded icons](https://github.com/terrastruct/d2/discussions/2223)
- [ ] [Export JSON graph](https://github.com/terrastruct/d2/discussions/2224)
- [ ] [Class-based dark mode](https://github.com/terrastruct/d2/discussions/2225)
- [ ] Link resolution callback

0 comments on commit ba74e2f

Please sign in to comment.