@stonecrop/stonecrop 0.3.5 → 0.3.7

package/dist/stonecrop.d.ts

@@ -0,0 +1,576 @@
+import { Component } from 'vue';
+import { List } from 'immutable';
+import { MachineConfig } from 'xstate';
+import { Map as Map_2 } from 'immutable';
+import { Plugin as Plugin_2 } from 'vue';
+import { Ref } from 'vue';
+import { Router } from 'vue-router';
+import { StateMachine } from 'xstate';
+import { StoreDefinition } from 'pinia';
+
+/**
+ * Basic field structure for AForm schemas
+ * @public
+ */
+export declare type BaseSchema = {
+    /**
+     * The fieldname for the schema field
+     * @public
+     */
+    fieldname: string;
+    /**
+     * The component to render
+     *
+     * @remarks
+     * This must be a string that represents the component to render. The registration of the component
+     * should be done in the main application.
+     *
+     * @public
+     */
+    component?: string;
+    /**
+     * A placeholder value for the field
+     * @beta
+     */
+    value?: any;
+};
+
+/**
+ * Table cell context definition.
+ * @public
+ */
+export declare type CellContext = {
+    row: TableRow;
+    column: TableColumn;
+    table: {
+        [key: string]: any;
+    };
+};
+
+/**
+ * Doctype Meta class
+ * @public
+ */
+export declare class DoctypeMeta {
+    /**
+     * The doctype name
+     * @public
+     * @readonly
+     */
+    readonly doctype: string;
+    /**
+     * The doctype schema
+     * @public
+     * @readonly
+     */
+    readonly schema: ImmutableDoctype['schema'];
+    /**
+     * The doctype workflow
+     * @public
+     * @readonly
+     */
+    readonly workflow: ImmutableDoctype['workflow'];
+    /**
+     * The doctype actions
+     * @public
+     * @readonly
+     */
+    readonly actions: ImmutableDoctype['actions'];
+    /**
+     * The doctype component
+     * @public
+     * @readonly
+     */
+    readonly component?: Component;
+    constructor(doctype: string, schema: ImmutableDoctype['schema'], workflow: ImmutableDoctype['workflow'], actions: ImmutableDoctype['actions'], component?: Component);
+    /**
+     * Converts the registered doctype to a slug (kebab-case)
+     * @returns The slugified doctype string
+     * @public
+     */
+    get slug(): string;
+}
+
+/**
+ * Schema structure for defining fieldsets inside AForm
+ * @public
+ */
+export declare type FieldsetSchema = BaseSchema & {
+    /**
+     * The label to display in the fieldset
+     * @public
+     */
+    label?: string;
+    /**
+     * The schemas to be rendered inside the fieldset
+     * @public
+     */
+    schema?: (FormSchema | TableSchema)[];
+    /**
+     * Indicate whether the fieldset is collapsible
+     * @public
+     */
+    collapsible?: boolean;
+};
+
+/**
+ * Schema structure for defining forms inside AForm
+ * @public
+ */
+export declare type FormSchema = BaseSchema & {
+    /**
+     * Align the field in the form
+     * @beta
+     */
+    align?: string;
+    /**
+     * Indicate whether the field is editable
+     * @beta
+     */
+    edit?: boolean;
+    /**
+     * The field type for the schema field
+     *
+     * @remarks
+     * This must be a string that represents the field type. A mask string will be automatically
+     * applied for the following field types:
+     * - Date ('##/##/####')
+     * - Datetime ('####/##/## ##:##')
+     * - Time ('##:##')
+     * - Fulltime ('##:##:##')
+     * - Phone ('(###) ### - ####')
+     * - Card ('#### #### #### ####')
+     *
+     * @public
+     */
+    fieldtype?: string;
+    /**
+     * The label to display in the form
+     * @public
+     */
+    label?: string;
+    /**
+     * The unique identifier for the field
+     * @beta
+     */
+    name?: string;
+    /**
+     * The width of the field element.
+     * @beta
+     */
+    width?: string;
+    /**
+     * The mask string for the field
+     * @beta
+     */
+    mask?: string;
+};
+
+/**
+ * Immutable Doctype type for Stonecrop instances
+ * @public
+ */
+export declare type ImmutableDoctype = {
+    readonly schema?: List<SchemaTypes>;
+    readonly workflow: StateMachine<unknown, unknown, any>;
+    readonly actions?: Map_2<string, string[]>;
+};
+
+/**
+ * Install options for Stonecrop Vue plugin
+ * @public
+ */
+export declare type InstallOptions = {
+    router?: Router;
+    components?: Record<string, Component>;
+    getMeta?: (doctype?: string) => DoctypeMeta | Promise<DoctypeMeta>;
+};
+
+/**
+ * Mutable Doctype type for Stonecrop instances
+ * @public
+ */
+export declare type MutableDoctype = {
+    schema?: SchemaTypes[];
+    workflow: MachineConfig<unknown, unknown, any>;
+    actions?: Record<string, string[]>;
+};
+
+/**
+ * Stonecrop Registry class
+ * @public
+ */
+export declare class Registry {
+    /**
+     * The root Registry instance
+     */
+    static _root: Registry;
+    /**
+     * The name of the Registry instance
+     *
+     * @defaultValue 'Registry'
+     */
+    name: string;
+    /**
+     * The Vue router instance
+     * @see {@link https://router.vuejs.org/}
+     */
+    router: Router;
+    /**
+     * The registry property contains a collection of doctypes
+     * @see {@link DoctypeMeta}
+     */
+    registry: Record<string, DoctypeMeta>;
+    /**
+     * The getMeta function fetches doctype metadata from an API
+     * @see {@link DoctypeMeta}
+     */
+    getMeta?: (doctype: string) => DoctypeMeta | Promise<DoctypeMeta>;
+    constructor(router: Router, getMeta?: (doctype: string) => DoctypeMeta | Promise<DoctypeMeta>);
+    /**
+     * Get doctype metadata
+     * @param doctype - The doctype to fetch metadata for
+     * @returns The doctype metadata
+     * @see {@link DoctypeMeta}
+     */
+    addDoctype(doctype: DoctypeMeta): void;
+}
+
+/**
+ * Schema type for Stonecrop instances
+ * @public
+ */
+export declare type Schema = {
+    doctype: string;
+    schema: List<SchemaTypes>;
+};
+
+/**
+ * Superset of all schema types for AForm
+ * @public
+ */
+export declare type SchemaTypes = FormSchema | TableSchema | FieldsetSchema;
+
+/**
+ * Stonecrop Vue plugin
+ * @param app - The Vue app instance
+ * @param options - The plugin options
+ * @example
+ * ```ts
+ *
+ * import { createApp } from 'vue'
+ * import Stonecrop from 'stonecrop'
+ *
+ * import App from './App.vue'
+ *
+ * const app = createApp(App)
+ * app.use(Stonecrop, {
+ *  router,
+ *  components: {
+ *   // register custom components
+ *  },
+ *  getMeta: async (doctype: string) => {
+ *   // fetch doctype meta from API
+ *  },
+ * })
+ *
+ * app.mount('#app')
+ * ```
+ *
+ * @public
+ */
+export declare const Stonecrop: Plugin_2;
+
+/**
+ * Stonecrop class
+ * @public
+ */
+declare class Stonecrop_2 {
+    /**
+     * The root Stonecrop instance
+     */
+    static _root: Stonecrop_2;
+    /**
+     * The name of the Stonecrop instance
+     * @readonly
+     *
+     * @defaultValue 'Stonecrop'
+     */
+    readonly name = "Stonecrop";
+    /**
+     * The registry is an immutable collection of doctypes
+     * @example
+     * ```ts
+     * {
+     * 	'task': {
+     * 		doctype: 'Task',
+     * 		schema: {
+     * 			title: 'string',
+     * 			description: 'string',
+     * 			...
+     * 		}
+     * 	},
+     * 	...
+     * }
+     * ```
+     * @see {@link Registry}
+     * @see {@link DoctypeMeta}
+     */
+    readonly registry: Registry;
+    /**
+     * schema - The Stonecrop schema; the schema is a subset of the registry
+     * @example
+     * ```ts
+     * {
+     * 	doctype: 'Task',
+     * 	schema: {
+     * 		title: 'string',
+     * 		description: 'string',
+     * 		...
+     * 	}
+     * }
+     * ```
+     * @see {@link Registry}
+     * @see {@link DoctypeMeta}
+     * @see {@link DoctypeMeta.schema}
+     */
+    schema: Schema;
+    /**
+     * The workflow is a subset of the registry
+     */
+    workflow: ImmutableDoctype['workflow'];
+    /**
+     * The actions are a subset of the registry
+     */
+    actions: ImmutableDoctype['actions'];
+    /**
+     * The Pinia store that manages the mutable records
+     */
+    store: ReturnType<typeof useDataStore>;
+    /**
+     * @param registry - The immutable registry
+     * @param store - The mutable Pinia store
+     * @param schema - The Stonecrop schema
+     * @param workflow - The Stonecrop workflow
+     * @param actions - The Stonecrop actions
+     * @returns The Stonecrop instance with the given registry, store, schema, workflow, and actions. If a Stonecrop instance has already been created, it returns the existing instance instead of creating a new one.
+     * @example
+     * ```ts
+     * const registry = new Registry()
+     * const store = useDataStore()
+     * const stonecrop = new Stonecrop(registry, store)
+     * ```
+     */
+    constructor(registry: Registry, store: ReturnType<typeof useDataStore>, schema?: Schema, workflow?: ImmutableDoctype['workflow'], actions?: ImmutableDoctype['actions']);
+    /**
+     * Sets up the Stonecrop instance with the given doctype
+     * @param doctype - The doctype to setup
+     * @example
+     * ```ts
+     * const doctype = await registry.getMeta('Task')
+     * stonecrop.setup(doctype)
+     * ```
+     */
+    setup(doctype: DoctypeMeta): void;
+    /**
+     * Gets the meta for the given doctype
+     * @param doctype - The doctype to get meta for
+     * @returns The meta for the given doctype
+     * @throws NotImplementedError
+     * @example
+     * ```ts
+     * const doctype = await registry.getMeta('Task')
+     * const meta = stonecrop.getMeta(doctype)
+     * ```
+     * @see {@link DoctypeMeta}
+     */
+    getMeta(doctype: DoctypeMeta): DoctypeMeta | Promise<DoctypeMeta> | never;
+    /**
+     * Gets the workflow for the given doctype
+     * @param doctype - The doctype to get workflow for
+     * @example
+     * ```ts
+     * const doctype = await registry.getMeta('Task')
+     * stonecrop.getWorkflow(doctype)
+     * ```
+     */
+    getWorkflow(doctype: DoctypeMeta): void;
+    /**
+     * Gets the actions for the given doctype
+     * @param doctype - The doctype to get actions for
+     * @example
+     * ```ts
+     * const doctype = await registry.getMeta('Task')
+     * stonecrop.getActions(doctype)
+     * ```
+     */
+    getActions(doctype: DoctypeMeta): void;
+    /**
+     * Gets the records for the given doctype
+     * @param doctype - The doctype to get records for
+     * @param filters - The filters to apply to the records
+     * @example
+     * ```ts
+     * const doctype = await registry.getMeta('Task')
+     * await stonecrop.getRecords(doctype)
+     * ```
+     * @example
+     * ```ts
+     * const doctype = await registry.getMeta('Task')
+     * const filters = JSON.stringify({ status: 'Open' })
+     * await stonecrop.getRecords(doctype, { body: filters })
+     * ```
+     */
+    getRecords(doctype: DoctypeMeta, filters?: RequestInit): Promise<void>;
+    /**
+     * Gets the record for the given doctype and id
+     * @param doctype - The doctype to get record for
+     * @param id - The id of the record to get
+     * @example
+     * ```ts
+     * const doctype = await registry.getMeta('Task')
+     * await stonecrop.getRecord(doctype, 'TASK-00001')
+     * ```
+     */
+    getRecord(doctype: DoctypeMeta, id: string): Promise<void>;
+    /**
+     * Runs the action for the given doctype and id
+     * @param doctype - The doctype to run action for
+     * @param action - The action to run
+     * @param id - The id(s) of the record(s) to run action on
+     * @example
+     * ```ts
+     * const doctype = await registry.getMeta('Task')
+     * stonecrop.runAction(doctype, 'CREATE')
+     * ```
+     * @example
+     * ```ts
+     * const doctype = await registry.getMeta('Task')
+     * stonecrop.runAction(doctype, 'UPDATE', ['TASK-00001'])
+     * ```
+     * @example
+     * ```ts
+     * const doctype = await registry.getMeta('Task')
+     * stonecrop.runAction(doctype, 'DELETE', ['TASK-00001'])
+     * ```
+     * @example
+     * ```ts
+     * const doctype = await registry.getMeta('Task')
+     * stonecrop.runAction(doctype, 'TRANSITION', ['TASK-00001', 'TASK-00002'])
+     * ```
+     */
+    runAction(doctype: DoctypeMeta, action: string, id?: string[]): void;
+}
+
+/**
+ * Stonecrop composable return type
+ * @public
+ */
+export declare type StonecropReturn = {
+    stonecrop: Ref<Stonecrop_2>;
+    isReady: Ref<boolean>;
+};
+
+/**
+ * Table column definition.
+ * @public
+ */
+export declare type TableColumn = {
+    name: string;
+    align?: CanvasTextAlign;
+    edit?: boolean;
+    label?: string;
+    type?: string;
+    width?: string;
+    pinned?: boolean;
+    cellComponent?: string;
+    cellComponentProps?: Record<string, any>;
+    /**
+     * The component to use for the modal. If a function is provided, it will be called with the cell context.
+     * The following properties are available on the cell context:
+     * - `row` - the row object
+     * - `column` - the column object
+     * - `table` - the table object
+     *
+     * The function should return the name of the component to use for the modal.
+     *
+     * Additionally, the following properties will be automatically passed to the modal component:
+     * - `colIndex` - the column index of the current cell
+     * - `rowIndex` - the row index of the current cell
+     * - `store` - the table data store
+     */
+    modalComponent?: string | ((context: CellContext) => string);
+    modalComponentExtraProps?: Record<string, any>;
+    format?: string | ((value: any, context: CellContext) => string);
+    mask?: (value: any) => any;
+};
+
+/**
+ * Table configuration definition.
+ * @public
+ */
+export declare type TableConfig = {
+    /**
+     * The type of view to display the table in. Possible values:
+     * - `uncounted` - row numbers are not displayed in the table
+     * - `list` - row numbers are displayed in the table
+     * - `list-expansion` - carets are displayed in the number column that expand/collapse the row inline
+     * - `tree` - carets are displayed in the number column that expand/collapse grouped rows
+     */
+    view?: 'uncounted' | 'list' | 'list-expansion' | 'tree';
+    fullWidth?: boolean;
+};
+
+/**
+ * Table row definition.
+ * @public
+ */
+export declare type TableRow = {
+    [key: string]: any;
+    indent?: number;
+    parent?: number;
+};
+
+/**
+ * Schema structure for defining tables inside AForm
+ * @public
+ */
+export declare type TableSchema = BaseSchema & {
+    /**
+     * The columns to display in the table
+     * @public
+     */
+    columns?: TableColumn[];
+    /**
+     * The configuration for the table
+     * @public
+     */
+    config?: TableConfig;
+    /**
+     * The rows to display in the table
+     * @public
+     */
+    rows?: TableRow[];
+};
+
+declare const useDataStore: StoreDefinition<"data", Pick<{
+records: Ref<Record<string, any>[], Record<string, any>[]>;
+record: Ref<Record<string, any>, Record<string, any>>;
+}, "records" | "record">, Pick<{
+records: Ref<Record<string, any>[], Record<string, any>[]>;
+record: Ref<Record<string, any>, Record<string, any>>;
+}, never>, Pick<{
+records: Ref<Record<string, any>[], Record<string, any>[]>;
+record: Ref<Record<string, any>, Record<string, any>>;
+}, never>>;
+
+/**
+ * Stonecrop composable
+ * @param registry - An existing Stonecrop Registry instance
+ * @returns The Stonecrop instance and a boolean indicating if Stonecrop is setup and ready
+ * @throws Error if the Stonecrop plugin is not enabled before using the composable
+ * @public
+ */
+export declare function useStonecrop(registry?: Registry): StonecropReturn;
+
+export { }