@korajs/vue 0.5.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +84 -10
  2. package/dist/index.cjs +419 -8
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +158 -20
  5. package/dist/index.d.ts +158 -20
  6. package/dist/index.js +415 -7
  7. package/dist/index.js.map +1 -1
  8. package/package.json +12 -5
package/dist/index.d.cts CHANGED
@@ -1,31 +1,169 @@
1
- import { App, InjectionKey } from 'vue';
2
- import { KoraEventEmitter } from '@korajs/core';
3
- import { Store } from '@korajs/store';
1
+ import * as vue from 'vue';
2
+ import { VNode, InjectionKey, ShallowRef, PropType, DeepReadonly, shallowRef, App } from 'vue';
3
+ import { KoraAppLike as KoraAppLike$1, KoraContextValue as KoraContextValue$1, UseMutationOptions as UseMutationOptions$1, UseMutationResultBase, UseQueryOptions as UseQueryOptions$1 } from '@korajs/core/bindings';
4
+ import { Store, QueryStoreCache, CollectionRecord, QueryBuilder, CollectionAccessor } from '@korajs/store';
5
+ import * as _korajs_sync from '@korajs/sync';
6
+ import { SyncEngine, CursorInfo, AwarenessUser, AwarenessState } from '@korajs/sync';
7
+ import * as Y from 'yjs';
8
+
9
+ type KoraAppLike = KoraAppLike$1<Store, SyncEngine, QueryStoreCache>;
10
+ type KoraContextValue = KoraContextValue$1<Store, SyncEngine, QueryStoreCache>;
11
+ type UseQueryOptions = UseQueryOptions$1;
12
+ type UseMutationOptions<TData, TArgs extends unknown[], TContext = void> = UseMutationOptions$1<TData, TArgs, TContext>;
13
+ interface KoraProviderProps {
14
+ app?: KoraAppLike;
15
+ store?: Store;
16
+ syncEngine?: SyncEngine | null;
17
+ fallback?: VNode | string | null;
18
+ }
19
+ interface UseMutationResult<TData, TArgs extends unknown[]> extends UseMutationResultBase<TData, TArgs> {
20
+ isLoading: Readonly<{
21
+ value: boolean;
22
+ }>;
23
+ error: Readonly<{
24
+ value: Error | null;
25
+ }>;
26
+ }
27
+ /** @deprecated Use {@link KoraAppLike} via {@link useApp}. */
28
+ type KoraAppHandle = KoraAppLike;
29
+ interface UseRichTextResult {
30
+ doc: Y.Doc;
31
+ text: Y.Text;
32
+ undo: () => void;
33
+ redo: () => void;
34
+ canUndo: boolean;
35
+ canRedo: boolean;
36
+ ready: boolean;
37
+ error: Error | null;
38
+ cursors: CursorInfo[];
39
+ setCursor: (anchor: number, head: number) => void;
40
+ clearCursor: () => void;
41
+ }
42
+
43
+ declare const koraContextKey: InjectionKey<ShallowRef<KoraContextValue | null>>;
44
+ /** @deprecated Use {@link koraContextKey} with {@link KoraProvider}. */
45
+ declare const koraAppInjectionKey: InjectionKey<KoraAppLike>;
46
+ declare function useKoraContext(): KoraContextValue;
47
+
48
+ declare const KoraProvider: vue.DefineComponent<vue.ExtractPropTypes<{
49
+ app: {
50
+ type: PropType<KoraAppLike>;
51
+ default: undefined;
52
+ };
53
+ store: {
54
+ type: PropType<Store>;
55
+ default: undefined;
56
+ };
57
+ syncEngine: {
58
+ type: PropType<SyncEngine | null>;
59
+ default: undefined;
60
+ };
61
+ fallback: {
62
+ type: PropType<VNode | string | null>;
63
+ default: null;
64
+ };
65
+ }>, () => string | VNode<vue.RendererNode, vue.RendererElement, {
66
+ [key: string]: any;
67
+ }> | VNode<vue.RendererNode, vue.RendererElement, {
68
+ [key: string]: any;
69
+ }>[] | null | undefined, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
70
+ app: {
71
+ type: PropType<KoraAppLike>;
72
+ default: undefined;
73
+ };
74
+ store: {
75
+ type: PropType<Store>;
76
+ default: undefined;
77
+ };
78
+ syncEngine: {
79
+ type: PropType<SyncEngine | null>;
80
+ default: undefined;
81
+ };
82
+ fallback: {
83
+ type: PropType<VNode | string | null>;
84
+ default: null;
85
+ };
86
+ }>> & Readonly<{}>, {
87
+ app: KoraAppLike;
88
+ store: Store;
89
+ syncEngine: SyncEngine | null;
90
+ fallback: string | VNode<vue.RendererNode, vue.RendererElement, {
91
+ [key: string]: any;
92
+ }> | null;
93
+ }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
94
+
95
+ /**
96
+ * Reactive query composable backed by the local Kora store.
97
+ */
98
+ declare function useQuery<T = CollectionRecord>(query: QueryBuilder<T>, options?: UseQueryOptions): DeepReadonly<ReturnType<typeof shallowRef<readonly T[]>>>;
99
+
100
+ /**
101
+ * Mutation composable with optional optimistic update and rollback hooks.
102
+ */
103
+ declare function useMutation<TData, TArgs extends unknown[], TContext = void>(mutationFn: (...args: TArgs) => Promise<TData>, options?: UseMutationOptions<TData, TArgs, TContext>): UseMutationResult<TData, TArgs>;
104
+
105
+ /**
106
+ * Reactive sync engine status. Updates only when status payload changes.
107
+ */
108
+ declare function useSyncStatus(): Readonly<vue.Ref<{
109
+ readonly status: _korajs_sync.SyncStatus;
110
+ readonly pendingOperations: number;
111
+ readonly lastSyncedAt: number | null;
112
+ readonly lastSuccessfulPush: number | null;
113
+ readonly lastSuccessfulPull: number | null;
114
+ readonly conflicts: number;
115
+ }, {
116
+ readonly status: _korajs_sync.SyncStatus;
117
+ readonly pendingOperations: number;
118
+ readonly lastSyncedAt: number | null;
119
+ readonly lastSuccessfulPush: number | null;
120
+ readonly lastSuccessfulPull: number | null;
121
+ readonly conflicts: number;
122
+ }>>;
4
123
 
