remove pushDefault, complete documentation

Author: lzurbriggen

README.md

@@ -2,4 +2,16 @@
 
 Lightweight and flexible system for modal dialogs, snackbars, toasts, ...
 
-## [Docs](https://jshmrtn.github.io/vue-haystack/)
+[Documentation and Demos](https://jshmrtn.github.io/vue-haystack/)
+
+## Installation
+
+```sh
+npm i vue-haystack
+```
+
+Import the styles (e.g. in your `App.vue`):
+
+```ts
+import "vue-haystack/style.css";
+```

docs/.vuepress/config.ts

@@ -7,33 +7,22 @@ export default defineUserConfig<DefaultThemeOptions>({
   port: 3000,
   lang: "en-US",
   title: "Vue Haystack 🧱",
-  bundler: "@vuepress/vite",
+  bundler: "@vuepress/bundler-vite",
   clientAppEnhanceFiles: [path.resolve(__dirname, "./enhanceAppFile.ts")],
+  plugins: ["@vuepress/plugin-search"],
   themeConfig: {
     repo: "https://github.com/jshmrtn/vue-haystack",
-    navbar: [],
+    navbar: [{ text: "npm", link: "https://npmjs.com/package/vue-haystack" }],
     locales: {
       "/": {
         selectLanguageName: "English",
       },
     },
-    sidebar: [
-      {
-        text: "Home",
-        link: "/README.md",
-      },
-      {
-        text: "Modals",
-        link: "/modal.md",
-      },
-      {
-        text: "Snackbar",
-        link: "/snackbar.md",
-      },
-      {
-        text: "Generic store",
-        link: "/generic.md",
-      },
-    ],
+    displayAllHeaders: true,
+    sidebarDepth: 3,
+    sidebar: ["/setup.md", "/modal.md", "/snackbar.md", "/generic.md"],
+    editLink: false,
+    contributors: false,
+    lastUpdated: false,
   },
 });

docs/README.md

@@ -9,7 +9,7 @@ actions:
   - text: Snackbar
     link: /snackbar
     type: primary
-  - text: Generic store
+  - text: Custom stores
     link: /generic
     type: primary
 features:
@@ -18,14 +18,10 @@ features:
   - title: Flexible
     details: Use your own components and maintain full control over the looks and functionality of your system.
   - title: Extensible
-    details: A generic store allows you to easily implement your own systems
+    details: A custom store allows you to easily implement your own systems
 footer: MIT Licensed | Copyright © 2021-present JOSHMARTIN GmbH
 ---
 
-<div class="alert">
-This is an early version, only the modal system is ready to use and documented
-</div>
-
 ## Installation
 
 ```sh

docs/generic.md

@@ -1,9 +1,190 @@
-# Generic store
+# Custom store
 
-<div class="alert">
-Work in progress
-</div>
+If you want to create your own system with special items or store behavior, you can write your own store. The generic store does the heavy lifting for you.
 
-If you have specific use cases, e.g. want to implement a `Toast` system or something similar, the generic store will take this much easier.
+All the built-in systems use the generic store, take a look [at the source](https://github.com/jshmrtn/vue-haystack/tree/master/src/modal) as well.
 
-The modal system uses the generic store, take a look [at the source](https://github.com/jshmrtn/vue-haystack/tree/master/src/modal) if you want to implement your own stores.
+## Creating a Store
+
+To create a store, call `createItemStoreInstance` with two callbacks, the first to set up your item (`createItem`) instances, the second to extend the store as a whole (`extendStore`).
+
+This is a skeleton that should help you get started (`myStore.ts`):
+
+```ts
+import { createItemStoreInstance } from "vue-haystack";
+
+const store = createItemStoreInstance(
+  // `base` contains all the mandatory item properties (id, component, props, listeners, options)
+  (base) => {
+    const options = {
+      // add custom options for your items
+      ...base.options,
+    };
+
+    const item = {
+      ...base,
+      // define custom properties that will be available in your component (return of `useMyItem`)
+      options: options,
+    };
+
+    return {
+      item: {
+        ...base,
+        options: options,
+      },
+      useReturn: {
+        // define custom properties that will be available on the push functions (return of `useMyStore().push()`)
+      },
+      options: item.options,
+    };
+  },
+  (_items) => {
+    // extend the store here to provide custom push functions for example
+    return {};
+  },
+);
+
+export const { useStore: useMyStore, useItem: useMyItem, provideItem: provideMyItem, store: myStore } = store;
+```
+
+## Components
+
+A system usually relies on two components, a `Container` and a `Provider`.
+
+### Container component
+
+The container will be responsible for displaying all your items (e.g. `Modal`, `Toast`, ...) on the screen. This is where you define where to show them, how many at the same time, in what order and define animations. A minimal container may look like this:
+
+```vue
+<template>
+  <div>
+    <MyProvider v-for="item in items" :key="item.id" :item="item">
+      </div>
+        <component
+          :is="item.component"
+          :key="item.id"
+          v-bind="item.props"
+          v-on="item.listeners"
+        />
+    </MyProvider>
+  </div>
+</template>
+
+<script lang="ts">
+import { computed, defineComponent } from "vue";
+import MyProvider from "./MyProvider.vue";
+import { useMyStore } from "./myStore";
+
+export default defineComponent({
+  name: "MyContainer",
+  components: { MyProvider },
+  setup: () => {
+    const myStore = useMyStore();
+
+    const items = computed(() => {
+      return myStore.items.value;
+    });
+
+    return { items };
+  },
+});
+</script>
+```
+
+### Provider component
+
+As you can see, `MyContainer` relies on the `MyProvider` component. The only responsibility of the `Provider` is to provide an item instance to your custom item components. The implementation is very simple and should not look much different than this:
+
+```vue
+<template>
+  <div>
+    <slot :item="item" />
+  </div>
+</template>
+
+<script lang="ts">
+import { defineComponent, PropType } from "vue";
+import { provideMyItem, useMyItem } from "./myStore";
+
+export default defineComponent({
+  name: "MyProvider",
+  components: {},
+  props: {
+    item: {
+      type: Object as PropType<ReturnType<typeof useMyItem>>,
+      required: true,
+    },
+  },
+  setup: (props) => {
+    provideMyItem(props.item);
+    return {};
+  },
+});
+</script>
+```
+
+### Item components
+
+These are the components you can push into your store and display in your container, so can take basically any shape. You can access the item instance using your `useMyItem()` function:
+
+```vue
+<template>
+  <div>MyItem: {{ foo }}</div>
+</template>
+
+<script lang="ts">
+import { defineComponent } from "vue";
+import { useMyItem } from "./myStore";
+
+export default defineComponent({
+  name: "MyExampleItem",
+  components: {},
+  props: {
+    foo: {
+      type: String,
+      required: true,
+    },
+  },
+  setup: () => {
+    const myItem = useMyItem();
+
+    return {};
+  },
+});
+</script>
+```
+
+## Using your custom store
+
+As with the built-in stores, use your container component in a template, for example your `App.vue`:
+
+```ts
+import { MyContainer } from "./MyContainer.vue";
+```
+
+```vue
+<template>
+  <div>
+    <router-view />
+    <MyContainer />
+  </div>
+</template>
+```
+
+Then wherever you want to instantiate your items:
+
+```ts
+import { useMyStore } from "./myStore";
+import MyExampleItem from "./MyExampleItem.vue";
+
+useMyStore().push(
+  MyExampleItem /* item component */,
+  { foo: "propValue" /* props */ },
+  {
+    /* listeners */
+  },
+  {
+    /* options */
+  },
+);
+```

docs/setup.md

@@ -0,0 +1,15 @@
+# Setup
+
+Install vue-haystack using `npm`, `yarn` or `pnPm`:
+
+```sh
+npm i vue-haystack
+```
+
+Import the styles (e.g. in your `App.vue`):
+
+```ts
+import "vue-haystack/style.css";
+```
+
+Now you can use one of the prebuilt systems ([modal](./modal.md), [snackbar](./modal.md)) or create your own ([custom store](./generic.md)).