@stonecrop/stonecrop 0.3.5 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/stonecrop",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "schema helper",
   "license": "MIT",
   "type": "module",
@@ -52,9 +52,9 @@
     "eslint-plugin-vue": "^9.11.1",
     "typescript": "^5.6.3",
     "vite": "^5.4.5",
-    "@stonecrop/aform": "0.3.5",
+    "@stonecrop/aform": "0.3.6",
     "stonecrop-rig": "0.2.22",
-    "@stonecrop/atable": "0.3.5"
+    "@stonecrop/atable": "0.3.6"
   },
   "publishConfig": {
     "access": "public"
@@ -63,8 +63,8 @@
     "node": ">=20.11.0"
   },
   "scripts": {
-    "prepublish": "heft build && vite build",
-    "build": "heft build && vite build",
+    "prepublish": "heft build && vite build && rushx docs",
+    "build": "heft build && vite build && rushx docs",
     "docs": "api-documenter markdown -i temp -o ../docs/stonecrop",
     "lint": "eslint . --ext .ts,.vue",
     "preview": "vite preview"

package/src/composable.ts

@@ -4,11 +4,22 @@ import Registry from './registry'
 import { Stonecrop } from './stonecrop'
 import { useDataStore } from './stores/data'
 
-type StonecropReturn = {
+/**
+ * Stonecrop composable return type
+ * @public
+ */
+export type StonecropReturn = {
 	stonecrop: Ref<Stonecrop>
 	isReady: Ref<boolean>
 }
 
+/**
+ * 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 function useStonecrop(registry?: Registry): StonecropReturn {
 	if (!registry) {
 		registry = inject<Registry>('$registry')

package/src/doctype.ts

@@ -2,14 +2,47 @@ import { Component } from 'vue'
 
 import type { ImmutableDoctype } from './types'
 
+/**
+ * Doctype Meta class
+ * @public
+ */
 export default 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
 	// TODO: allow different components for different views; probably
 	// should be defined in the schema instead?
-	readonly component?: Component
 
 	constructor(
 		doctype: string,
@@ -25,15 +58,15 @@ export default class DoctypeMeta {
 		this.component = component
 	}
 
+	/**
+	 * Converts the registered doctype to a slug (kebab-case)
+	 * @returns The slugified doctype string
+	 * @public
+	 */
 	get slug() {
-		// kebab case
 		return this.doctype
 			.replace(/([a-z])([A-Z])/g, '$1-$2')
 			.replace(/[\s_]+/g, '-')
 			.toLowerCase()
 	}
-
-	get __typename() {
-		return this.doctype
-	}
 }

package/src/index.ts

@@ -1,7 +1,10 @@
-import { useStonecrop } from './composable'
+export type { BaseSchema, FieldsetSchema, FormSchema, SchemaTypes, TableSchema } from '@stonecrop/aform'
+export type { CellContext, TableColumn, TableConfig, TableRow } from '@stonecrop/atable'
+
+import { type StonecropReturn, useStonecrop } from './composable'
 import DoctypeMeta from './doctype'
 import Registry from './registry'
 import Stonecrop from './plugins'
 export type { ImmutableDoctype, MutableDoctype, Schema, InstallOptions } from './types'
 
-export { DoctypeMeta, Registry, Stonecrop, useStonecrop }
+export { DoctypeMeta, Registry, Stonecrop, StonecropReturn, useStonecrop }

package/src/plugins/index.ts

@@ -5,6 +5,34 @@ import router from '../router'
 import { pinia } from '../stores'
 import type { InstallOptions } from '../types'
 
+/**
+ * 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
+ */
 const plugin: Plugin = {
 	install: (app: App, options?: InstallOptions) => {
 		const appRouter = options?.router || router

package/src/registry.ts

@@ -2,11 +2,39 @@ import { Router } from 'vue-router'
 
 import DoctypeMeta from './doctype'
 
+/**
+ * Stonecrop Registry class
+ * @public
+ */
 export default 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>) {
@@ -20,6 +48,12 @@ export default class Registry {
 		this.getMeta = getMeta
 	}
 
+	/**
+	 * Get doctype metadata
+	 * @param doctype - The doctype to fetch metadata for
+	 * @returns The doctype metadata
+	 * @see {@link DoctypeMeta}
+	 */
 	addDoctype(doctype: DoctypeMeta) {
 		if (!(doctype.doctype in Object.keys(this.registry))) {
 			this.registry[doctype.slug] = doctype

package/src/stonecrop.ts

@@ -4,25 +4,28 @@ import Registry from './registry'
 import { useDataStore } from './stores/data'
 import type { ImmutableDoctype, Schema } from './types'
 
+/**
+ * Stonecrop class
+ * @public
+ */
 export class Stonecrop {
 	/**
-	 * @property {Stonecrop} _root
-	 * @description The root Stonecrop instance
+	 * The root Stonecrop instance
 	 */
 	static _root: Stonecrop
 
 	/**
-	 * @property {string} name
-	 * @description The name of the Stonecrop instance
-	 * @example
-	 * 'Stonecrop'
+	 * The name of the Stonecrop instance
+	 * @readonly
+	 *
+	 * @defaultValue 'Stonecrop'
 	 */
 	readonly name = 'Stonecrop'
 
 	/**
-	 * @property {Registry} registry
-	 * @description The registry is an immutable collection of doctypes
+	 * The registry is an immutable collection of doctypes
 	 * @example
+	 * ```ts
 	 * {
 	 * 	'task': {
 	 * 		doctype: 'Task',
@@ -34,15 +37,16 @@ export class Stonecrop {
 	 * 	},
 	 * 	...
 	 * }
+	 * ```
 	 * @see {@link Registry}
 	 * @see {@link DoctypeMeta}
 	 */
 	readonly registry: Registry
 
 	/**
-	 * @property {Schema} schema - The Stonecrop schema
-	 * @description The schema is a subset of the registry
+	 * schema - The Stonecrop schema; the schema is a subset of the registry
 	 * @example
+	 * ```ts
 	 * {
 	 * 	doctype: 'Task',
 	 * 	schema: {
@@ -51,6 +55,7 @@ export class Stonecrop {
 	 * 		...
 	 * 	}
 	 * }
+	 * ```
 	 * @see {@link Registry}
 	 * @see {@link DoctypeMeta}
 	 * @see {@link DoctypeMeta.schema}
@@ -58,36 +63,33 @@ export class Stonecrop {
 	schema: Schema
 
 	/**
-	 * @property {ImmutableDoctype['workflow']} workflow
-	 * @description The workflow is a subset of the registry
+	 * The workflow is a subset of the registry
 	 */
 	workflow: ImmutableDoctype['workflow']
 
 	/**
-	 * @property {ImmutableDoctype['actions']} actions
-	 * @description The actions are a subset of the registry
+	 * The actions are a subset of the registry
 	 */
 	actions: ImmutableDoctype['actions']
 
 	/**
-	 * @property {ReturnType<typeof useDataStore>} store
-	 * @description The Pinia store that manages the mutable records
+	 * The Pinia store that manages the mutable records
 	 */
 	store: ReturnType<typeof useDataStore>
 
 	/**
-	 * @constructor
-	 * @param {Registry} registry - The immutable registry
-	 * @param {ReturnType<typeof useDataStore>} store - The mutable Pinia store
-	 * @param {Schema} [schema] - (optional) The Stonecrop schema
-	 * @param {ImmutableDoctype['workflow']} [workflow] - (optional) The Stonecrop workflow
-	 * @param {ImmutableDoctype['actions']} [actions] - (optional) The Stonecrop actions
-	 * @returns {Stonecrop} The Stonecrop instance
-	 * @description The Stonecrop constructor initializes a new 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.
+	 * @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, schema, workflow, actions)
+	 * const stonecrop = new Stonecrop(registry, store)
+	 * ```
 	 */
 	constructor(
 		registry: Registry,
@@ -108,13 +110,13 @@ export class Stonecrop {
 	}
 
 	/**
-	 * @method setup
-	 * @param {DoctypeMeta} doctype - The doctype to setup
-	 * @returns {void}
-	 * @description Sets up the Stonecrop instance with the given doctype
+	 * 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 {
 		void this.getMeta(doctype)
@@ -123,28 +125,29 @@ export class Stonecrop {
 	}
 
 	/**
-	 * @method getMeta
-	 * @param {DoctypeMeta} doctype - The doctype to get meta for
-	 * @returns {DoctypeMeta}
-	 * @see {@link DoctypeMeta}
+	 * Gets the meta for the given doctype
+	 * @param doctype - The doctype to get meta for
+	 * @returns The meta for the given doctype
 	 * @throws NotImplementedError
-	 * @description Gets the meta for the given doctype
 	 * @example
+	 * ```ts
 	 * const doctype = await registry.getMeta('Task')
 	 * const meta = stonecrop.getMeta(doctype)
+	 * ```
+	 * @see {@link DoctypeMeta}
 	 */
 	getMeta(doctype: DoctypeMeta): DoctypeMeta | Promise<DoctypeMeta> | never {
 		return this.registry.getMeta ? this.registry.getMeta(doctype.doctype) : new NotImplementedError(doctype.doctype)
 	}
 
 	/**
-	 * @method getWorkflow
-	 * @param {DoctypeMeta} doctype - The doctype to get workflow for
-	 * @returns {void}
-	 * @description Gets the workflow for the given doctype
+	 * 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 {
 		const doctypeRegistry = this.registry.registry[doctype.slug]
@@ -152,13 +155,13 @@ export class Stonecrop {
 	}
 
 	/**
-	 * @method getActions
-	 * @param {DoctypeMeta} doctype - The doctype to get actions for
-	 * @returns {void}
-	 * @description Gets the actions for the given doctype
+	 * 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 {
 		const doctypeRegistry = this.registry.registry[doctype.slug]
@@ -166,18 +169,20 @@ export class Stonecrop {
 	}
 
 	/**
-	 * @method getRecords
-	 * @param {DoctypeMeta} doctype - The doctype to get records for
-	 * @param {RequestInit} [filters] - The filters to apply to the records
-	 * @returns {Promise<void>}
-	 * @description Gets the records for the given doctype
+	 * 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 })
+	 * ```
 	 */
 	async getRecords(doctype: DoctypeMeta, filters?: RequestInit): Promise<void> {
 		this.store.$patch({ records: [] })
@@ -187,14 +192,14 @@ export class Stonecrop {
 	}
 
 	/**
-	 * @method getRecord
-	 * @param {DoctypeMeta} doctype - The doctype to get record for
-	 * @param {string} id - The id of the record to get
-	 * @returns {Promise<void>}
-	 * @description Gets the record for the given doctype and id
+	 * 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')
+	 * ```
 	 */
 	async getRecord(doctype: DoctypeMeta, id: string): Promise<void> {
 		this.store.$patch({ record: {} })
@@ -204,24 +209,30 @@ export class Stonecrop {
 	}
 
 	/**
-	 * @method runAction
-	 * @param {DoctypeMeta} doctype - The doctype to run action for
-	 * @param {string} action - The action to run
-	 * @param {string[]} [id] - The id(s) of the record(s) to run action on
-	 * @returns {void}
-	 * @description Runs the action for the given doctype and id
+	 * 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 {
 		const doctypeRegistry = this.registry.registry[doctype.slug]

package/src/types/index.ts

@@ -6,6 +6,10 @@ import { MachineConfig, StateMachine } from 'xstate'
 
 import DoctypeMeta from '../doctype'
 
+/**
+ * Immutable Doctype type for Stonecrop instances
+ * @public
+ */
 export type ImmutableDoctype = {
 	// TODO: allow schema to be a function
 	readonly schema?: List<SchemaTypes>
@@ -13,6 +17,10 @@ export type ImmutableDoctype = {
 	readonly actions?: Map<string, string[]>
 }
 
+/**
+ * Mutable Doctype type for Stonecrop instances
+ * @public
+ */
 export type MutableDoctype = {
 	// TODO: allow schema to be a function
 	schema?: SchemaTypes[]
@@ -20,11 +28,19 @@ export type MutableDoctype = {
 	actions?: Record<string, string[]>
 }
 
+/**
+ * Schema type for Stonecrop instances
+ * @public
+ */
 export type Schema = {
 	doctype: string
 	schema: List<SchemaTypes>
 }
 
+/**
+ * Install options for Stonecrop Vue plugin
+ * @public
+ */
 export type InstallOptions = {
 	router?: Router
 	components?: Record<string, Component>