docs(guide): add guide to the docs

nickmessing · nickmessing · commit 3244f04e42ec · 2024-06-24T17:28:48.000+03:00
diff --git a/packages/examples/todolist-ts/.eslintrc.cjs b/packages/examples/todolist-ts/.eslintrc.cjs
@@ -5,9 +5,6 @@ module.exports = {
     project: ['./tsconfig.json', './tsconfig.app.json', './tsconfig.node.json'],
     parser: '@typescript-eslint/parser',
   },
-  rules: {
-    'import/no-unresolved': [2, { ignore: ['vue-tinybase/typed'] }],
-  },
   settings: {
     'import/resolver': {
       node: {
diff --git a/packages/examples/todolist-ts/src/components/todos/NewTodoInput.vue b/packages/examples/todolist-ts/src/components/todos/NewTodoInput.vue
@@ -1,8 +1,8 @@
 <script setup lang="ts">
 import { ref } from 'vue'
-import { useStore } from 'vue-tinybase'
+import { injectStore } from 'vue-tinybase'
 
-const store = useStore()
+const store = injectStore()
 
 const newTodoText = ref('')
 
diff --git a/packages/examples/todolist-ts/src/components/todos/SingleTodo.vue b/packages/examples/todolist-ts/src/components/todos/SingleTodo.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { nextTick, ref } from 'vue'
-import { cellRef, useStore } from 'vue-tinybase'
+import { cellRef, injectStore } from 'vue-tinybase'
 
 const props = defineProps<{
   rowId: string
@@ -26,7 +26,7 @@ function exitEditingMode(save = false) {
   }
 }
 
-const store = useStore()
+const store = injectStore()
 function removeTodo() {
   store.delRow('todos', props.rowId)
 }
diff --git a/packages/examples/todolist-ts/src/components/todos/TodosFooter.vue b/packages/examples/todolist-ts/src/components/todos/TodosFooter.vue
@@ -1,14 +1,14 @@
 <script setup lang="ts">
 import { computed } from 'vue'
 import { RouterLink } from 'vue-router'
-import { useStore, useTable } from 'vue-tinybase'
+import { injectStore, useTable } from 'vue-tinybase'
 
-const { data: table } = useTable('todos')
+const table = useTable('todos')
 const entries = computed(() => Object.entries(table.value))
 const activeEntries = computed(() => entries.value.filter(([_, entry]) => !entry.completed))
 const completedEntries = computed(() => entries.value.filter(([_, entry]) => entry.completed))
 
-const store = useStore()
+const store = injectStore()
 function clearCompleted() {
   for (const entry of completedEntries.value) {
     store.delRow('todos', entry[0])
diff --git a/packages/examples/todolist-ts/src/main.ts b/packages/examples/todolist-ts/src/main.ts
@@ -1,14 +1,18 @@
 import 'todomvc-app-css/index.css'
-import { createApp } from 'vue'
-import { createTinybaseVue } from 'vue-tinybase'
+import { createApp, h } from 'vue'
+import { provideStore } from 'vue-tinybase'
 
 import App from '@/App.vue'
 import { router } from '@/router'
 import { store } from '@/store'
 
-const app = createApp(App)
+const app = createApp({
+  setup() {
+    provideStore(store)
+  },
+  render: () => h(App),
+})
 
 app.use(router)
-app.use(createTinybaseVue(store))
 
 app.mount('#app')
diff --git a/packages/examples/todolist-ts/src/store.ts b/packages/examples/todolist-ts/src/store.ts
@@ -13,14 +13,14 @@ export const store = createStore()
     val2: { type: 'number', default: 0 },
     val3: { type: 'boolean', default: false },
   })
-export const store2 = createStore().setValuesSchema({
-  val10: { type: 'string' },
-})
 
 const persister = createLocalPersister(store, 'todos')
 
-await persister.startAutoLoad()
-await persister.startAutoSave()
+// eslint-disable-next-line unicorn/prefer-top-level-await
+void (async () => {
+  await persister.startAutoLoad()
+  await persister.startAutoSave()
+})()
 
 export type Store = typeof store
 
diff --git a/packages/examples/todolist-ts/src/views/filtered/ActiveTodos.vue b/packages/examples/todolist-ts/src/views/filtered/ActiveTodos.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { computed } from 'vue'
-import { useTable } from 'vue-tinybase/typed'
+import { useTable } from 'vue-tinybase'
 
 import TodosList from '@/components/todos/TodosList.vue'
 
diff --git a/packages/examples/todolist-ts/src/views/filtered/AllTodos.vue b/packages/examples/todolist-ts/src/views/filtered/AllTodos.vue
@@ -1,13 +1,13 @@
 <script setup lang="ts">
 import { computed } from 'vue'
-import { useStore, useTable } from 'vue-tinybase'
+import { injectStore, useTable } from 'vue-tinybase'
 
 import TodosList from '@/components/todos/TodosList.vue'
 
-const { data: table } = useTable('todos')
+const table = useTable('todos')
 const rowIds = computed(() => Object.keys(table.value))
 
-const store = useStore()
+const store = injectStore()
 const allCompleted = computed({
   get: () => rowIds.value.length > 0 && rowIds.value.every(rowId => table.value[rowId].completed),
   set: (value: boolean) => {
diff --git a/packages/examples/todolist-ts/src/views/filtered/CompletedTodos.vue b/packages/examples/todolist-ts/src/views/filtered/CompletedTodos.vue
@@ -4,7 +4,7 @@ import { useTable } from 'vue-tinybase'
 
 import TodosList from '@/components/todos/TodosList.vue'
 
-const { data: table } = useTable('todos')
+const table = useTable('todos')
 const entries = computed(() => Object.entries(table.value))
 const completedEntries = computed(() => entries.value.filter(([_, entry]) => entry.completed))
 const rowIds = computed(() => completedEntries.value.map(([rowId, _]) => rowId))
diff --git a/packages/examples/todolist-ts/vite.config.ts b/packages/examples/todolist-ts/vite.config.ts
@@ -10,7 +10,6 @@ export default defineConfig({
   resolve: {
     alias: {
       '@': fileURLToPath(new URL('src', import.meta.url)),
-      'vue-tinybase/typed': 'vue-tinybase',
       'tinybase/with-schemas/persisters/persister-browser': 'tinybase/persisters/persister-browser',
     },
   },
diff --git a/packages/private/docs/.vitepress/config.mts b/packages/private/docs/.vitepress/config.mts
@@ -1,6 +1,5 @@
 import { defineConfig } from 'vitepress'
 
-// https://vitepress.dev/reference/site-config
 export default defineConfig({
   title: 'Vue TinyBase',
   description: 'Vue + TinyBase Documentation',
@@ -10,11 +9,24 @@ export default defineConfig({
 
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'Guide', link: '/guide' },
-      { text: 'API', link: '/api' },
+      { text: 'Guide', link: '/guide/getting-started', activeMatch: `^/guide/` },
+      { text: 'API', link: '/api', activeMatch: `^/api/` },
     ],
 
     sidebar: {
+      '/guide': [
+        {
+          text: 'Getting Started',
+          items: [
+            { text: '1. Create a store', link: '/guide/getting-started/create-a-store' },
+            { text: '2. Connect to Vue.js app', link: '/guide/getting-started/connect-to-vuejs-app' },
+          ],
+        },
+        {
+          text: 'Usage with TypeScript',
+          link: '/guide/usage-with-typescript',
+        },
+      ],
       '/api': [
         {
           text: 'Store',
diff --git a/packages/private/docs/.vitepress/theme/components/MyLayout.vue b/packages/private/docs/.vitepress/theme/components/MyLayout.vue
@@ -1,14 +1,20 @@
-<script setup>
+<script setup lang="ts">
+import { useRoute } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
 import VPSwitchStoreStyle from './VPSwitchStoreStyle.vue'
+import { computed } from 'vue'
 
 const { Layout } = DefaultTheme
+
+const route = useRoute()
+
+const isApiPage = computed(() => route.path.startsWith('/api'))
 </script>
 
 <template>
   <Layout>
     <template #sidebar-nav-before>
-      <ClientOnly>
+      <ClientOnly v-if="isApiPage">
         <VPSwitchStoreStyle />
       </ClientOnly>
     </template>
diff --git a/packages/private/docs/api/index.md b/packages/private/docs/api/index.md
@@ -1,6 +1 @@
----
-title: API Reference
-sidebar: false
-page: true
-footer: false
----
+# API
diff --git a/packages/private/docs/guide/getting-started/connect-to-vuejs-app.md b/packages/private/docs/guide/getting-started/connect-to-vuejs-app.md
@@ -0,0 +1,32 @@
+# Connect the Store to Your Vue.js App
+
+With your TinyBase store set up, the next step is to connect it to your Vue.js application. This integration allows you to leverage TinyBase’s state management capabilities within your Vue components.
+
+For more details on context, you can refer to the [context](/api/store/context) section of the API.
+
+## Provide the Store to Your Vue App
+
+To provide the TinyBase store to your Vue.js app, you need to use the `provideStore` function from `vue-tinybase`. This will make the store available throughout your Vue component tree.
+
+Here's the simplest example to get you started:
+
+```js
+import { createApp, h } from 'vue'
+import { provideStore } from 'vue-tinybase'
+
+import { store } from './tinybase'
+import App from './App.vue'
+
+const app = createApp({
+  setup() {
+    provideStore(store)
+  },
+  render: () => h(App),
+})
+
+app.mount('#app')
+```
+
+In this example, we create a Vue app and use the provideStore function in the setup function to provide the TinyBase store. The render function is used to render the main App component.
+
+After providing the store, you can use `vue-tinybase` [event hooks](/api/store/events), [composables](/api/store/composables), and [writable references](/api/store/references) inside all components of your app. This integration enables you to interact with the store’s state and respond to changes efficiently.
diff --git a/packages/private/docs/guide/getting-started/create-a-store.md b/packages/private/docs/guide/getting-started/create-a-store.md
@@ -0,0 +1,32 @@
+# Create a store
+
+TinyBase is a powerful and flexible state management library that provides a robust solution for managing your application's data. To get started with TinyBase, you'll need to create a store, which is where all your data will reside.
+
+Feel free to check [the official TinyBase documentation](https://tinybase.org/guides/the-basics/creating-a-store/) for more detailed information and examples.
+
+## Add `tinybase` package to your project
+
+First, you need to install the `tinybase` package. You can do this using npm with the following command:
+
+```bash
+npm install --save tinybase
+```
+
+This will add TinyBase to your project’s dependencies, allowing you to import and use it in your code.
+
+## Create a store
+
+Once you have installed the TinyBase package, you can create a store. The store is a central place where you can keep and manage your application’s state.
+
+Create a new JavaScript file, for example `tinybase.js`, and add the following code:
+
+```javascript
+import { createStore } from 'tinybase'
+
+// Create a new store instance
+export const store = createStore()
+```
+
+This code imports the createStore function from TinyBase and uses it to create a new store instance. The store is then exported so that it can be imported and used in other parts of your application.
+
+With your store set up, the next step is to [connect it to your Vue.js application](/guide/getting-started/connect-to-vuejs-app). This allows you to use TinyBase’s state management features within your Vue components.
diff --git a/packages/private/docs/guide/getting-started/index.md b/packages/private/docs/guide/getting-started/index.md
@@ -0,0 +1,3 @@
+# Getting started
+
+This guide will help you get started with your new project.
diff --git a/packages/private/docs/guide/usage-with-typescript.md b/packages/private/docs/guide/usage-with-typescript.md
@@ -0,0 +1,39 @@
+# Usage with TypeScript
+
+TinyBase provides excellent support for TypeScript, allowing you to define and enforce types for your data. We highly recommend using "Schema-based" typing because it is best supported and provides a robust way to manage your application's state.
+
+For more information on Schema-based typing, please refer to the [official TinyBase documentation](https://tinybase.org/guides/the-basics/tinybase-and-typescript/#2-schema-based-typing).
+
+## Connecting Defined Schema to Vue-TinyBase Composables
+
+The following code snippet demonstrates how to define a schema for your store and connect it to all composables imported from `vue-tinybase`:
+
+```typescript
+import { createStore } from 'tinybase/with-schemas'
+
+// Create a store with schema-based typing
+export const store = createStore()
+  .setTablesSchema({
+    // Define the schema for the 'todos' table
+    todos: {
+      text: { type: 'string' },
+      completed: { type: 'boolean', default: false },
+    },
+  })
+  .setValuesSchema({
+    // Define the schema for the store's values
+    val1: { type: 'string' },
+    val2: { type: 'number', default: 0 },
+    val3: { type: 'boolean', default: false },
+  })
+
+// Export the store type
+export type Store = typeof store
+
+// Extend the Vue-Tinybase context with the store type
+declare module 'vue-tinybase' {
+  export interface VueTinybaseContext {
+    store: Store
+  }
+}
+```
diff --git a/packages/public/vue-tinybase/src/context/index.ts b/packages/public/vue-tinybase/src/context/index.ts
@@ -1 +1,2 @@
+export { injectStore } from './injectStore.js'
 export { provideStore } from './provideStore.js'
diff --git a/packages/public/vue-tinybase/src/custom-store/context/index.ts b/packages/public/vue-tinybase/src/custom-store/context/index.ts
@@ -1 +1,2 @@
+export { injectStore } from './injectStore.js'
 export { provideStore } from './provideStore.js'

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`<script setup lang="ts">`
`2`	`2`	`import { nextTick, ref } from 'vue'`
`3`		`-import { cellRef, useStore } from 'vue-tinybase'`
	`3`	`+import { cellRef, injectStore } from 'vue-tinybase'`
`4`	`4`
`5`	`5`	`const props = defineProps<{`
`6`	`6`	`rowId: string`
`@@ -26,7 +26,7 @@ function exitEditingMode(save = false) {`
`26`	`26`	`}`
`27`	`27`	`}`
`28`	`28`
`29`		`-const store = useStore()`
	`29`	`+const store = injectStore()`
`30`	`30`	`function removeTodo() {`
`31`	`31`	`store.delRow('todos', props.rowId)`
`32`	`32`	`}`