@particle-academy/fancy-flow 0.33.0 → 0.33.2

package/dist/index.d.cts

@@ -391,6 +391,17 @@ type ConfigFieldRendererProps = {
     field: ConfigField;
     value: unknown;
     onChange: (value: unknown) => void;
+    /**
+     * DOM id for the control this renders.
+     *
+     * Supplied by the caller rather than generated here so the panel's `<label>`
+     * can point at it — a label beside a control is not a label attached to one.
+     * Also the agent-facing handle: the Human+ contract asks that every
+     * interactive element have a stable identity so an agent targets it instead
+     * of guessing at the DOM, and until this existed nothing in the editor had
+     * one.
+     */
+    id?: string;
     renderCredentialField?: (props: {
         credentialType: string;
         value: unknown;
@@ -410,14 +421,17 @@ type ConfigFieldRendererProps = {
     }) => ReactNode;
 };
 /**
- * ConfigFieldRenderer — dispatches to the right input element per field
- * type. Plain HTML inputs styled via the package's CSS so the package
- * stays standalone (no react-fancy import required).
+ * ConfigFieldRenderer — dispatches to the right input element per field type.
+ *
+ * Plain HTML inputs styled via the package's CSS so the package stays
+ * standalone (no react-fancy import required) and every surface stays themeable
+ * through the `--ff-*` token layer. Hosts that want react-fancy form components
+ * can supply their own field renderers via the kind's `renderPanel`.
  *
- * Hosts that want to use react-fancy form components can supply their
- * own field renderers via the kind's `renderPanel`.
+ * Each control carries the caller's `id` and a `data-ff-field` handle keyed by
+ * the field, so a label can point at it and an agent can find it by name.
  */
-declare function ConfigFieldRenderer({ field, value, onChange, renderCredentialField, renderDocumentField, }: ConfigFieldRendererProps): react.JSX.Element | null;
+declare function ConfigFieldRenderer({ field, value, onChange, id, renderCredentialField, renderDocumentField, }: ConfigFieldRendererProps): react.JSX.Element | null;
 
 /** Entry-point node — outputs only, no inputs. */
 declare function TriggerNodeInner(props: NodeProps<FlowNode>): react.JSX.Element;

package/dist/index.d.ts

@@ -391,6 +391,17 @@ type ConfigFieldRendererProps = {
     field: ConfigField;
     value: unknown;
     onChange: (value: unknown) => void;
+    /**
+     * DOM id for the control this renders.
+     *
+     * Supplied by the caller rather than generated here so the panel's `<label>`
+     * can point at it — a label beside a control is not a label attached to one.
+     * Also the agent-facing handle: the Human+ contract asks that every
+     * interactive element have a stable identity so an agent targets it instead
+     * of guessing at the DOM, and until this existed nothing in the editor had
+     * one.
+     */
+    id?: string;
     renderCredentialField?: (props: {
         credentialType: string;
         value: unknown;
@@ -410,14 +421,17 @@ type ConfigFieldRendererProps = {
     }) => ReactNode;
 };
 /**
- * ConfigFieldRenderer — dispatches to the right input element per field
- * type. Plain HTML inputs styled via the package's CSS so the package
- * stays standalone (no react-fancy import required).
+ * ConfigFieldRenderer — dispatches to the right input element per field type.
+ *
+ * Plain HTML inputs styled via the package's CSS so the package stays
+ * standalone (no react-fancy import required) and every surface stays themeable
+ * through the `--ff-*` token layer. Hosts that want react-fancy form components
+ * can supply their own field renderers via the kind's `renderPanel`.
  *
- * Hosts that want to use react-fancy form components can supply their
- * own field renderers via the kind's `renderPanel`.
+ * Each control carries the caller's `id` and a `data-ff-field` handle keyed by
+ * the field, so a label can point at it and an agent can find it by name.
  */
-declare function ConfigFieldRenderer({ field, value, onChange, renderCredentialField, renderDocumentField, }: ConfigFieldRendererProps): react.JSX.Element | null;
+declare function ConfigFieldRenderer({ field, value, onChange, id, renderCredentialField, renderDocumentField, }: ConfigFieldRendererProps): react.JSX.Element | null;
 
 /** Entry-point node — outputs only, no inputs. */
 declare function TriggerNodeInner(props: NodeProps<FlowNode>): react.JSX.Element;

package/dist/index.js

@@ -14,7 +14,7 @@ import { onNodeKindsChanged, listNodeKinds, getNodeKind, defaultConfigFor, valid
 export { categoryAccent, defaultConfigFor, getNodeKind, listNodeKinds, onNodeKindsChanged, registerNodeKind, validateConfig } from './chunk-Q6IPK64P.js';
 import { getRichInputAdapter } from './chunk-F5RPRB7A.js';
 export { RichInputPreview, getRichInputAdapter, isRichInputEnabled, onRichInputAdapterChanged, registerRichInputAdapter } from './chunk-F5RPRB7A.js';
-import { memo, forwardRef, useState, useMemo, useEffect, useCallback, useRef, useImperativeHandle } from 'react';
+import { memo, forwardRef, useState, useMemo, useEffect, useCallback, useRef, useImperativeHandle, useId } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 
 function NodeShellInner({
@@ -565,9 +565,11 @@ function ConfigFieldRenderer({
   field,
   value,
   onChange,
+  id,
   renderCredentialField,
   renderDocumentField
 }) {
+  const handle = { id, "data-ff-field": field.key };
   switch (field.type) {
     case "text": {
       if (field.choices?.length) {
@@ -576,6 +578,7 @@ function ConfigFieldRenderer({
       return /* @__PURE__ */ jsx(
         "input",
         {
+          ...handle,
           className: "ff-panel__input",
           type: "text",
           value: value ?? "",
@@ -588,6 +591,7 @@ function ConfigFieldRenderer({
       return /* @__PURE__ */ jsx(
         "textarea",
         {
+          ...handle,
           className: "ff-panel__input ff-panel__input--textarea",
           rows: field.rows ?? 4,
           value: value ?? "",
@@ -599,6 +603,7 @@ function ConfigFieldRenderer({
       return /* @__PURE__ */ jsx(
         "input",
         {
+          ...handle,
           className: "ff-panel__input",
           type: "number",
           value: value ?? "",
@@ -613,6 +618,7 @@ function ConfigFieldRenderer({
         /* @__PURE__ */ jsx(
           "input",
           {
+            ...handle,
             type: "checkbox",
             checked: !!value,
             onChange: (e) => onChange(e.target.checked)
@@ -624,6 +630,7 @@ function ConfigFieldRenderer({
       return /* @__PURE__ */ jsxs(
         "select",
         {
+          ...handle,
           className: "ff-panel__input",
           value: value ?? "",
           onChange: (e) => onChange(e.target.value),
@@ -639,6 +646,7 @@ function ConfigFieldRenderer({
       return /* @__PURE__ */ jsx(
         "textarea",
         {
+          ...handle,
           className: "ff-panel__input ff-panel__input--expression",
           rows: 2,
           value: value ?? "",
@@ -939,15 +947,20 @@ function NodeConfigPanel({
   className,
   style
 }) {
+  const uid = useId();
+  const kindName = node ? node.data.kind ?? node.type : null;
+  const kind = useMemo(() => kindName ? getNodeKind(kindName) : void 0, [kindName]);
+  const config = useMemo(
+    () => node?.data?.config ?? {},
+    [node?.data]
+  );
+  const fieldId = (key) => `${uid}-${key}`;
   if (!node) {
     return /* @__PURE__ */ jsxs("aside", { className: ["ff-panel", "ff-panel--empty", className ?? ""].filter(Boolean).join(" "), style, children: [
       header,
       /* @__PURE__ */ jsx("p", { className: "ff-panel__empty", children: "Select a node to configure it." })
     ] });
   }
-  const kindName = node.data.kind ?? node.type;
-  const kind = useMemo(() => getNodeKind(kindName), [kindName]);
-  const config = useMemo(() => node.data.config ?? {}, [node.data]);
   if (!kind) {
     return /* @__PURE__ */ jsxs("aside", { className: ["ff-panel", className ?? ""].filter(Boolean).join(" "), style, children: [
       header,
@@ -988,10 +1001,12 @@ function NodeConfigPanel({
     ] }),
     kind.description && /* @__PURE__ */ jsx("p", { className: "ff-panel__kind-desc", children: kind.description }),
     /* @__PURE__ */ jsxs("div", { className: "ff-panel__field", children: [
-      /* @__PURE__ */ jsx("label", { className: "ff-panel__label", children: "Label" }),
+      /* @__PURE__ */ jsx("label", { className: "ff-panel__label", htmlFor: fieldId("label"), children: "Label" }),
       /* @__PURE__ */ jsx(
         "input",
         {
+          id: fieldId("label"),
+          "data-ff-field": "label",
           className: "ff-panel__input",
           value: node.data.label ?? "",
           onChange: (e) => setLabel(e.target.value),
@@ -1000,10 +1015,12 @@ function NodeConfigPanel({
       )
     ] }),
     /* @__PURE__ */ jsxs("div", { className: "ff-panel__field", children: [
-      /* @__PURE__ */ jsx("label", { className: "ff-panel__label", children: "Description" }),
+      /* @__PURE__ */ jsx("label", { className: "ff-panel__label", htmlFor: fieldId("description"), children: "Description" }),
       /* @__PURE__ */ jsx(
         "textarea",
         {
+          id: fieldId("description"),
+          "data-ff-field": "description",
           className: "ff-panel__input ff-panel__input--textarea",
           rows: 2,
           value: node.data.description ?? "",
@@ -1018,7 +1035,7 @@ function NodeConfigPanel({
     }) : /* @__PURE__ */ jsxs(Fragment, { children: [
       (kind.configSchema ?? []).length > 0 && /* @__PURE__ */ jsx("hr", { className: "ff-panel__divider" }),
       (kind.configSchema ?? []).map((field) => /* @__PURE__ */ jsxs("div", { className: "ff-panel__field", children: [
-        /* @__PURE__ */ jsxs("label", { className: "ff-panel__label", children: [
+        /* @__PURE__ */ jsxs("label", { className: "ff-panel__label", htmlFor: fieldId(field.key), children: [
           field.label,
           field.required && /* @__PURE__ */ jsx("span", { className: "ff-panel__required", "aria-hidden": true, children: " *" })
         ] }),
@@ -1026,6 +1043,7 @@ function NodeConfigPanel({
         /* @__PURE__ */ jsx(
           ConfigFieldRenderer,
           {
+            id: fieldId(field.key),
             field,
             value: config[field.key],
             onChange: (v) => setConfigValue(field.key, v),