@colixsystems/widget-sdk 0.1.0 → 0.2.0

package/README.md

@@ -6,7 +6,7 @@ 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.2.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**.
 
 ## Public API
 

package/dist/index.d.ts

@@ -118,15 +118,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.2.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",