@meeovi/directus-client 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,238 @@
+# @meeovi/directus-client
+
+A framework-agnostic, type-safe Directus client with optional bindings for Vue 3, Nuxt 3, and React. Includes schema introspection, auto-form and auto-table generators, validation utilities, and visual-editing / live-preview helpers.
+
+Designed for modular, provider-agnostic platforms like Meeovi, but usable in any Directus-powered project.
+
+## Features
+
+- Framework-agnostic Directus client
+- Vue 3 bindings (`useDirectus`, `DirectusVueProvider`)
+- React bindings (`useDirectus`, `DirectusReactProvider`)
+- Schema introspection
+- Auto-form engine
+- Auto-table engine
+- Validation engine
+- Widget registry
+- Visual editing utilities
+- Live preview utilities
+- Fully typed and tree-shakeable
+
+## Installation
+
+```bash
+npm install @meeovi/directus-client
+# or
+pnpm add @meeovi/directus-client
+```
+
+## Package structure
+
+```
+src/
+  client/
+    createClient.ts
+  vue/
+    DirectusProvider.ts
+    useDirectus.ts
+  react/
+    DirectusProvider.tsx
+    useDirectus.ts
+  schema/
+    types.ts
+    introspect.ts
+  utils/
+    collections.ts
+    fields.ts
+  generators/
+    form-engine.ts
+    table-engine.ts
+    validation-engine.ts
+    widget-registry.ts
+  visual-editing.ts
+  live-preview.ts
+  index.ts
+```
+
+## Usage
+
+### 1) Framework-agnostic
+
+```ts
+import { createMeeoviDirectusClient } from '@meeovi/directus-client';
+
+const directus = createMeeoviDirectusClient('https://your-directus-url.com');
+
+// Example request
+const products = await directus.client.request(directus.readItems('products'));
+```
+
+### 2) Vue 3
+
+Wrap your app:
+
+```ts
+import { DirectusVueProvider, createMeeoviDirectusClient } from '@meeovi/directus-client';
+
+const directus = createMeeoviDirectusClient('https://cms.example.com');
+```
+
+```vue
+<template>
+  <DirectusVueProvider :client="directus">
+    <App />
+  </DirectusVueProvider>
+</template>
+```
+
+Use inside components:
+
+```ts
+import { useDirectus } from '@meeovi/directus-client';
+
+const directus = useDirectus();
+const items = await directus.client.request(directus.readItems('articles'));
+```
+
+### 3) Nuxt 3
+
+Create a plugin:
+
+```ts
+// plugins/directus.client.ts
+import { defineNuxtPlugin, useRuntimeConfig } from '#imports';
+import { createMeeoviDirectusClient, DirectusVueProvider } from '@meeovi/directus-client';
+
+export default defineNuxtPlugin((nuxtApp) => {
+  const config = useRuntimeConfig();
+  const directus = createMeeoviDirectusClient(config.public.directus.url);
+
+  nuxtApp.provide('directus', directus);
+  nuxtApp.vueApp.component('DirectusVueProvider', DirectusVueProvider);
+});
+```
+
+Use it:
+
+```ts
+const { $directus } = useNuxtApp();
+const posts = await $directus.client.request($directus.readItems('posts'));
+```
+
+### 4) React
+
+Wrap your app:
+
+```tsx
+import { DirectusReactProvider, createMeeoviDirectusClient } from '@meeovi/directus-client';
+
+const directus = createMeeoviDirectusClient('https://cms.example.com');
+
+export function App() {
+  return (
+    <DirectusReactProvider client={directus}>
+      <YourRoutes />
+    </DirectusReactProvider>
+  );
+}
+```
+
+Use inside components:
+
+```tsx
+import { useDirectus } from '@meeovi/directus-client';
+const directus = useDirectus();
+const items = await directus.client.request(directus.readItems('products'));
+```
+
+## Schema introspection
+
+```ts
+import { introspectSchema } from '@meeovi/directus-client';
+
+const schema = await introspectSchema(directus.client);
+console.log(schema.directus_fields);
+```
+
+## Auto-Form Engine
+
+```ts
+import { createFormEngine } from '@meeovi/directus-client';
+
+const engine = createFormEngine('products', fields, directus);
+engine.form.title = 'New Product';
+const result = await engine.submit();
+```
+
+## Auto-Table Engine
+
+```ts
+import { generateTableSchema } from '@meeovi/directus-client';
+const table = generateTableSchema(fields);
+console.log(table);
+```
+
+## Validation Engine
+
+```ts
+import { validateField } from '@meeovi/directus-client';
+const error = validateField(field, value);
+if (error) console.error(error);
+```
+
+## Widget Registry
+
+```ts
+import { widgetRegistry } from '@meeovi/directus-client';
+console.log(widgetRegistry.text.component);
+```
+
+## Visual Editing (framework-agnostic)
+
+```ts
+import { createVisualEditing } from '@meeovi/directus-client';
+
+const visual = createVisualEditing({
+  enableVisualEditing: true,
+  directusUrl: 'https://cms.example.com',
+  query: { 'visual-editing': 'true' },
+});
+
+visual.apply({ elements: document.querySelectorAll('[data-editable]') });
+```
+
+## Live Preview (framework-agnostic)
+
+```ts
+import { createLivePreview } from '@meeovi/directus-client';
+
+const preview = createLivePreview({
+  query: Object.fromEntries(new URLSearchParams(location.search)),
+});
+
+if (preview.enabled) {
+  console.log('Preview token:', preview.state.token);
+}
+```
+
+## TypeScript support
+
+Everything is fully typed: Directus schema, client methods, form/table generators, visual editing, live preview, and framework bindings.
+
+## Build
+
+If you’re working inside a monorepo:
+
+```bash
+npm --workspace @meeovi/directus-client run build
+# or
+pnpm --filter @meeovi/directus-client build
+```
+
+## Contributing
+
+PRs are welcome. This package is designed to be modular, extensible, and framework-agnostic — contributions that improve developer experience or expand framework bindings are encouraged.
+
+## License
+
+MIT © Meeovi

