@paged-media/plugin-api 0.2.27-canary.1 → 0.2.29-canary.0

package/dist/panel-schema.d.ts

@@ -25,6 +25,71 @@ export interface BindingRef {
  *  (and a missing name reads as `false` — a visible seam, never a
  *  throw). */
 export type SchemaGate = boolean | BindingRef;
+/** Where a `list` row's items come from. Two sources, mirroring the
+ *  two live-collection lanes the host already has:
+ *    · `documentCollection` — a named engine collection (the same
+ *      `host.document.collection(name)` lane the editor's own panels
+ *      read);
+ *    · `binding` — an ARRAY the plugin publishes through
+ *      `host.bindings.publish(name, rows)` (the §12.2 published-
+ *      bindings door, now carrying rows instead of a boolean). */
+export type WidgetCollectionBinding = {
+    kind: "documentCollection";
+    collection: string;
+} | {
+    kind: "binding";
+    bind: string;
+};
+/** G3 — a schema row ACTION. Either dispatches a registered command
+ *  with the row id as payload, or the `applyEntity` write kind: apply
+ *  the row's entity id (style / swatch self-id) to the current
+ *  selection through the SAME `setElementProperty` mutation channel the
+ *  scalar widgets commit on. `valueType` picks the wire payload
+ *  (`text` for applied-style paths, `colorRef` for swatch/gradient
+ *  paths) — the collection-select leaf's convention. Note the ceiling
+ *  holds: an action writes ONE typed PropertyPath, it does not compute. */
+export type SchemaRowAction = {
+    kind: "command";
+    command: string;
+} | {
+    kind: "applyEntity";
+    /** Selection surface to write to (defaults to `"element"`). */
+    scope?: "element" | "content";
+    /** The applied-entity PropertyPath (e.g. `frameFillColor`,
+     *  `appliedParagraphStyle`). */
+    path: PropertyPath;
+    /** Wire payload variant; defaults to `"text"`. */
+    valueType?: "text" | "colorRef";
+};
+/** One per-row action button on a `list` widget. */
+export interface SchemaListAction {
+    /** Button label (sentence case, no emoji — brand content rules). */
+    label: string;
+    action: SchemaRowAction;
+    /** Gate the button on a published binding (absent = enabled;
+     *  `applyEntity` actions additionally disable while the target
+     *  selection is empty — the honest no-write-path rule). */
+    enabled?: SchemaGate;
+}
+/** The `list` widget spec (widget id `paged.list`). Renders rows from a
+ *  collection binding; publishes the clicked row's id back through
+ *  `selectionBinding` so other rows/sections can gate on it — which is
+ *  how a list participates in §12.2 without a DSL. */
+export interface SchemaListSpec {
+    items: WidgetCollectionBinding;
+    /** Dot-path into a row object for the primary label ("name"). */
+    labelField: string;
+    /** Optional secondary line (mono), e.g. "kind". */
+    secondaryField?: string;
+    /** Dot-path carrying the row's stable id; defaults to "selfId" (the
+     *  summary-shape convention every document collection uses). */
+    idField?: string;
+    /** Published binding name that receives the selected row id on click
+     *  (string). Absent = the list keeps private selection. */
+    selectionBinding?: string;
+    /** Per-row action buttons. */
+    actions?: SchemaListAction[];
+}
 export interface PanelSchemaRow {
     /** Catalog widget id (a curated primitive-leaf id the host
      *  registered). An unknown id renders a visible "unknown widget"
@@ -38,6 +103,9 @@ export interface PanelSchemaRow {
      *  (`literal | selectionProperty`). Absent = a layout-only / display
      *  leaf (label, section). */
     value?: WidgetValueBinding;
+    /** ADDITIVE (schema v1.1) — present iff `widget` is the list widget
+     *  (`paged.list`). Scalar rows ignore it; a v1 schema never sets it. */
+    list?: SchemaListSpec;
     /** Show the row only when this gate is truthy. Absent = always. */
     visible?: SchemaGate;
     /** Enable the row's control only when this gate is truthy. Absent =