Merge pull request #526 from Tragio/master

Added docs website
haltu · Sep 9, 2022 · 9551104 · 9551104
2 parents 1911552 + 57a51da
commit 9551104
Show file tree

Hide file tree

Showing 19 changed files with 4,835 additions and 47 deletions.
diff --git a/.gitignore b/.gitignore
@@ -4,4 +4,5 @@ website
 /website
 *.log
 *.env
-*.DS_Store
+*.DS_Store
+docs/.vitepress/dist
diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
@@ -0,0 +1,102 @@
+import { version } from '../../package.json';
+
+export default {
+  lang: 'en-US',
+  title: 'Muuri',
+  description: 'Build all kinds of layouts',
+
+  head: [['link', { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' }]],
+
+  lastUpdated: true,
+
+  // Experimental Feature - it is giving 404 when reloading the page in the docs
+  // cleanUrls: 'without-subfolders',
+
+  themeConfig: {
+    logo: '/logo.svg',
+
+    nav: nav(),
+
+    sidebar: {
+      '/': sidebarGuide(),
+    },
+
+    editLink: {
+      pattern: 'https://github.com/haltu/muuri/edit/main/docs/:path',
+      text: 'Edit this page on GitHub',
+    },
+
+    socialLinks: [{ icon: 'github', link: 'https://github.com/haltu/muuri' }],
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2017-present Niklas Rämö',
+    },
+
+    algolia: {
+      appId: 'xxxxx',
+      apiKey: 'xxxxx',
+      indexName: 'muuri',
+    },
+
+    // carbonAds: {
+    //   code: "xxxxx",
+    //   placement: "xxxxx",
+    // },
+  },
+};
+
+function nav() {
+  return [
+    { text: 'Docs', link: '/what-is-muuri', activeMatch: '/' },
+    {
+      text: 'Examples',
+      link: '/examples',
+      activeMatch: '/examples',
+    },
+    {
+      text: version,
+      items: [
+        {
+          text: 'Changelog',
+          link: 'https://github.com/haltu/muuri/releases',
+        },
+        {
+          text: 'Contributing',
+          link: 'https://github.com/haltu/muuri/blob/master/CONTRIBUTING.md',
+        },
+      ],
+    },
+  ];
+}
+
+function sidebarGuide() {
+  return [
+    {
+      text: 'Introduction',
+      collapsible: true,
+      items: [
+        { text: 'What is Muuri?', link: '/' },
+        { text: 'Getting Started', link: '/getting-started' },
+        { text: 'Motivation', link: '/motivation' },
+        { text: 'Credits', link: '/credits' },
+      ],
+    },
+    {
+      text: 'API',
+      collapsible: true,
+      items: [
+        { text: 'Grid Constructor', link: '/grid-constructor' },
+        { text: 'Grid Options', link: '/grid-options' },
+        { text: 'Grid Methods', link: '/grid-methods' },
+        { text: 'Grid Events', link: '/grid-events' },
+        { text: 'Item Methods', link: '/item-methods' },
+      ],
+    },
+    {
+      text: 'Examples',
+      collapsible: true,
+      items: [{ text: 'Demos', link: '/examples' }],
+    },
+  ];
+}
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
@@ -0,0 +1,7 @@
+:root {
+    --vp-c-brand: #ED6EE3;
+    --vp-c-brand-light: #ED6EE3;
+    --vp-c-brand-lighter:#FA73EF;
+    --vp-c-green-dark:#B958D6;
+    --vp-button-brand-bg: #ED6EE3;
+  }
diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js
@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme';
+import './custom.css';
+
+export default DefaultTheme;
diff --git a/docs/credits.md b/docs/credits.md
@@ -0,0 +1,8 @@
+# Credits
+
+**Created and maintained by [Niklas Rämö](https://github.com/niklasramo).**
+
+- This project owes much to David DeSandro's [Masonry](http://masonry.desandro.com/), [Packery](http://packery.metafizzy.co/) and [Isotope](https://isotope.metafizzy.co/) libraries. You should go ahead and check them out right now if you haven't yet. Thanks Dave!
+- Jukka Jylänki's [survey](https://github.com/juj/RectangleBinPack) "A Thousand Ways to Pack the Bin - A Practical Approach to Two-Dimensional Rectangle Bin Packing" came in handy when building Muuri's layout algorithms. Thanks Jukka!
+- Big thanks to the people behind [Web Animations polyfill](https://github.com/web-animations/web-animations-js) for making it possible to use Web Animations API reliably across browsers today.
+- [Haltu Oy](http://www.haltu.fi/) was responsible for initiating this project in the first place and funded the initial development. Thanks Haltu!
diff --git a/docs/examples.md b/docs/examples.md
@@ -0,0 +1,113 @@
+# Examples
+
+## Barebones Grid
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: barebones grid" src="https://codepen.io/niklasramo/embed/preview/wpwNjK?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/niklasramo/pen/wpwNjK">
+  Muuri: barebones grid</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+## Basic Sorting
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: basic sorting" src="https://codepen.io/niklasramo/embed/preview/EvXoOG?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/niklasramo/pen/EvXoOG">
+  Muuri: basic sorting</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+## Basic Vertical Grid With Dragging
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: basic vertical grid with dragging" src="https://codepen.io/niklasramo/embed/preview/jyJLGM?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/niklasramo/pen/jyJLGM">
+  Muuri: basic vertical grid with dragging</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+## Basic Horizontal Grid With Dragging
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: basic horizontal grid with dragging" src="https://codepen.io/niklasramo/embed/preview/xPoVPe?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/niklasramo/pen/xPoVPe">
+  Muuri: basic horizontal grid with dragging</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+## Multiple Instances
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri demo: multiple instances" src="https://codepen.io/niklasramo/embed/preview/wJKMQz?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/niklasramo/pen/wJKMQz">
+  Muuri demo: multiple instances</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+## Links As Grid Items
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: links as grid items" src="https://codepen.io/niklasramo/embed/preview/ZvzVpg?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/niklasramo/pen/ZvzVpg">
+  Muuri: links as grid items</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+## Prevent Dragging For Specific Items
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: prevent dragging for specific items" src="https://codepen.io/niklasramo/embed/preview/LOzZPo?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/niklasramo/pen/LOzZPo">
+  Muuri: prevent dragging for specific items</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+## Custom Layout Algorithm
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: custom layout algorithm" src="https://codepen.io/niklasramo/embed/preview/LLbLLd?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/niklasramo/pen/LLbLLd">
+  Muuri: custom layout algorithm</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+## Simple Kanban (With Scrolling Containers)
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: simple kanban (with scrolling containers)" src="https://codepen.io/niklasramo/embed/preview/BrYaOp?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/niklasramo/pen/BrYaOp">
+  Muuri: simple kanban (with scrolling containers)</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+## Images Inside Grid Items
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: images inside grid items" src="https://codepen.io/niklasramo/embed/preview/xWYdmp?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/niklasramo/pen/xWYdmp">
+  Muuri: images inside grid items</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+## Saving And Loading Layout
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: saving and loading layout" src="https://codepen.io/niklasramo/embed/preview/YveqNN?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/niklasramo/pen/YveqNN">
+  Muuri: saving and loading layout</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+## Clone Item Back To Original Grid When Dropping To Another Grid
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri demo: clone item back to original grid when dropping to another grid" src="https://codepen.io/niklasramo/embed/preview/zPVBLq?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/niklasramo/pen/zPVBLq">
+  Muuri demo: clone item back to original grid when dropping to another grid</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+## Blocked First Item
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: blocked first item" src="https://codepen.io/niklasramo/embed/preview/EEdmJr?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/niklasramo/pen/EEdmJr">
+  Muuri: blocked first item</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+## Drag Start Delay On Touch
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: drag start delay on touch" src="https://codepen.io/niklasramo/embed/preview/WNRLwEV?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/niklasramo/pen/WNRLwEV">
+  Muuri: drag start delay on touch</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -0,0 +1,116 @@
+# Getting Started
+
+## 1. Get Muuri
+
+Install via [npm](https://www.npmjs.com/package/muuri):
+
+```bash
+npm install muuri
+```
+
+Or download:
+
+- [muuri.js](https://cdn.jsdelivr.net/npm/[email protected]/dist/muuri.js) - for development (not minified, with comments).
+- [muuri.min.js](https://cdn.jsdelivr.net/npm/[email protected]/dist/muuri.min.js) - for production (minified, no comments).
+
+Or link directly:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/muuri.min.js"></script>
+```
+
+## 2. Get Web Animations Polyfill (if needed)
+
+Muuri uses [Web Animations](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) to handle all the animations by default. If you need to use Muuri on a browser that does not support Web Animations you need to use a [polyfill](https://github.com/web-animations/web-animations-js).
+
+Install via [npm](https://www.npmjs.com/package/web-animations-js):
+
+```bash
+npm install web-animations-js
+```
+
+Or download:
+
+- [web-animations.min.js](https://cdn.jsdelivr.net/npm/[email protected]/web-animations.min.js)
+
+Or link directly:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/web-animations.min.js"></script>
+```
+
+## 3. Add the markup
+
+- Every grid must have a container element (referred as the _grid element_ from now on).
+- Grid items must always consist of at least two elements. The outer element is used for positioning the item and the inner element (first direct child) is used for animating the item's visibility (show/hide methods). You can insert any markup you wish inside the inner item element.
+- Note that the class names in the below example are not required by Muuri at all, they're just there for example's sake.
+
+```html
+<div class="grid">
+  <div class="item">
+    <div class="item-content">
+      <!-- Safe zone, enter your custom markup -->
+      This can be anything.
+      <!-- Safe zone ends -->
+    </div>
+  </div>
+
+  <div class="item">
+    <div class="item-content">
+      <!-- Safe zone, enter your custom markup -->
+      <div class="my-custom-content">
+        Yippee!
+      </div>
+      <!-- Safe zone ends -->
+    </div>
+  </div>
+</div>
+```
+
+## 4. Add the styles
+
+- The grid element must be "positioned" meaning that it's CSS position property must be set to _relative_, _absolute_ or _fixed_. Also note that Muuri automatically resizes the grid element's width/height depending on the area the items cover and the layout algorithm configuration.
+- The item elements must have their CSS position set to _absolute_.
+- The item elements must not have any CSS transitions or animations applied to them, because they might conflict with Muuri's internal animation engine. However, the grid element can have transitions applied to it if you want it to animate when it's size changes after the layout operation.
+- You can control the gaps between the items by giving some margin to the item elements.
+- One last thing. Never ever set `overflow: auto;` or `overflow: scroll;` to the grid element. Muuri's calculation logic does not account for that and you _will_ see some item jumps when dragging starts. Always use a wrapper element for the grid element where you set the `auto`/`scroll` overflow values.
+
+```css
+.grid {
+  position: relative;
+}
+.item {
+  display: block;
+  position: absolute;
+  width: 100px;
+  height: 100px;
+  margin: 5px;
+  z-index: 1;
+  background: #000;
+  color: #fff;
+}
+.item.muuri-item-dragging {
+  z-index: 3;
+}
+.item.muuri-item-releasing {
+  z-index: 2;
+}
+.item.muuri-item-hidden {
+  z-index: 0;
+}
+.item-content {
+  position: relative;
+  width: 100%;
+  height: 100%;
+}
+```
+
+## 5. Fire it up
+
+The bare minimum configuration is demonstrated below. You must always provide the grid element (or a selector so Muuri can fetch the element for you), everything else is optional.
+
+```javascript
+var grid = new Muuri('.grid');
+```
+
+You can view this little tutorial demo [here](https://codepen.io/niklasramo/pen/wpwNjK). After that you might want to check some [other demos](https://codepen.io/collection/AWopag/) as well.