@pylonsync/sdk 0.3.360 → 0.3.362

package/dist/studio.d.ts

@@ -211,12 +211,69 @@ export interface BulkAction {
     /** Hide unless viewer is_admin. */
     requiresAdmin?: boolean;
 }
+/**
+ * A control attached to every row.
+ *
+ * `kind: "action"` is the one that calls back into your app: Studio POSTs
+ * `/api/fn/<action>` with `input`, then shows the result. Pair it with
+ * `display: "button"` for a control that sits in the row instead of behind
+ * the `…` menu.
+ *
+ * @example Generate a share link for a proposal and copy it
+ * ```ts
+ * rowActions: [
+ *   {
+ *     id: "generateLink",
+ *     label: "Generate link",
+ *     icon: "link",
+ *     kind: "action",
+ *     display: "button",
+ *     action: "generateProposalLink",
+ *     input: { proposalId: "{row.id}" },
+ *     result: "copy",
+ *     resultField: "url",
+ *   },
+ * ]
+ * ```
+ */
 export interface RowAction {
     id: string;
     label: string;
     icon?: IconName;
-    kind?: "delete" | "edit" | "view" | "custom";
+    /**
+     * `delete` / `edit` / `view` are built in. `action` calls a server
+     * function. `custom` is resolved against `studio.entry.tsx`.
+     */
+    kind?: "delete" | "edit" | "view" | "action" | "custom";
+    /**
+     * Where the control renders. `"button"` puts it in the row; `"menu"`
+     * (the default) puts it behind the trailing `…` menu.
+     */
+    display?: "menu" | "button";
+    /** Function name for `kind: "action"`. POSTed to `/api/fn/<action>`. */
+    action?: string;
+    /**
+     * Argument object for `kind: "action"`. String values interpolate
+     * `{row.<field>}` — a value that is exactly one placeholder keeps the
+     * row value's type, so `"{row.count}"` sends a number. Defaults to
+     * `{ id: <row id> }`.
+     */
+    input?: Record<string, unknown>;
+    /**
+     * What to do with the return value. `"toast"` (default) shows it,
+     * `"copy"` writes it to the clipboard, `"dialog"` opens it as JSON,
+     * `"none"` discards it.
+     */
+    result?: "toast" | "copy" | "dialog" | "none";
+    /** Dot path into the return value, for `result: "copy"` / `"toast"`. */
+    resultField?: string;
+    /** Reload the table after the action succeeds. Defaults to true. */
+    refresh?: boolean;
+    /** Button styling for `display: "button"`. Defaults to `"outline"`. */
+    variant?: "default" | "outline" | "ghost" | "secondary" | "destructive";
+    /** Confirmation dialog message. Shown before the action runs. */
     confirm?: string;
+    /** Hide unless viewer is_admin. */
     requiresAdmin?: boolean;
 }
 export interface ResourceListConfig {
@@ -270,18 +327,21 @@ export interface StudioConfig {
     hasExtensions?: boolean;
     /**
      * URL to send unauthenticated callers to when they hit `/studio`.
-     * Lets a host app (Pylon Cloud, an enterprise dashboard) point the
-     * Studio gate at its own email/password login page instead of the
-     * built-in `/studio/login` admin-token form.
      *
-     * The framework appends `?next=/studio` so the host app can redirect
-     * back after sign-in. Authenticated-but-not-admin users still see
-     * the framework's "access denied" page (no point sending them back
-     * to a login they're already past).
+     * Studio requires a signed-in user this app treats as an admin — via
+     * `auth.user.adminField` or the `PYLON_ADMIN_EMAILS` allowlist. It has no
+     * login page of its own, so point this at yours. Without it, an anonymous
+     * visitor gets a static page explaining how to designate an admin, because
+     * the framework has no login route it can safely assume you serve.
+     *
+     * The framework appends `?next=/studio` so the host app can redirect back
+     * after sign-in. Authenticated-but-not-admin users still see the
+     * framework's "access denied" page — no point sending them back to a login
+     * they're already past.
      *
-     * Example: `loginUrl: "/login"` — www.pylonsync.com handles `/login`
-     * at the dashboard, and the user's existing session cookie lifts
-     * them to admin via `auth.user.adminField` on the way back.
+     * Example: `loginUrl: "/login"` — www.pylonsync.com handles `/login` at the
+     * dashboard, and the user's existing session cookie lifts them to admin via
+     * `auth.user.adminField` on the way back.
      */
     loginUrl?: string;
 }

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.360",
+  "version": "0.3.362",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/studio.ts

@@ -283,12 +283,69 @@ export interface BulkAction {
   requiresAdmin?: boolean;
 }
 
+/**
+ * A control attached to every row.
+ *
+ * `kind: "action"` is the one that calls back into your app: Studio POSTs
+ * `/api/fn/<action>` with `input`, then shows the result. Pair it with
+ * `display: "button"` for a control that sits in the row instead of behind
+ * the `…` menu.
+ *
+ * @example Generate a share link for a proposal and copy it
+ * ```ts
+ * rowActions: [
+ *   {
+ *     id: "generateLink",
+ *     label: "Generate link",
+ *     icon: "link",
+ *     kind: "action",
+ *     display: "button",
+ *     action: "generateProposalLink",
+ *     input: { proposalId: "{row.id}" },
+ *     result: "copy",
+ *     resultField: "url",
+ *   },
+ * ]
+ * ```
+ */
 export interface RowAction {
   id: string;
   label: string;
   icon?: IconName;
-  kind?: "delete" | "edit" | "view" | "custom";
+  /**
+   * `delete` / `edit` / `view` are built in. `action` calls a server
+   * function. `custom` is resolved against `studio.entry.tsx`.
+   */
+  kind?: "delete" | "edit" | "view" | "action" | "custom";
+  /**
+   * Where the control renders. `"button"` puts it in the row; `"menu"`
+   * (the default) puts it behind the trailing `…` menu.
+   */
+  display?: "menu" | "button";
+  /** Function name for `kind: "action"`. POSTed to `/api/fn/<action>`. */
+  action?: string;
+  /**
+   * Argument object for `kind: "action"`. String values interpolate
+   * `{row.<field>}` — a value that is exactly one placeholder keeps the
+   * row value's type, so `"{row.count}"` sends a number. Defaults to
+   * `{ id: <row id> }`.
+   */
+  input?: Record<string, unknown>;
+  /**
+   * What to do with the return value. `"toast"` (default) shows it,
+   * `"copy"` writes it to the clipboard, `"dialog"` opens it as JSON,
+   * `"none"` discards it.
+   */
+  result?: "toast" | "copy" | "dialog" | "none";
+  /** Dot path into the return value, for `result: "copy"` / `"toast"`. */
+  resultField?: string;
+  /** Reload the table after the action succeeds. Defaults to true. */
+  refresh?: boolean;
+  /** Button styling for `display: "button"`. Defaults to `"outline"`. */
+  variant?: "default" | "outline" | "ghost" | "secondary" | "destructive";
+  /** Confirmation dialog message. Shown before the action runs. */
   confirm?: string;
+  /** Hide unless viewer is_admin. */
   requiresAdmin?: boolean;
 }
 
@@ -351,18 +408,21 @@ export interface StudioConfig {
   hasExtensions?: boolean;
   /**
    * URL to send unauthenticated callers to when they hit `/studio`.
-   * Lets a host app (Pylon Cloud, an enterprise dashboard) point the
-   * Studio gate at its own email/password login page instead of the
-   * built-in `/studio/login` admin-token form.
    *
-   * The framework appends `?next=/studio` so the host app can redirect
-   * back after sign-in. Authenticated-but-not-admin users still see
-   * the framework's "access denied" page (no point sending them back
-   * to a login they're already past).
+   * Studio requires a signed-in user this app treats as an admin — via
+   * `auth.user.adminField` or the `PYLON_ADMIN_EMAILS` allowlist. It has no
+   * login page of its own, so point this at yours. Without it, an anonymous
+   * visitor gets a static page explaining how to designate an admin, because
+   * the framework has no login route it can safely assume you serve.
+   *
+   * The framework appends `?next=/studio` so the host app can redirect back
+   * after sign-in. Authenticated-but-not-admin users still see the
+   * framework's "access denied" page — no point sending them back to a login
+   * they're already past.
    *
-   * Example: `loginUrl: "/login"` — www.pylonsync.com handles `/login`
-   * at the dashboard, and the user's existing session cookie lifts
-   * them to admin via `auth.user.adminField` on the way back.
+   * Example: `loginUrl: "/login"` — www.pylonsync.com handles `/login` at the
+   * dashboard, and the user's existing session cookie lifts them to admin via
+   * `auth.user.adminField` on the way back.
    */
   loginUrl?: string;
 }