5
124
  /**
6
- * Minimal app handle type for Vue provide/inject (matches `createApp()` from korajs).
7
- * Use the full `KoraApp` / `TypedKoraApp` types from korajs in application code when available.
125
+ * Returns the typed Kora app from {@link KoraProvider}'s `app` prop.
8
126
  */
9
- interface KoraAppHandle {
10
- readonly ready: Promise<void>;
11
- readonly events: KoraEventEmitter;
12
- readonly sync: unknown;
13
- close(): Promise<void>;
14
- getStore(): Store;
15
- [collection: string]: unknown;
127
+ declare function useApp<T extends KoraAppLike = KoraAppLike>(): T;
128
+
129
+ /**
130
+ * Returns a collection accessor for the given schema collection name.
131
+ */
132
+ declare function useCollection(name: string): CollectionAccessor;
133
+
134
+ interface UseRichTextOptions {
135
+ user?: AwarenessUser;
136
+ useDocChannel?: boolean;
16
137
  }
138
+ /**
139
+ * Binds a richtext field to a shared Yjs document for editor integration.
140
+ */
141
+ declare function useRichText(collectionName: string, recordId: string, fieldName: string, options?: UseRichTextOptions): UseRichTextResult;
142
+
143
+ /**
144
+ * Sets the local user's collaborative presence state.
145
+ */
146
+ declare function usePresence(user: {
147
+ name: string;
148
+ color: string;
149
+ avatar?: string;
150
+ } | null): void;
151
+ /**
152
+ * Reactive list of remote collaborators' awareness states.
153
+ */
154
+ declare function useCollaborators(): ShallowRef<AwarenessState[]>;
17
155
 
18
- /** Vue injection key for the root Kora app instance. */
19
- declare const koraAppInjectionKey: InjectionKey<KoraAppHandle>;
20
156
  /**
21
157
  * Register a Kora app on a Vue application instance.
22
- * Call once after `createApp()` from korajs, typically in `main.ts`.
158
+ *
159
+ * @deprecated Prefer {@link KoraProvider} — `installKora` does not provide reactive
160
+ * hook context (`useQuery`, `useSyncStatus`, etc.) until you migrate to `KoraProvider`.
23
161
  */
24
- declare function installKora(vueApp: App, koraApp: KoraAppHandle): void;
162
+ declare function installKora(vueApp: App, koraApp: KoraAppLike): void;
25
163
  /**
26
- * Access the Kora app from a component setup function.
27
- * Pair with {@link installKora} and `app.ready` before running queries.
164
+ * Access the Kora app from a component when using {@link installKora} only.
165
+ * For reactive hooks, use {@link useApp} inside {@link KoraProvider}.
28
166
  */
29
- declare function useKoraApp(): KoraAppHandle;
167
+ declare function useKoraApp(): KoraAppLike;
30
168
 
31
- export { type KoraAppHandle, installKora, koraAppInjectionKey, useKoraApp };
169
+ export { type KoraAppHandle, type KoraAppLike, type KoraContextValue, KoraProvider, type KoraProviderProps, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseRichTextOptions, type UseRichTextResult, installKora, koraAppInjectionKey, koraContextKey, useApp, useCollaborators, useCollection, useKoraApp, useKoraContext, useMutation, usePresence, useQuery, useRichText, useSyncStatus };
package/dist/index.d.ts CHANGED
@@ -1,31 +1,169 @@
1
- import { App, InjectionKey } from 'vue';
2
- import { KoraEventEmitter } from '@korajs/core';
3
- import { Store } from '@korajs/store';
1
+ import * as vue from 'vue';
2
+ import { VNode, InjectionKey, ShallowRef, PropType, DeepReadonly, shallowRef, App } from 'vue';
3
+ import { KoraAppLike as KoraAppLike$1, KoraContextValue as KoraContextValue$1, UseMutationOptions as UseMutationOptions$1, UseMutationResultBase, UseQueryOptions as UseQueryOptions$1 } from '@korajs/core/bindings';
4
+ import { Store, QueryStoreCache, CollectionRecord, QueryBuilder, CollectionAccessor } from '@korajs/store';
5
+ import * as _korajs_sync from '@korajs/sync';
6
+ import { SyncEngine, CursorInfo, AwarenessUser, AwarenessState } from '@korajs/sync';
7
+ import * as Y from 'yjs';
8
+
9
+ type KoraAppLike = KoraAppLike$1<Store, SyncEngine, QueryStoreCache>;
10
+ type KoraContextValue = KoraContextValue$1<Store, SyncEngine, QueryStoreCache>;
11
+ type UseQueryOptions = UseQueryOptions$1;
12
+ type UseMutationOptions<TData, TArgs extends unknown[], TContext = void> = UseMutationOptions$1<TData, TArgs, TContext>;
13
+ interface KoraProviderProps {
14
+ app?: KoraAppLike;
15
+ store?: Store;
16
+ syncEngine?: SyncEngine | null;
17
+ fallback?: VNode | string | null;
18
+ }
19
+ interface UseMutationResult<TData, TArgs extends unknown[]> extends UseMutationResultBase<TData, TArgs> {
20
+ isLoading: Readonly<{
21
+ value: boolean;
22
+ }>;
23
+ error: Readonly<{
24
+ value: Error | null;
25
+ }>;
26
+ }
27
+ /** @deprecated Use {@link KoraAppLike} via {@link useApp}. */
28
+ type KoraAppHandle = KoraAppLike;
29
+ interface UseRichTextResult {
30
+ doc: Y.Doc;
31
+ text: Y.Text;
32
+ undo: () => void;
33
+ redo: () => void;
34
+ canUndo: boolean;
35
+ canRedo: boolean;
36
+ ready: boolean;
37
+ error: Error | null;
38
+ cursors: CursorInfo[];
39
+ setCursor: (anchor: number, head: number) => void;
40
+ clearCursor: () => void;
41
+ }
42
+
43
+ declare const koraContextKey: InjectionKey<ShallowRef<KoraContextValue | null>>;
44
+ /** @deprecated Use {@link koraContextKey} with {@link KoraProvider}. */
45
+ declare const koraAppInjectionKey: InjectionKey<KoraAppLike>;
46
+ declare function useKoraContext(): KoraContextValue;
47
+
48
+ declare const KoraProvider: vue.DefineComponent<vue.ExtractPropTypes<{
49
+ app: {
50
+ type: PropType<KoraAppLike>;
51
+ default: undefined;
52
+ };
53
+ store: {
54
+ type: PropType<Store>;
55
+ default: undefined;
56
+ };
57
+ syncEngine: {
58
+ type: PropType<SyncEngine | null>;
59
+ default: undefined;
60
+ };
61
+ fallback: {
62
+ type: PropType<VNode | string | null>;
63
+ default: null;
64
+ };
65
+ }>, () => string | VNode<vue.RendererNode, vue.RendererElement, {
66
+ [key: string]: any;
67
+ }> | VNode<vue.RendererNode, vue.RendererElement, {
68
+ [key: string]: any;
69
+ }>[] | null | undefined, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
70
+ app: {
71
+ type: PropType<KoraAppLike>;
72
+ default: undefined;
73
+ };
74
+ store: {
75
+ type: PropType<Store>;
76
+ default: undefined;
77
+ };
78
+ syncEngine: {
79
+ type: PropType<SyncEngine | null>;
80
+ default: undefined;
81
+ };
82
+ fallback: {
83
+ type: PropType<VNode | string | null>;
84
+ default: null;
85
+ };
86
+ }>> & Readonly<{}>, {
87
+ app: KoraAppLike;
88
+ store: Store;
89
+ syncEngine: SyncEngine | null;
90
+ fallback: string | VNode<vue.RendererNode, vue.RendererElement, {
91
+ [key: string]: any;
92
+ }> | null;
93
+ }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
94
+
95
+ /**
96
+ * Reactive query composable backed by the local Kora store.
97
+ */
98
+ declare function useQuery<T = CollectionRecord>(query: QueryBuilder<T>, options?: UseQueryOptions): DeepReadonly<ReturnType<typeof shallowRef<readonly T[]>>>;
99
+
100
+ /**
101
+ * Mutation composable with optional optimistic update and rollback hooks.
102
+ */
103
+ declare function useMutation<TData, TArgs extends unknown[], TContext = void>(mutationFn: (...args: TArgs) => Promise<TData>, options?: UseMutationOptions<TData, TArgs, TContext>): UseMutationResult<TData, TArgs>;
104
+
105
+ /**
106
+ * Reactive sync engine status. Updates only when status payload changes.
107
+ */
108
+ declare function useSyncStatus(): Readonly<vue.Ref<{
109
+ readonly status: _korajs_sync.SyncStatus;
110
+ readonly pendingOperations: number;
111
+ readonly lastSyncedAt: number | null;
112
+ readonly lastSuccessfulPush: number | null;
113
+ readonly lastSuccessfulPull: number | null;
114
+ readonly conflicts: number;
115
+ }, {
116
+ readonly status: _korajs_sync.SyncStatus;
117
+ readonly pendingOperations: number;
118
+ readonly lastSyncedAt: number | null;
119
+ readonly lastSuccessfulPush: number | null;
120
+ readonly lastSuccessfulPull: number | null;
121
+ readonly conflicts: number;
122
+ }>>;
4
123
 