package/dist/client/createClient.d.ts

@@ -0,0 +1,14 @@
+import { readItem, readItems, createItem, updateItem, deleteItem, uploadFiles, readSingleton, readFieldsByCollection, type DirectusClient } from '@directus/sdk';
+export interface MeeoviDirectusClient<Schema> {
+    client: DirectusClient<Schema>;
+    request: any;
+    readItem: typeof readItem;
+    readItems: typeof readItems;
+    createItem: typeof createItem;
+    updateItem: typeof updateItem;
+    deleteItem: typeof deleteItem;
+    uploadFiles: typeof uploadFiles;
+    readSingleton: typeof readSingleton;
+    readFieldsByCollection: typeof readFieldsByCollection;
+}
+export declare function createMeeoviDirectusClient<Schema>(url: string): MeeoviDirectusClient<Schema>;

package/dist/client/createClient.js

@@ -0,0 +1,18 @@
+import { createDirectus, rest, authentication, readItem, readItems, createItem, updateItem, deleteItem, uploadFiles, readSingleton, readFieldsByCollection } from '@directus/sdk';
+export function createMeeoviDirectusClient(url) {
+    const client = createDirectus(url)
+        .with(rest())
+        .with(authentication());
+    return {
+        client,
+        request: client.request,
+        readItem,
+        readItems,
+        createItem,
+        updateItem,
+        deleteItem,
+        uploadFiles,
+        readSingleton,
+        readFieldsByCollection
+    };
+}

package/dist/generators/form-engine.d.ts

@@ -0,0 +1,13 @@
+import type { DirectusField } from '../schema/types';
+export interface GeneratedFormField {
+    key: string;
+    widget: string;
+    type: string;
+    options?: Record<string, any>;
+    fields?: GeneratedFormField[];
+    isRepeatable?: boolean;
+    isFile?: boolean;
+    isRelational?: boolean;
+}
+export declare function generateFormField(field: DirectusField): GeneratedFormField;
+export declare function generateFormSchema(fields: DirectusField[]): GeneratedFormField[];

package/dist/generators/form-engine.js

@@ -0,0 +1,22 @@
+import { widgetRegistry } from './widget-registry';
+export function generateFormField(field) {
+    const widget = widgetRegistry[field.interface || 'input'];
+    const base = {
+        key: field.field,
+        widget: widget.component,
+        type: field.type,
+        options: field.options || {},
+        isRepeatable: widget.isRepeatable,
+        isFile: widget.isFile,
+        isRelational: widget.isRelational
+    };
+    if ((field.interface === 'repeater' || field.interface === 'group') && field.options?.fields) {
+        base.fields = field.options.fields.map((sub) => generateFormField(sub));
+    }
+    return base;
+}
+export function generateFormSchema(fields) {
+    return fields
+        .filter(f => f.interface !== 'presentation' && f.interface !== 'divider')
+        .map(generateFormField);
+}

