@agile-team/mach-table-vue 0.19.0 → 0.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/mach-table-vue",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Official Vue 3 adapter for the MachTable enterprise data grid",
   "keywords": [
     "vue",
@@ -108,7 +108,7 @@
     "**/*.css"
   ],
   "dependencies": {
-    "@agile-team/mach-table": "0.19.0"
+    "@agile-team/mach-table": "0.19.1"
   },
   "peerDependencies": {
     "vue": ">=3.2.0"
@@ -121,5 +121,6 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage"
-  }
+  },
+  "readme": "<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/ChenyCHENYU/MachTable/main/assets/mach-table-logo.svg\" alt=\"MachTable\" width=\"760\" />\n</p>\n\n# @agile-team/mach-table-vue\n\nOfficial Vue 3 adapter for MachTable 0.19. It provides a generic `<MachTable>`, native typed slots, dedicated app/route configuration, cohesive controllers, advanced-filter aware remote query, conflict-aware editing composables, persistent named views, optional and persistent column resizing, random-access remote blocks, batched/domain APIs, optional Worker processing, an optional standard toolbar, optional Element Plus editors, async boundaries, in-place renderer refresh and automatic lifecycle cleanup. `RobotGrid` remains a deprecated 0.x alias.\n\n## Install\n\n```bash\npnpm add @agile-team/mach-table-vue\n```\n\nImport the stylesheet once from your application entry:\n\n```ts\nimport \"@agile-team/mach-table-vue/styles.css\";\n```\n\nOptional large local-data Worker helpers use the same installed package but a separate chunk:\n\n```ts\nimport { createWorkerDataProcessor } from \"@agile-team/mach-table-vue/worker\";\n```\n\n## Integration modes\n\n### Local, route-level import\n\nBest when only a few routes use a grid. A lazy-loaded route naturally keeps MachTable in that route's chunk.\n\n```vue\n<script setup lang=\"ts\">\nimport { ref } from \"vue\";\nimport { MachTable, useMachTable, type ColDef } from \"@agile-team/mach-table-vue\";\n\ninterface Row { id: string; name: string }\nconst grid = useMachTable<Row>();\nconst rows = ref<Row[]>([{ id: \"1\", name: \"MachTable\" }]);\nconst columns: ColDef<Row>[] = [{ field: \"name\", headerName: \"Name\", flex: 1 }];\n</script>\n\n<template>\n  <div style=\"height: 520px\">\n    <MachTable\n      :ref=\"grid.ref\"\n      :row-data=\"rows\"\n      :column-defs=\"columns\"\n      row-key=\"id\"\n      state-key=\"customer-list\"\n      enable-column-resize\n      striped-rows\n    />\n  </div>\n</template>\n```\n\n### Global synchronous plugin\n\nBest when most screens render tables. Components are available in every template without page-level runtime imports.\n\n```ts\n// main.ts\nimport { createApp } from \"vue\";\nimport { MachTablePlugin } from \"@agile-team/mach-table-vue\";\nimport \"@agile-team/mach-table-vue/styles.css\";\nimport App from \"./App.vue\";\n\ncreateApp(App).use(MachTablePlugin).mount(\"#app\");\n```\n\n### Global async plugin\n\nBest for large admin or low-code applications. The plugin is registered at startup, while the component and Core stay in a separate chunk until the first `<MachTable>` is rendered.\n\n```ts\n// main.ts\nimport { createApp } from \"vue\";\nimport AsyncMachTablePlugin, { preloadMachTable } from \"@agile-team/mach-table-vue/async\";\nimport \"@agile-team/mach-table-vue/styles.css\";\nimport App from \"./App.vue\";\n\ncreateApp(App).use(AsyncMachTablePlugin).mount(\"#app\");\n\n// Optional route-hover prefetch; dynamic imports are cached and idempotent.\nvoid preloadMachTable();\n```\n\nThe standard toolbar is a separate, tree-shakeable entry. Register it globally only when needed:\n\n```ts\nimport MachTableUiPlugin from \"@agile-team/mach-table-vue/ui\";\napp.use(MachTableUiPlugin);\n```\n\nAfter either global plugin is installed, pages can use `<MachTable>` directly. Keep conventions in a dedicated `mach-table.config.ts`, then install it with one clean line:\n\n```ts\n// mach-table.config.ts\nimport { defineMachTableConfig, defineMachTablePreset } from \"@agile-team/mach-table-vue\";\nexport default defineMachTableConfig({\n  defaults: {\n    size: \"compact\",\n    enableColumnResize: true,\n    pagination: { pageSize: 20, pageSizeOptions: [20, 50, 100] },\n    defaultColDef: { sortable: true, resizable: true, filter: true }\n  },\n  defaultPreset: \"list\",\n  presets: { list: defineMachTablePreset({ stripedRows: true }) }\n});\n\n// main.ts\napp.use(MachTablePlugin, machTableConfig);\n```\n\nLayouts can reactively refine defaults and presets with `provideMachTableConfig(...)`; direct table props always win. `provideMachTableDefaults(...)` remains as a smaller compatibility API. The async plugin also accepts `asyncComponentOptions` with `loadingComponent`, `errorComponent`, `delay`, `timeout` and `onError`.\n\nThe adapter installs the matching `@agile-team/mach-table` core automatically and re-exports its complete API and types. Only `vue >= 3.2` remains a peer dependency supplied by the host application. Existing local imports remain fully supported.\n\nRemote B-side lists can bind `useMachTableQuery()` directly. Use `mode: \"auto\"` for live filters or `mode: \"manual\"` for a submit-to-search form. For the smallest composable-only chunk, import query/editing/controller helpers from `@agile-team/mach-table-vue/workflows`. They own controlled server pagination, AbortSignal cancellation, stale-response protection, retry state and cross-page selection without exposing `gridApi` to ordinary pages.\n\n`useMachTableController()` composes table readiness, query, editing, selection, errors and standard commands. Pair it with `MachTableToolbar` from `/ui`, or bind `controller.commands` to your own design-system toolbar.\n\nMillion-row batch actions use `selectionScope: \"query\"` and compact `allMatching + excludedKeys` rules, so clients never download every matching row ID.\n\n`useMachTableEditing()` exposes reactive dirty changes, detailed partial-save results, validation failures, version conflicts, failed-row reveal, rollback and an optional unsaved-page guard. `lastSaveResult`, `saveIssues`, `failedRowIds` and `resolveConflict()` keep page code small while preserving explicit business decisions. Semantic business types and cached dictionaries are configured once with `createBusinessColumnTypes()` and `createCachedDictionary()`.\n\n```ts\nconst editing = useMachTableEditing(grid, { guardBeforeUnload: true });\nconst result = await editing.saveDetailed(orderApi.saveChanges);\nif (result.conflicts.length) editing.reveal(result.conflicts[0].rowId);\n\nasync function saveCurrentView() {\n  if (!grid.api.value) return;\n  const views = createGridViewManager(grid.api.value, {\n    scope: `${tenantId}:${userId}:orders`\n  });\n  await views.save(\"My pending orders\");\n}\n```\n\nRemote query requests include both `filterModel` and the serializable nested `advancedFilterModel`. See the [advanced filter](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/recipes/advanced-filter.md), [named views](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/recipes/saved-views.md), and [batch save](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/recipes/batch-save.md) guides.\n\nElement Plus editors are optional and registered once without making EP a package dependency:\n\n```ts\nimport { createElementPlusEditors } from \"@agile-team/mach-table-vue/editors\";\n\nconst ep = createElementPlusEditors({\n  input: ElInput,\n  inputNumber: ElInputNumber,\n  select: ElSelect,\n  datePicker: ElDatePicker\n});\n```\n\nUse `api.openColumnWorkbench()` for the built-in column settings UI. Lazy trees opt in with `isTreeRowExpandable` plus `loadTreeChildren`; ordinary tree data is unchanged.\n\n## Cell and full-row editing\n\nCore helpers are re-exported, so no second package import is needed:\n\n```vue\n<script setup lang=\"ts\">\nimport { rowActionsColumn } from \"@agile-team/mach-table-vue\";\n\nconst columns = [\n  { field: \"name\", editable: true },\n  { field: \"age\", editable: true, cellEditor: \"number\" },\n  rowActionsColumn({ onView, onDelete, overflow: \"drawer\" })\n];\n</script>\n\n<template>\n  <MachTable edit-type=\"fullRow\" :column-defs=\"columns\" :row-data=\"rows\" />\n</template>\n```\n\nCell mode is the default and provides a pencil plus inline confirm/cancel controls. Set `editable-indicator=\"always\"`, `\"hover\"` or `\"none\"` to control the affordance.\n\nDocumentation: [Vue guide](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/guide/vue.md) · [Enterprise integration](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/guide/enterprise-integration.md) · [Element Plus](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/guide/element-plus.md) · [Naive UI](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/guide/naive-ui.md)\n\nSource-available © ChenyCHENYU (Agile Team). Any use requires prior written authorization. See the [license](https://github.com/ChenyCHENYU/MachTable/blob/main/LICENSE) and [authorization process](https://github.com/ChenyCHENYU/MachTable/blob/main/LICENSING.md).\n"
 }