5
124
  /**
6
- * Minimal app handle type for Vue provide/inject (matches `createApp()` from korajs).
7
- * Use the full `KoraApp` / `TypedKoraApp` types from korajs in application code when available.
125
+ * Returns the typed Kora app from {@link KoraProvider}'s `app` prop.
8
126
  */
9
- interface KoraAppHandle {
10
- readonly ready: Promise<void>;
11
- readonly events: KoraEventEmitter;
12
- readonly sync: unknown;
13
- close(): Promise<void>;
14
- getStore(): Store;
15
- [collection: string]: unknown;
127
+ declare function useApp<T extends KoraAppLike = KoraAppLike>(): T;
128
+
129
+ /**
130
+ * Returns a collection accessor for the given schema collection name.
131
+ */
132
+ declare function useCollection(name: string): CollectionAccessor;
133
+
134
+ interface UseRichTextOptions {
135
+ user?: AwarenessUser;
136
+ useDocChannel?: boolean;
16
137
  }
138
+ /**
139
+ * Binds a richtext field to a shared Yjs document for editor integration.
140
+ */
141
+ declare function useRichText(collectionName: string, recordId: string, fieldName: string, options?: UseRichTextOptions): UseRichTextResult;
142
+
143
+ /**
144
+ * Sets the local user's collaborative presence state.
145
+ */
146
+ declare function usePresence(user: {
147
+ name: string;
148
+ color: string;
149
+ avatar?: string;
150
+ } | null): void;
151
+ /**
152
+ * Reactive list of remote collaborators' awareness states.
153
+ */
154
+ declare function useCollaborators(): ShallowRef<AwarenessState[]>;
17
155
 
18
- /** Vue injection key for the root Kora app instance. */
19
- declare const koraAppInjectionKey: InjectionKey<KoraAppHandle>;
20
156
  /**
21
157
  * Register a Kora app on a Vue application instance.
22
- * Call once after `createApp()` from korajs, typically in `main.ts`.
158
+ *
159
+ * @deprecated Prefer {@link KoraProvider} — `installKora` does not provide reactive
160
+ * hook context (`useQuery`, `useSyncStatus`, etc.) until you migrate to `KoraProvider`.
23
161
  */
24
- declare function installKora(vueApp: App, koraApp: KoraAppHandle): void;
162
+ declare function installKora(vueApp: App, koraApp: KoraAppLike): void;
25
163
  /**
26
- * Access the Kora app from a component setup function.
27
- * Pair with {@link installKora} and `app.ready` before running queries.
164
+ * Access the Kora app from a component when using {@link installKora} only.
165
+ * For reactive hooks, use {@link useApp} inside {@link KoraProvider}.
28
166
  */
29
- declare function useKoraApp(): KoraAppHandle;
167
+ declare function useKoraApp(): KoraAppLike;
30
168
 
31
- export { type KoraAppHandle, installKora, koraAppInjectionKey, useKoraApp };
169
+ export { type KoraAppHandle, type KoraAppLike, type KoraContextValue, KoraProvider, type KoraProviderProps, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseRichTextOptions, type UseRichTextResult, installKora, koraAppInjectionKey, koraContextKey, useApp, useCollaborators, useCollection, useKoraApp, useKoraContext, useMutation, usePresence, useQuery, useRichText, useSyncStatus };