@paged-media/plugin-api 0.2.43-canary.0 → 0.2.46-canary.0

package/dist/panel-schema.d.ts

@@ -1,5 +1,6 @@
 import type { ComponentType } from "react";
 import type { BindingsSurface } from "./host";
+import type { Address, PropertyPathName, Selector } from "./object-model";
 import type { PropertyPath, Value } from "./wire";
 export type WidgetValueBinding = {
     kind: "literal";
@@ -90,7 +91,113 @@ export interface SchemaListSpec {
     /** Per-row action buttons. */
     actions?: SchemaListAction[];
 }
-export interface PanelSchemaRow {
+/**
+ * Which object(s) a property row edits.
+ *   · `"selection"` — the selected objects. With `kind` set, the objects of
+ *     that kind HOSTED by each selected object (`<selected> > <kind>`):
+ *     the web frame of a selected text frame, the layers of a selected
+ *     image frame.
+ *   · a selector string (ADR 131) — every address it selects, re-resolved
+ *     when the object model changes. Also the durable "Bind to data…"
+ *     target, so prefer a name/label selector over a raw session address.
+ *   · `{ bind }` — an address, or a list of addresses, the plugin publishes
+ *     through `host.bindings.publish(name, …)` (its active layer, the cell
+ *     under the cursor). Absent / empty = no target (the field disables).
+ *   · `{ addresses }` — explicit addresses, as given.
+ */
+export type PropertyFieldAddress = "selection" | Selector | {
+    bind: string;
+} | {
+    addresses: readonly Address[];
+};
+/** How a property row presents an `enum` (or a text row offering a
+ *  collection): the host picks from the schema row otherwise. */
+export type PropertyFieldStyle = "select" | "segments" | "collection";
+/** One option override for a `select` / `segments` presentation (labels
+ *  for enum members; the member list still comes from the schema). */
+export interface PropertyFieldOption {
+    value: string;
+    label?: string;
+    icon?: string;
+}
+/** One sub-field a property row shows of a STRUCT value (or of each
+ *  struct item of a list): `field` is the struct field's name; the widget
+ *  comes from that field's value type, like a row's comes from its schema
+ *  row. A bare string is `{ field }`. */
+export interface PropertySubField {
+    field: string;
+    label?: string;
+    style?: PropertyFieldStyle;
+    options?: readonly PropertyFieldOption[];
+    /** Leaf chrome passthrough. */
+    props?: Record<string, unknown>;
+}
+/**
+ * How a property row presents a LIST value (`{ kind: "list", of }`): an
+ * appearance stack's fills, a gradient's stops. Every edit the host
+ * offers is a {@link ListEdit} the SDK lowers to `set` ops (one batch, one
+ * undo step) — `planValueEdit` / `editValue` in plugin-sdk.
+ */
+export interface PropertyListPresentation {
+    /** Struct items: the fields each item shows, in order. Absent = every
+     *  declared field of the item struct. Scalar items show one widget. */
+    fields?: readonly (string | PropertySubField)[];
+    /** The item field whose value titles an item (`name`, `stopColor`). */
+    itemLabel?: string;
+    /** Offer add / remove / reorder. Each defaults to `true` on a
+     *  read-write row; `add` also stops at the type's `maxItems`. */
+    add?: boolean;
+    remove?: boolean;
+    reorder?: boolean;
+    /** List the LAST item first (a stack painted bottom → top reads
+     *  top-first, like a layers panel). Indices in the edits stay value
+     *  indices. Default `false`. */
+    reversed?: boolean;
+    /** The item `add` inserts. Absent = the item type's default
+     *  (`defaultValueOf`: struct field defaults, the first enum member,
+     *  0, "", false, []). Must satisfy the item type. */
+    newItem?: unknown;
+}
+/** The property row (the property row). Mutually exclusive with `widget`: a
+ *  row is EITHER a catalog widget OR an object-model property field. */
+export interface PanelSchemaPropertyRow {
+    field: "property";
+    /** The object(s) the field edits — see {@link PropertyFieldAddress}. */
+    address: PropertyFieldAddress;
+    /** The ADR 132 path on the target's kind (`opacity`, `blendMode`,
+     *  `points[0].anchor`). */
+    path: PropertyPathName;
+    /** The qualified kind (`plugin:<id>/<kind>`, or a core kind) whose
+     *  schema row types the field. Required with `address: "selection"`
+     *  for plugin objects (it scopes the selection to that kind); otherwise
+     *  it lets the field show its widget before any target resolves. */
+    kind?: string;
+    /** Row label (sentence case). Absent = the schema row's `title`, then
+     *  the path. */
+    label?: string;
+    style?: PropertyFieldStyle;
+    options?: readonly PropertyFieldOption[];
+    /** Offer "Bind to data…" (default: when the schema row is bindable). */
+    bindable?: boolean;
+    /** A STRUCT-typed path: the fields to show, in order (absent = every
+     *  declared field; an `open` struct with no `fields` shows none and
+     *  falls back to its JSON text). Edits are {@link StructEdit}s. */
+    fields?: readonly (string | PropertySubField)[];
+    /** A LIST-typed path: how its items present and which edits are
+     *  offered. Absent = the defaults of {@link PropertyListPresentation}. */
+    items?: PropertyListPresentation;
+    /** Leaf chrome passthrough (placeholder, prefix, suffix, icon, …). */
+    props?: Record<string, unknown>;
+    visible?: SchemaGate;
+    enabled?: SchemaGate;
+    /** Never set on a property row (keeps `row.widget` readable on the
+     *  union). */
+    widget?: undefined;
+    value?: undefined;
+    list?: undefined;
+}
+/** The catalog-widget row (schema v1 / v1.1). */
+export interface PanelSchemaWidgetRow {
     /** Catalog widget id (a curated primitive-leaf id the host
      *  registered). An unknown id renders a visible "unknown widget"
      *  placeholder, not a throw. */
@@ -112,7 +219,12 @@ export interface PanelSchemaRow {
      *  always enabled (subject to the widget's own no-write-path
      *  disable). */
     enabled?: SchemaGate;
+    /** Never set on a widget row. */
+    field?: undefined;
 }
+/** One panel row: a catalog widget, or an object-model property
+ *  field. Discriminate with `isPropertyRow` (plugin-sdk) or `row.field`. */
+export type PanelSchemaRow = PanelSchemaWidgetRow | PanelSchemaPropertyRow;
 export interface PanelSchemaSection {
     /** Section title (the kicker / disclosure header). Absent = an
      *  untitled flat group. */

package/dist/widgets.d.ts

@@ -1,4 +1,6 @@
-import type { ComponentType } from "react";
+import type { ComponentType, ReactNode } from "react";
+import type { Address, PropertyPathName, Selector } from "./object-model";
+import type { PropertyFieldOption, PropertyFieldStyle, PropertyListPresentation, PropertySubField } from "./panel-schema";
 /** Languages the host code editor highlights. `text` = no
  *  highlighting (line numbers + gutter only). Additive: a host MAY
  *  accept more, but only these are contract-guaranteed. */
@@ -51,6 +53,59 @@ export interface WidgetSurface {
      *  `<input type="color">` fallback stands in when the host injects
      *  none (probe `host.supports("widgets.colorPicker@1")`). */
     readonly ColorPicker: ComponentType<ColorPickerProps>;
+    /** ADR 323 — the host's ONE schema-driven property field, for bundles
+     *  that render their own React panel: the same field a schema panel's
+     *  `{ field: "property" }` row renders (widget from the schema row,
+     *  reads/writes through `host.objects`, one undo step per commit, "Bind
+     *  to data…" and the bound badge). OPTIONAL: absent on a host without
+     *  an object-model UI — probe the member (or
+     *  `host.supports("widgets.propertyField@1")`) and keep your own control
+     *  as the fallback. */
+    readonly PropertyField?: ComponentType<PropertyFieldProps>;
+    /** ADR 323 — the field CHROME without a widget, around a control the
+     *  bundle keeps on purpose (a curve editor, a gradient strip): the
+     *  host's verdict hooks, "Bind to data…" on right-click and the badges.
+     *  The bundle's control still writes through its own door; the frame
+     *  only names the object property it edits. OPTIONAL like
+     *  `PropertyField`. */
+    readonly PropertyFrame?: ComponentType<PropertyFrameProps>;
+}
+/** Which object(s) a React property field edits: the selection (scoped to
+ *  `kind` when given), a selector, or explicit addresses. (A schema row
+ *  can also name a published binding; a React panel has its state at hand
+ *  and passes the addresses.) */
+export type PropertyFieldTarget = "selection" | Selector | {
+    addresses: readonly Address[];
+};
+/** Props of {@link WidgetSurface.PropertyField}. */
+export interface PropertyFieldProps {
+    address: PropertyFieldTarget;
+    path: PropertyPathName;
+    /** Qualified kind (`plugin:<id>/<kind>`) — see `PanelSchemaPropertyRow.kind`. */
+    kind?: string;
+    label?: string;
+    style?: PropertyFieldStyle;
+    options?: readonly PropertyFieldOption[];
+    bindable?: boolean;
+    disabled?: boolean;
+    /** A struct-typed path: the fields shown (see
+     *  `PanelSchemaPropertyRow.fields`). Needs
+     *  `host.supports("widgets.propertyField.values@1")`. */
+    fields?: readonly (string | PropertySubField)[];
+    /** A list-typed path: item presentation and the offered edits (see
+     *  `PanelSchemaPropertyRow.items`). Needs
+     *  `host.supports("widgets.propertyField.values@1")`. */
+    items?: PropertyListPresentation;
+    /** Leaf chrome passthrough (placeholder, prefix, suffix, icon, …). */
+    props?: Record<string, unknown>;
+}
+/** Props of {@link WidgetSurface.PropertyFrame}. */
+export interface PropertyFrameProps {
+    address: PropertyFieldTarget;
+    path: PropertyPathName;
+    kind?: string;
+    bindable?: boolean;
+    children: ReactNode;
 }
 /** Props of {@link WidgetSurface.ColorPicker}. Colours are sRGB hex. */
 export interface ColorPickerProps {