package/dist/generators/table-engine.d.ts

@@ -0,0 +1,6 @@
+import type { DirectusField } from '../schema/types';
+export declare function generateTableSchema(fields: DirectusField[]): {
+    key: string;
+    label: string;
+    type: string;
+}[];

package/dist/generators/table-engine.js

@@ -0,0 +1,9 @@
+export function generateTableSchema(fields) {
+    return fields
+        .filter(f => !f.hidden)
+        .map(f => ({
+        key: f.field,
+        label: f.field.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase()),
+        type: f.type
+    }));
+}

package/dist/generators/validation-engine.d.ts

@@ -0,0 +1,2 @@
+import type { DirectusField } from '../schema/types';
+export declare function validateField(field: DirectusField, value: any): string | null;

package/dist/generators/validation-engine.js

@@ -0,0 +1,25 @@
+export function validateField(field, value) {
+    if (!field.validation)
+        return null;
+    try {
+        const validation = field.validation;
+        if (validation._and) {
+            for (const rule of validation._and) {
+                const fieldName = Object.keys(rule)[0];
+                if (!fieldName)
+                    continue;
+                const ruleDef = rule[fieldName];
+                if (ruleDef?._regex) {
+                    const regex = new RegExp(ruleDef._regex);
+                    if (!regex.test(String(value ?? ''))) {
+                        return field.validation_message || `${field.field} failed validation`;
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        return `Validation error for ${field.field}`;
+    }
+    return null;
+}

package/dist/generators/widget-registry.d.ts

@@ -0,0 +1,9 @@
+export interface WidgetDefinition {
+    component: string;
+    props?: Record<string, any>;
+    isRepeatable?: boolean;
+    isRelational?: boolean;
+    isFile?: boolean;
+}
+export declare const widgetRegistry: Record<string, WidgetDefinition>;
+export declare function extendWidgetRegistryFromDirectus(client: any): Promise<void>;

package/dist/generators/widget-registry.js

@@ -0,0 +1,54 @@
+import { readItems } from "@directus/sdk";
+export const widgetRegistry = {
+    // Basic inputs
+    input: { component: 'TextInput' },
+    textarea: { component: 'TextareaInput' },
+    boolean: { component: 'ToggleInput' },
+    slider: { component: 'SliderInput' },
+    color: { component: 'ColorPicker' },
+    rating: { component: 'RatingInput' },
+    // Selects
+    'select-dropdown': { component: 'SelectInput' },
+    'select-multiple-dropdown': { component: 'MultiSelectInput' },
+    tags: { component: 'TagInput' },
+    checkbox: { component: 'CheckboxInput' },
+    radio: { component: 'RadioInput' },
+    // Date/time
+    datetime: { component: 'DateTimeInput' },
+    date: { component: 'DateInput' },
+    time: { component: 'TimeInput' },
+    // Files
+    file: { component: 'FileInput', isFile: true },
+    files: { component: 'FilesInput', isFile: true },
+    image: { component: 'ImageInput', isFile: true },
+    images: { component: 'ImagesInput', isFile: true },
+    // Complex
+    repeater: { component: 'RepeaterInput', isRepeatable: true },
+    group: { component: 'GroupInput' },
+    json: { component: 'JsonEditor' },
+    code: { component: 'CodeEditor' },
+    wysiwyg: { component: 'WysiwygEditor' },
+    markdown: { component: 'MarkdownEditor' },
+    // Directus-specific
+    icon: { component: 'IconPicker' },
+    user: { component: 'UserSelect' },
+    role: { component: 'RoleSelect' },
+    translation: { component: 'TranslationInput' },
+    // Presentation (ignored in forms)
+    presentation: { component: 'PresentationBlock' },
+    divider: { component: 'DividerBlock' }
+};
+export async function extendWidgetRegistryFromDirectus(client) {
+    const extensions = await client.request(readItems('directus_extensions'));
+    for (const ext of extensions) {
+        if (ext.type !== 'interface')
+            continue;
+        const name = ext.name;
+        if (!widgetRegistry[name]) {
+            widgetRegistry[name] = {
+                component: 'CustomInterfaceRenderer',
+                props: { interfaceName: name }
+            };
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from './client/createClient';
+export { default as DirectusVueProvider } from './vue/DirectusProvider';
+export * from './vue/useDirectus';
+export { DirectusProvider as DirectusReactProvider } from './react/DirectusProvider';
+export * from './react/useDirectus';
+export * from './schema/types';
+export * from './schema/introspect';
+export * from './utils/collections';
+export * from './utils/fields';
+export * from './generators/form-engine';
+export * from './generators/table-engine';
+export * from './generators/validation-engine';
+export * from './generators/widget-registry';

package/dist/index.js

@@ -0,0 +1,17 @@
+// src/index.ts
+export * from './client/createClient';
+// Vue bindings
+export { default as DirectusVueProvider } from './vue/DirectusProvider';
+export * from './vue/useDirectus';
+// React bindings
+export { DirectusProvider as DirectusReactProvider } from './react/DirectusProvider';
+export * from './react/useDirectus';
+// Schema + generators + utils
+export * from './schema/types';
+export * from './schema/introspect';
+export * from './utils/collections';
+export * from './utils/fields';
+export * from './generators/form-engine';
+export * from './generators/table-engine';
+export * from './generators/validation-engine';
+export * from './generators/widget-registry';

package/dist/react/DirectusProvider.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+import type { MeeoviDirectusClient } from '../client/createClient';
+export declare const DirectusContext: React.Context<MeeoviDirectusClient<any> | null>;
+export declare function DirectusProvider({ client, children }: {
+    client: MeeoviDirectusClient<any>;
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/react/DirectusProvider.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext } from 'react';
+export const DirectusContext = createContext(null);
+export function DirectusProvider({ client, children }) {
+    return (_jsx(DirectusContext.Provider, { value: client, children: children }));
+}

package/dist/react/useDirectus.d.ts

@@ -0,0 +1,2 @@
+import type { MeeoviDirectusClient } from '../client/createClient';
+export declare function useReactDirectus<Schema>(): MeeoviDirectusClient<Schema>;

package/dist/react/useDirectus.js

@@ -0,0 +1,9 @@
+import { useContext } from 'react';
+import { DirectusContext } from './DirectusProvider';
+export function useReactDirectus() {
+    const client = useContext(DirectusContext);
+    if (!client) {
+        throw new Error('Directus client not provided. Wrap your app in <DirectusProvider>.');
+    }
+    return client;
+}

package/dist/schema/introspect.d.ts

@@ -0,0 +1,5 @@
+import type { DirectusSchema, DirectusField, DirectusCollection, DirectusRelation } from './types';
+export declare function introspectCollections(client: any): Promise<DirectusCollection[]>;
+export declare function introspectFields(client: any, collection: string): Promise<DirectusField[]>;
+export declare function introspectRelations(client: any): Promise<DirectusRelation[]>;
+export declare function introspectSchema(client: any): Promise<DirectusSchema>;

package/dist/schema/introspect.js

@@ -0,0 +1,30 @@
+// schema/introspect.ts
+import { readFieldsByCollection, readItems } from '@directus/sdk';
+export async function introspectCollections(client) {
+    return await client.request(readItems('directus_collection'));
+}
+export async function introspectFields(client, collection) {
+    return await client.request(readFieldsByCollection(collection));
+}
+export async function introspectRelations(client) {
+    return await client.request(readItems('directus_relations'));
+}
+export async function introspectSchema(client) {
+    const [collections, relations] = await Promise.all([
+        introspectCollections(client),
+        introspectRelations(client),
+    ]);
+    const fields = [];
+    for (const col of collections) {
+        const colFields = await introspectFields(client, col.collection);
+        fields.push(...colFields);
+    }
+    return {
+        collections,
+        fields,
+        relations,
+        directus_collections: collections,
+        directus_fields: fields,
+        directus_relations: relations,
+    };
+}

package/dist/schema/types.d.ts

@@ -0,0 +1,47 @@
+export interface DirectusField {
+    collection: string;
+    field: string;
+    type: string;
+    interface?: string;
+    options?: Record<string, any>;
+    required?: boolean;
+    readonly?: boolean;
+    hidden?: boolean;
+    sort?: number;
+    special?: string[];
+    validation?: Record<string, any>;
+    validation_message?: string;
+}
+export interface DirectusRelation {
+    collection: string;
+    field: string;
+    related_collection: string | null;
+    meta?: Record<string, any>;
+}
+export interface DirectusCollection {
+    collection: string;
+    meta?: Record<string, any>;
+    schema?: Record<string, any>;
+}
+export interface DirectusSchema {
+    directus_collections: DirectusCollection[];
+    directus_relations: DirectusRelation[];
+    directus_fields: DirectusField[];
+    collections: DirectusCollection[];
+    fields: DirectusField[];
+    relations: DirectusRelation[];
+}
+export interface GeneratedFieldSchema {
+    key: string;
+    type: string;
+    widget: string;
+    required: boolean;
+    readonly: boolean;
+    hidden: boolean;
+    options?: Record<string, any>;
+    validation?: Record<string, any>;
+}
+export interface GeneratedCollectionSchema {
+    collection: string;
+    fields: GeneratedFieldSchema[];
+}

package/dist/schema/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/collections.d.ts

@@ -0,0 +1,5 @@
+import type { DirectusSchema, DirectusCollection, DirectusField } from '../schema/types';
+export declare function getCollection(schema: DirectusSchema, name: string): DirectusCollection | undefined;
+export declare function getCollectionFields(schema: DirectusSchema, name: string): DirectusField[];
+export declare function listCollections(schema: DirectusSchema): string[];
+export declare function isSingleton(schema: DirectusSchema, name: string): boolean;

package/dist/utils/collections.js

@@ -0,0 +1,13 @@
+export function getCollection(schema, name) {
+    return schema.collections.find(c => c.collection === name);
+}
+export function getCollectionFields(schema, name) {
+    return schema.fields.filter(f => f.collection === name);
+}
+export function listCollections(schema) {
+    return schema.collections.map(c => c.collection);
+}
+export function isSingleton(schema, name) {
+    const col = getCollection(schema, name);
+    return col?.meta?.singleton === true;
+}

package/dist/utils/fields.d.ts

@@ -0,0 +1,4 @@
+import type { DirectusField, GeneratedFieldSchema } from '../schema/types';
+export declare function mapFieldToWidget(field: DirectusField): string;
+export declare function generateFieldSchema(field: DirectusField): GeneratedFieldSchema;
+export declare function generateFieldsSchema(fields: DirectusField[]): GeneratedFieldSchema[];

package/dist/utils/fields.js

@@ -0,0 +1,40 @@
+export function mapFieldToWidget(field) {
+    if (field.interface)
+        return field.interface;
+    switch (field.type) {
+        case 'string':
+        case 'text':
+            return 'text';
+        case 'integer':
+        case 'bigInteger':
+        case 'float':
+        case 'decimal':
+            return 'number';
+        case 'boolean':
+            return 'checkbox';
+        case 'date':
+        case 'dateTime':
+            return 'date';
+        case 'json':
+            return 'json';
+        default:
+            return 'text';
+    }
+}
+export function generateFieldSchema(field) {
+    return {
+        key: field.field,
+        type: field.type,
+        widget: mapFieldToWidget(field),
+        required: field.required ?? false,
+        readonly: field.readonly ?? false,
+        hidden: field.hidden ?? false,
+        options: field.options ?? {},
+        validation: field.validation ?? {},
+    };
+}
+export function generateFieldsSchema(fields) {
+    return fields
+        .sort((a, b) => (a.sort ?? 0) - (b.sort ?? 0))
+        .map(generateFieldSchema);
+}

package/dist/utils/livePreview.d.ts

@@ -0,0 +1,11 @@
+export interface LivePreviewState {
+    token?: string;
+}
+export interface LivePreviewOptions {
+    query?: Record<string, string | undefined>;
+    initialState?: LivePreviewState;
+}
+export declare function createLivePreview(options: LivePreviewOptions): {
+    enabled: boolean;
+    state: LivePreviewState;
+};

package/dist/utils/livePreview.js

@@ -0,0 +1,11 @@
+export function createLivePreview(options) {
+    const { query = {}, initialState = {} } = options;
+    const shouldEnable = Boolean(query.preview) && Boolean(query.token);
+    const state = {
+        token: query.token || initialState.token,
+    };
+    return {
+        enabled: shouldEnable,
+        state,
+    };
+}