@colixsystems/widget-sdk 0.1.0 → 0.3.0

package/README.md

@@ -6,7 +6,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.1.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.3.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.3.0
+
+Additive: `WidgetManifest` now carries an optional `datastoreTemplate` field. When a tenant installs a widget that declares one, the table set is seeded into their workspace alongside the install. Tables follow the existing built-in template semantics (auto-suffixed naming, REQ-ACL-05 creator-grants, REQ-TEMPLATES-ACL public grants, REQ-ACL-RELINHERIT cross-relation inheritance) and persist when the widget is later uninstalled. See `WidgetDatastoreTemplate` in `src/index.d.ts` for the structural constraints — at most 8 tables per widget, 24 columns per table, RELATION columns address siblings by `suffix`.
 
 ## Public API
 

package/dist/index.d.ts

@@ -54,6 +54,71 @@ export interface WidgetEventDescriptor {
   payloadSchema?: WidgetPropertySchema;
 }
 
+/**
+ * Optional datastore template a widget can ship in its manifest. When the
+ * tenant installs the widget, every declared table is created in their
+ * workspace alongside the WidgetInstallation row, named
+ * `<widgetDisplayName>_<suffix>` (auto-suffixed `_2`/`_3`/... on name
+ * collisions). The tables persist when the widget is uninstalled — the
+ * tenant may have authored records into them.
+ *
+ * The shape mirrors the built-in template registry on the backend, with
+ * two limits a third-party widget must satisfy (enforced at submission
+ * time by the static analyzer):
+ *
+ *   - At most 8 tables per widget. Templates exist to seed schema, not
+ *     to be a full database design tool.
+ *   - At most 24 columns per table. Same reason.
+ *
+ * RELATION columns reference siblings within the same template via
+ * `targetSuffix` — that suffix MUST belong to a table declared earlier
+ * in the array. There is intentionally no way to reference a table
+ * outside the widget's own template.
+ */
+export interface WidgetDatastoreTemplateColumn {
+  name: string;
+  dataType:
+    | "STRING"
+    | "TEXT"
+    | "NUMBER"
+    | "FLOAT"
+    | "BOOL"
+    | "DATE"
+    | "FILE"
+    | "STRING_ARRAY"
+    | "INT_ARRAY"
+    | "RELATION"
+    | "USER"
+    | "USER_GROUP";
+  required?: boolean;
+  /** For RELATION columns only — points at a sibling table's `suffix`. */
+  targetSuffix?: string;
+  /** For RELATION columns only. */
+  relationType?: "ONE_TO_ONE" | "ONE_TO_MANY" | "MANY_TO_MANY";
+  /** REQ-ACL-RELINHERIT: opt this RELATION column into row-level ACL inheritance. */
+  inheritAcl?: boolean;
+}
+
+export interface WidgetDatastoreTemplateTable {
+  /** Stable identifier within the template; appears in the created table name. */
+  suffix: string;
+  /** REQ-ACL-05: when true, the row creator gets full RWD+G on the new record. */
+  grantCreatorPermissions?: boolean;
+  /**
+   * REQ-TEMPLATES-ACL: optional table-level public grant. Omitted means
+   * the table starts purely per-record (record-level grants are the only
+   * access path). canRead opens reads to everyone (including anonymous);
+   * canWrite only lets authenticated APP_USERs insert; canDelete remains
+   * studio-owner only regardless.
+   */
+  publicGrant?: { canRead?: boolean; canWrite?: boolean; canDelete?: boolean };
+  columns: WidgetDatastoreTemplateColumn[];
+}
+
+export interface WidgetDatastoreTemplate {
+  tables: WidgetDatastoreTemplateTable[];
+}
+
 export interface WidgetManifest {
   id: string;
   name: string;
@@ -67,6 +132,14 @@ export interface WidgetManifest {
   requestedScopes: WidgetScope[];
   propertySchema: WidgetPropertySchema;
   events: WidgetEventDescriptor[];
+  /**
+   * Optional datastore template seeded into the tenant's workspace when
+   * the widget is installed. The author wires the resulting tables into
+   * the widget's `tableRef` properties via the Properties Panel — the
+   * SDK does not auto-bind them. See `WidgetDatastoreTemplate` for the
+   * structural constraints enforced at submission time.
+   */
+  datastoreTemplate?: WidgetDatastoreTemplate;
 }
 
 export interface ThemeTokens {
@@ -118,15 +191,38 @@ export interface WidgetContext<TProps = unknown> {
   };
 }
 
-export interface WidgetModule<TProps = unknown> {
+/**
+ * The widget's component receives the author-authored props **as React
+ * props** — the same shape and calling convention every built-in widget
+ * uses (`<MetricWidget tableId={...} sumField={...} />`). Everything
+ * else from `WidgetContext` (datastore, user, workspace, navigation,
+ * i18n, …) is reachable via the SDK hooks (`useDatastoreMutation`,
+ * `useDatastoreQuery`, `useTheme`, `useI18n`, `useWidgetEvent`), which
+ * read from the host-mounted `WidgetContextProvider`.
+ *
+ *   function Counter({ tableId }) {            // ← props
+ *     const mut = useDatastoreMutation(tableId); // ← rest via hook
+ *     const { t } = useI18n();
+ *     return ...;
+ *   }
+ *
+ * Note: earlier versions of this typing passed the entire
+ * `WidgetContext` as the first argument. That was changed to the props-
+ * spread form so marketplace widgets follow the same interface as
+ * built-ins. Widgets that previously did `function Widget(ctx) { const
+ * { table } = ctx.props; }` should rewrite to
+ * `function Widget({ table }) { … }` and reach for hooks for anything
+ * else they need.
+ */
+export interface WidgetModule<TProps = Record<string, unknown>> {
   manifest: WidgetManifest;
-  component: (ctx: WidgetContext<TProps>) => JSX.Element;
+  component: (props: TProps) => JSX.Element;
   _kind: "appstudio-widget-module";
 }
 
-export function defineWidget<TProps = unknown>(opts: {
+export function defineWidget<TProps = Record<string, unknown>>(opts: {
   manifest: WidgetManifest;
-  component: (ctx: WidgetContext<TProps>) => JSX.Element;
+  component: (props: TProps) => JSX.Element;
 }): WidgetModule<TProps>;
 
 export function validateManifest(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",