@bemaestro/views 0.0.2

package/LICENSE

@@ -0,0 +1,193 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the
+      purposes of this License, Derivative Works shall not include works
+      that remain separable from, or merely link (or bind by name) to the
+      interfaces of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright
+      owner or by an individual or Legal Entity authorized to submit on
+      behalf of the copyright owner. For the purposes of this definition,
+      "submitted" means any form of electronic, verbal, or written
+      communication sent to the Licensor or its representatives, including
+      but not limited to communication on electronic mailing lists, source
+      code control systems, and issue tracking systems that are managed by,
+      or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or otherwise designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing
+      the origin of the Work and reproducing the content of the NOTICE
+      file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this
+      License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 BeMaestro
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,45 @@
+# @bemaestro/views
+
+Vue 3 renderers that turn a Maestro Core `view` (table/detail/form/calendar/kanban/gallery/dashboard,
+spec 17) into a working screen driven entirely by the meta-model — no per-app UI code required.
+
+## Install
+
+```sh
+npm install @bemaestro/views
+```
+
+This package ships raw `.vue`/`.ts` **source**, not a pre-built bundle — your bundler compiles it
+like any workspace file. With Vite, exclude it from dependency pre-bundling so `@vitejs/plugin-vue`
+processes its `.vue` files:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [vue()],
+  optimizeDeps: { exclude: ['@bemaestro/views'] },
+});
+```
+
+(`create-maestro-app` scaffolds this automatically.)
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { ViewRenderer } from '@bemaestro/views';
+import '@bemaestro/views/styles.css';
+</script>
+
+<template>
+  <ViewRenderer :client="client" :view="view" />
+</template>
+```
+
+Individual renderers (`TableView`, `DetailView`, `FormView`, `CalendarView`, `KanbanView`,
+`GalleryView`, `DashboardView`) are exported directly for consumers that want to mount one without
+the dispatcher. Peer deps: `vue`, `@lucide/vue`, `date-fns`.
+
+## License
+
+UNLICENSED — proprietary, part of the Maestro Core platform.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@bemaestro/views",
+  "version": "0.0.2",
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": [
+    "src",
+    "!src/**/*.spec.ts",
+    "!src/**/*.test.ts"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./styles.css": "./src/styles.css"
+  },
+  "dependencies": {
+    "@tiptap/core": "^3.28.0",
+    "@tiptap/extension-image": "^3.28.0",
+    "@tiptap/extension-placeholder": "^3.28.0",
+    "@tiptap/extension-table": "^3.28.0",
+    "@tiptap/pm": "^3.28.0",
+    "@tiptap/starter-kit": "^3.28.0",
+    "@tiptap/vue-3": "^3.28.0",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.5.0",
+    "@bemaestro/sdk": "0.1.0"
+  },
+  "peerDependencies": {
+    "@lucide/vue": "^1.23.0",
+    "date-fns": "^4.1.0",
+    "vue": "^3.5.25"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@lucide/vue": "^1.23.0",
+    "@vitejs/plugin-vue": "^6.0.1",
+    "@vue/test-utils": "^2.4.11",
+    "@vue/tsconfig": "^0.8.1",
+    "date-fns": "^4.1.0",
+    "eslint": "^10.2.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-vue": "^10.6.0",
+    "globals": "^17.7.0",
+    "jsdom": "^29.1.1",
+    "typescript": "~5.8.3",
+    "typescript-eslint": "^8.62.1",
+    "vitest": "^4.1.9",
+    "vue": "^3.5.25",
+    "vue-tsc": "^3.1.1"
+  },
+  "scripts": {
+    "typecheck": "vue-tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}

package/src/ViewRenderer.vue

@@ -0,0 +1,47 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { MaestroClient, RuntimeView } from '@bemaestro/sdk/runtime'
+import TableView from './renderers/TableView.vue'
+import CalendarView from './renderers/CalendarView.vue'
+import KanbanView from './renderers/KanbanView.vue'
+import GalleryView from './renderers/GalleryView.vue'
+import DetailView from './renderers/DetailView.vue'
+import FormView from './renderers/FormView.vue'
+import DashboardView from './renderers/DashboardView.vue'
+import StateMessage from './primitives/StateMessage.vue'
+
+const props = defineProps<{ view: RuntimeView; client: MaestroClient }>()
+
+// Single dispatch point: a surface's nav entry maps to a view type, each with
+// its own generic renderer (spec 17 — no per-app custom code).
+const component = computed(() => {
+  switch (props.view.type) {
+    case 'table':
+      return TableView
+    case 'calendar':
+      return CalendarView
+    case 'kanban':
+      return KanbanView
+    case 'gallery':
+      return GalleryView
+    case 'detail':
+      return DetailView
+    case 'form':
+      return FormView
+    case 'dashboard':
+      return DashboardView
+    default:
+      return null
+  }
+})
+</script>
+
+<template>
+  <component :is="component" v-if="component" :view="view" :client="client" />
+  <StateMessage
+    v-else
+    variant="error"
+    title="Unknown view type"
+    :description="`No renderer for '${view.type}'.`"
+  />
+</template>

package/src/composables/use-view-data.ts

@@ -0,0 +1,53 @@
+import { ref, shallowRef, watch, type Ref } from 'vue';
+import type { ListParams, MaestroClient } from '@bemaestro/sdk/runtime';
+
+export type DataRecord = Record<string, unknown>;
+
+export interface UseViewDataOptions {
+  /** Collection to read via the Data API; when null the view reads nothing. */
+  collectionKey: Ref<string | null | undefined>;
+  /** Query params (filter/sort/fields/search/window). Re-fetches on change. */
+  params: Ref<ListParams>;
+}
+
+/**
+ * Reactive reader over the Data API for a view (spec 17): server-side paging
+ * only — the renderer passes the visible window/params, never loads a whole
+ * collection. Kept free of vue-query so the package has no data-layer peer.
+ */
+export function useViewData(client: MaestroClient, options: UseViewDataOptions) {
+  const rows = shallowRef<DataRecord[]>([]);
+  const total = ref<number | null>(null);
+  const loading = ref(false);
+  const error = ref<Error | null>(null);
+  let seq = 0;
+
+  async function reload() {
+    const collectionKey = options.collectionKey.value;
+    if (!collectionKey) {
+      rows.value = [];
+      total.value = null;
+      return;
+    }
+    const current = ++seq;
+    loading.value = true;
+    error.value = null;
+    try {
+      const res = await client.collection<DataRecord>(collectionKey).list(options.params.value);
+      // Drop a response that a newer request has superseded (avoids flicker).
+      if (current !== seq) return;
+      rows.value = res.data;
+      total.value = res.meta?.total ?? null;
+    } catch (err) {
+      if (current !== seq) return;
+      error.value = err instanceof Error ? err : new Error(String(err));
+      rows.value = [];
+    } finally {
+      if (current === seq) loading.value = false;
+    }
+  }
+
+  watch([options.collectionKey, options.params], reload, { immediate: true, deep: true });
+
+  return { rows, total, loading, error, reload };
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+export { cn } from './lib/cn.js';
+export { formatValue, humanizeKey, recordLabel } from './lib/format.js';
+export { checkViewBinding, type BindingCheck } from './lib/view-binding.js';
+export {
+  useViewData,
+  type DataRecord,
+  type UseViewDataOptions,
+} from './composables/use-view-data.js';
+
+// The dispatcher is the main entry point; individual renderers are exported for
+// consumers that want to mount one directly (e.g. a detail page by id).
+export { default as ViewRenderer } from './ViewRenderer.vue';
+export { default as RichTextField } from './primitives/RichTextField.vue';
+export { default as TableView } from './renderers/TableView.vue';
+export { default as CalendarView } from './renderers/CalendarView.vue';
+export { default as KanbanView } from './renderers/KanbanView.vue';
+export { default as GalleryView } from './renderers/GalleryView.vue';
+export { default as DetailView } from './renderers/DetailView.vue';
+export { default as FormView } from './renderers/FormView.vue';
+export { default as DashboardView } from './renderers/DashboardView.vue';
+
+// Re-export the runtime view/surface contract so consumers get one import site.
+export type {
+  RuntimeResponse,
+  RuntimeSurface,
+  RuntimeView,
+  SurfaceNavEntry,
+  ViewType,
+} from '@bemaestro/sdk/runtime';

package/src/lib/cn.ts

@@ -0,0 +1,7 @@
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+/** Tailwind-aware className combiner (shadcn convention). */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/lib/format.ts

@@ -0,0 +1,31 @@
+/** Human-friendly rendering of a raw Data API value (spec 17 renderers). */
+export function formatValue(value: unknown): string {
+  if (value === null || value === undefined) return '—';
+  if (typeof value === 'boolean') return value ? 'Yes' : 'No';
+  if (value instanceof Date) return value.toLocaleString();
+  if (typeof value === 'string') {
+    // ISO date/datetime → locale string; leave other strings untouched.
+    if (/^\d{4}-\d{2}-\d{2}(T|\s)/.test(value)) {
+      const d = new Date(value);
+      if (!Number.isNaN(d.getTime())) return d.toLocaleString();
+    }
+    return value;
+  }
+  if (typeof value === 'number') return String(value);
+  return JSON.stringify(value);
+}
+
+/** Turn a field key into a readable label: `starts_at` → `Starts at`. */
+export function humanizeKey(key: string): string {
+  const spaced = key.replace(/[_-]+/g, ' ').trim();
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+/** Best-effort label for a record (title binding, else name/title/id field). */
+export function recordLabel(record: Record<string, unknown>, titleField?: string): string {
+  if (titleField && record[titleField] != null) return formatValue(record[titleField]);
+  for (const k of ['name', 'title', 'label']) {
+    if (record[k] != null) return formatValue(record[k]);
+  }
+  return record.id != null ? String(record.id) : '—';
+}

package/src/lib/view-binding.ts

@@ -0,0 +1,40 @@
+import type { RuntimeView, ViewType } from '@bemaestro/sdk/runtime';
+
+/**
+ * Config keys each view type needs to render (mirrors the server's
+ * VIEW_FIELD_BINDINGS, spec 17 US-17.1). The server validates types at write
+ * time; here we only guard against a dangling/misconfigured view at load so it
+ * renders a clear message instead of crashing (spec 17 edge cases).
+ */
+const REQUIRED_CONFIG: Partial<Record<ViewType, string[]>> = {
+  calendar: ['dateField', 'titleField'],
+  kanban: ['groupField', 'titleField'],
+  gallery: ['imageField', 'titleField'],
+};
+
+const NEEDS_COLLECTION: ViewType[] = ['table', 'calendar', 'kanban', 'gallery', 'detail', 'form'];
+
+export interface BindingCheck {
+  ok: boolean;
+  reason?: string;
+}
+
+export function checkViewBinding(view: RuntimeView): BindingCheck {
+  if (NEEDS_COLLECTION.includes(view.type) && !view.collectionKey) {
+    return { ok: false, reason: `${view.type} view is not bound to a collection` };
+  }
+  const required = REQUIRED_CONFIG[view.type] ?? [];
+  const missing = required.filter((k) => {
+    const v = (view.config as Record<string, unknown>)[k];
+    return v === undefined || v === null || v === '';
+  });
+  if (missing.length > 0) {
+    return { ok: false, reason: `missing config: ${missing.join(', ')}` };
+  }
+  return { ok: true };
+}
+
+export function configString(view: RuntimeView, key: string): string | undefined {
+  const v = (view.config as Record<string, unknown>)[key];
+  return typeof v === 'string' ? v : undefined;
+}

package/src/primitives/Badge.vue

@@ -0,0 +1,34 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { cn } from '../lib/cn.js'
+
+const props = defineProps<{ class?: string; color?: string }>()
+
+// Optional stable hue derived from an enum value (calendar/kanban color coding).
+const style = computed(() =>
+  props.color
+    ? { backgroundColor: `var(--maestro-badge-bg, hsl(${hashHue(props.color)} 70% 92%))` }
+    : undefined,
+)
+
+function hashHue(value: string): number {
+  let h = 0
+  for (let i = 0; i < value.length; i++) h = (h * 31 + value.charCodeAt(i)) % 360
+  return h
+}
+</script>
+
+<template>
+  <span
+    :class="
+      cn(
+        'inline-flex items-center rounded-md border px-2 py-0.5 text-xs font-medium',
+        !props.color && 'bg-secondary text-secondary-foreground',
+        $props.class,
+      )
+    "
+    :style="style"
+  >
+    <slot />
+  </span>
+</template>

package/src/primitives/Card.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+import { cn } from '../lib/cn.js'
+
+defineProps<{ class?: string }>()
+</script>
+
+<template>
+  <div :class="cn('rounded-lg border bg-card text-card-foreground shadow-sm', $props.class)">
+    <slot />
+  </div>
+</template>