From b9aafea9a0bc9a79376691c8506a43f5dab84467 Mon Sep 17 00:00:00 2001 From: zspriggs Date: Thu, 11 Jun 2026 08:27:08 -0400 Subject: [PATCH 1/5] wip: add mutatoricon to docs --- .../define/extensions.mdx | 22 +++++++++++++++++++ .../guides/create-custom-blocks/mutators.mdx | 10 +++++++++ 2 files changed, 32 insertions(+) diff --git a/packages/docs/docs/guides/create-custom-blocks/define/extensions.mdx b/packages/docs/docs/guides/create-custom-blocks/define/extensions.mdx index 58b414524c1..0d318264eb3 100644 --- a/packages/docs/docs/guides/create-custom-blocks/define/extensions.mdx +++ b/packages/docs/docs/guides/create-custom-blocks/define/extensions.mdx @@ -89,3 +89,25 @@ extension. "extensions": ["my_mixin"], } ``` +### Mutators + +Mutators are a type of mixin that allow you to add extra details about the state +of a block. If there's an aspect of the state of your block that can't be +captured by the block's existing properties, you will likely need a mutator. For +instance, the builtin ```list_create_with``` block uses a mutator so that the +number of items in the list can be serialized and deserialized as part of the +block's state. + +**add more ** + +** add screenshot of list_create_with ** + +When you create a mutator, you'll need to define the functions ```saveExtraState``` +and ```loadExtraState```, which specify how serialize and deserialize the extra +state of the block. + +As with any mixin, you'll need to register the mutator before you can reference +it in your block's JSON definition. + +For more information about when and how to use mutators, see the [Mutators](/guides/create-custom-blocks/mutators) +guide. \ No newline at end of file diff --git a/packages/docs/docs/guides/create-custom-blocks/mutators.mdx b/packages/docs/docs/guides/create-custom-blocks/mutators.mdx index 7fbd8d3c091..31ec409cedd 100644 --- a/packages/docs/docs/guides/create-custom-blocks/mutators.mdx +++ b/packages/docs/docs/guides/create-custom-blocks/mutators.mdx @@ -147,6 +147,16 @@ If your `mutationToDom` function returns null, then no extra element will be added to the XML. ## UI Hooks +In many cases, you will want to add a UI to your mutators so that users can +select the block shape that they want. Blockly's builtin MutatorIcon class will +allow you to add a mutator UI to your block, + +including a clickable icon which +opens the mutator UI in a bubble. + + ** what does "certain functions" mean?? ** + +** add an example with mutatorIcon being used ** If you provide certain functions as part of your mutator, Blockly will add a default "mutator" UI to your block. From 45a2a150ce68ef6c8fca8b86c973fd12f5cdfaff Mon Sep 17 00:00:00 2001 From: zspriggs Date: Thu, 11 Jun 2026 16:10:09 -0400 Subject: [PATCH 2/5] wip: add more to mutators doc --- .../docs/guides/create-custom-blocks/mutators.mdx | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/packages/docs/docs/guides/create-custom-blocks/mutators.mdx b/packages/docs/docs/guides/create-custom-blocks/mutators.mdx index 31ec409cedd..0906af9753b 100644 --- a/packages/docs/docs/guides/create-custom-blocks/mutators.mdx +++ b/packages/docs/docs/guides/create-custom-blocks/mutators.mdx @@ -147,15 +147,13 @@ If your `mutationToDom` function returns null, then no extra element will be added to the XML. ## UI Hooks -In many cases, you will want to add a UI to your mutators so that users can -select the block shape that they want. Blockly's builtin MutatorIcon class will -allow you to add a mutator UI to your block, -including a clickable icon which +In many cases, you will want to add a UI to your mutators so that users can +select the block shape that they want. If add serialization hooks and the +`compose` and `decompose` functions (explained below), Blockly will add a +default mutator UI to your block. This includes a clickable gear icon which opens the mutator UI in a bubble. - ** what does "certain functions" mean?? ** - ** add an example with mutatorIcon being used ** If you provide certain functions as part of your mutator, Blockly will add a @@ -305,7 +303,8 @@ Blockly.Extensions.registerMutator( added to the flyout in the default mutator UI, if the UI methods are also defined. -Note that unlike extensions, each block type may only have one mutator. +Note that unlike extensions, each block type may only have one mutator. Once you +have registered your mutator, you can add it to your block's JSON definition. ```js { From a7bcdf209ae9cd4df23f90bc5e879a78ad4f662c Mon Sep 17 00:00:00 2001 From: zspriggs Date: Fri, 12 Jun 2026 10:01:47 -0400 Subject: [PATCH 3/5] docs: add mutators to extensions, reword mutators UI info --- .../define/extensions.mdx | 38 +++++++++--------- .../guides/create-custom-blocks/mutators.mdx | 13 ++---- .../images/list-create-with-mutator.png | Bin 0 -> 21965 bytes 3 files changed, 24 insertions(+), 27 deletions(-) create mode 100644 packages/docs/static/images/list-create-with-mutator.png diff --git a/packages/docs/docs/guides/create-custom-blocks/define/extensions.mdx b/packages/docs/docs/guides/create-custom-blocks/define/extensions.mdx index 0d318264eb3..67a8a0fa7e7 100644 --- a/packages/docs/docs/guides/create-custom-blocks/define/extensions.mdx +++ b/packages/docs/docs/guides/create-custom-blocks/define/extensions.mdx @@ -92,22 +92,24 @@ extension. ### Mutators Mutators are a type of mixin that allow you to add extra details about the state -of a block. If there's an aspect of the state of your block that can't be -captured by the block's existing properties, you will likely need a mutator. For -instance, the builtin ```list_create_with``` block uses a mutator so that the -number of items in the list can be serialized and deserialized as part of the -block's state. - -**add more ** - -** add screenshot of list_create_with ** - -When you create a mutator, you'll need to define the functions ```saveExtraState``` -and ```loadExtraState```, which specify how serialize and deserialize the extra -state of the block. - -As with any mixin, you'll need to register the mutator before you can reference -it in your block's JSON definition. - -For more information about when and how to use mutators, see the [Mutators](/guides/create-custom-blocks/mutators) +of a block. If the full state of your block that can't be captured by the +block's existing properties, you may need a mutator. By default, Blockly +represents mutators with a small gear icon on the block. When the user +clicks the icon, a mutator UI and the user can select options that affect the +shape and/or behavior of the block. + +For instance, the builtin ```list_create_with``` block uses a mutator. The +mutator allows for the user to change the shape of the block and allows the +block to keep track of how many items are in the list. + +![A list_create_with block with its mutator bubble open. This lets users add +more items to the list.](/images/list-create-with-mutator.png) + +When you create a mutator, you'll need to define the certain functions that +specify how the mutator should serialize and deserialize the state of the block, +as well as how the mutator should compose and decompose the block's shape in the +UI. As with any mixin, you'll also need to register the mutator before you can +reference it in your block's JSON definition. + +For more details about when and how to use mutators, see the [Mutators](/guides/create-custom-blocks/mutators) guide. \ No newline at end of file diff --git a/packages/docs/docs/guides/create-custom-blocks/mutators.mdx b/packages/docs/docs/guides/create-custom-blocks/mutators.mdx index 0906af9753b..1e4c910d34d 100644 --- a/packages/docs/docs/guides/create-custom-blocks/mutators.mdx +++ b/packages/docs/docs/guides/create-custom-blocks/mutators.mdx @@ -149,15 +149,10 @@ added to the XML. ## UI Hooks In many cases, you will want to add a UI to your mutators so that users can -select the block shape that they want. If add serialization hooks and the -`compose` and `decompose` functions (explained below), Blockly will add a -default mutator UI to your block. This includes a clickable gear icon which -opens the mutator UI in a bubble. - -** add an example with mutatorIcon being used ** - -If you provide certain functions as part of your mutator, Blockly will add a -default "mutator" UI to your block. +select the block shape that they want. If you add the `compose` and `decompose` +functions (explained below), Blockly will add a default mutator UI to your +block. This includes a clickable gear icon which opens the mutator UI in a +bubble. ![An if-do block with its mutator bubble open. This lets users add else-if and else clauses to the if-do block.](/images/mutator-annot.png) diff --git a/packages/docs/static/images/list-create-with-mutator.png b/packages/docs/static/images/list-create-with-mutator.png new file mode 100644 index 0000000000000000000000000000000000000000..92ae2db457ecc35bb5baa78523e997ca4cf7577f GIT binary patch literal 21965 zcmb5V1yo$m@-7-I3=rHBbQoX=!QCaeO9&oZ2L^YC;3T-aOM(V>f(3VXhv4pZC;6TK zIcL3l-+K4WtXb20cXd~H@9u9`SA89-q#%ioN`(62#S3(4DX|YPUcfrGM&j2^}VUEx!_zq>PH83^ATLe#|I%L`kfs15O*Ol5LQNVv%pS>V-U*g3E4a3JXFe0RBtz%o z?!ezt`<;IhVk;c*^lu=nz1I%H5xnA_*<_2HkZ(0#)Rg}fSRQyk)EtfNje}9RaPf(l z5Upvu=hgB>c1cYw$VtjR;5Aqi%Kl+67niyt=is-EV)a_6ipUS9GE)0ZyDm~(apfpo zB3X@br+68=7cHo65_-cn3=Z zUckfQyg-1Z;9%bu!H^e-f735sfMNeHULeE-y+DTjp4AHnx3 zqSDf^e-$Hp6BBC(a~nrsh(g+n7w`g*j~b2|@^ZXJHdc%V#x{l~jILI;e~P@|cjbj8 ztxOyZfUZ_hYX@Fe0nlFwURe6iZ6*-#uZW|i07ye#2`Fk~Zvy0GWM*Ur38DglKz@5; zQ{E3^68|a=yAlAIJ389(GBLThxG=h~G1}OhF|qLQ@Gvp6GO@BUz$6$P+^ii9Tp6q# zDF3PCf9er4aWJxn*g8UNtbu>(H88Ysaufi8{wVtQ=bv_(xI+G;$=cyx-GX(H=}!(5 z3nMer|EZWG#Pt8A*q@w#iv8`^KkE4ZRK}|WaW#Qzib1SkqY7)9AS(|i|6eu#Th4zP z`cFw!2NQcy8!K2rN5TI*mVXug@67*a!M`ds{-ctOll{L{{#VX_mHg8MUPXHdOq;=< zF%)FsXZqjn{Y##o>CXWF*MR@?H2>a(Jx)PXex`p<4M9{7DBSIf7s4;3#om8(g*$9P z@%%V7hy0L9eV-8}tbq&o0uTF?`G$qnXE89$H`dgYmg?2mtkh-Jw2fRH8m_dK*4Suk zAA;r^v)4ahDI?-3tG!3J)Igx1xM!6HS9y;(fL&OnO~J9oF^kD=5f~1~0y`P!Y0t?I z#}1k2X*;hM!1oF>7AnX$RvoDr&z^k|r z+P`^NwGS`<6u=6>LJX*&G|m!}gI)YdZ*lz*|12B;1O|{&AW$2k{;3KWz|i(b919VI z2uE=Mc=Hxp<*!Z(=q>tRWmpsdfPrMMaA?vWaael5=8rg{AK<+(fKTM5Oc&nYCIYm* z5&lYu0pLYuv00Ts1%DeTGJ8h+w-Z1SShFLd{BT&1{%Y($>|~yA*fS;+2O-3jPbg5U9|q@lEfqB>`s{rt*O>AR#1EU1 zSzYUuF@{!Fq9!Kz1UfEorh}y9ECS5+wBlc@LFR2(MQ@8c6E3@7^SmSf2BBppLch3{ zxZ`++-!vO#f^Kd13j6x(F(%4lJ6ky+^pAX`^nvnPH(Gg%ISPL)33**`0%&l)#E?s4 zhkKI@saPPb&^ok@sily{3K2(Str}l-Y_xq);;C)Ed_%z4B7DsZFxdAF>7djJlsZH9Q#?^o!rtO@SrctQ z>HZo@rY*7%gSe+B>L&#nC?_(6fPL=muZj~ml0Xjeb7S`BEA$77bp;s(rIl_Eg|!?y z@UA;mV1<(a{~B&t!FLo&$%60d!h|g^EsWFoSpCXS9D>8D2im`DIu@FPEy#H47JP%W ziq9g}+Yoa500=`nAJsW`z4c)=2#Kv>kIHXjX6PHIrXQ0V&oe(ENeZC^B6mk)BoJbCu!RI7k$fw@fi= zVTI(w%Ekt<2IjhO$?j4}{0uH#pgxVc!jhd%|7+~&=h!A~|KrB(CYmm~){b4yylTHB)D6N9Swgch9ja5=QEP~`MC=R5E zS)$eJ03ivb3)!JW?Ew|Jrf>5pMZ<+fMLU(g01qX3;Mb{fwh;Iymx{lcqr4Rv4%zf| z6EHz6t}FDYc`*HgZ}g?IM&*_O(J|5&tM(}PZ6%^HNT9L~l>>iB=EPK1`zJ=;DC??p zl|2i@)cPl@4qNq|Y^1Zx(4JOpp@X;nEUB7Y5^H5)P7HYs;P=Y)JfS-URF8eLUJpPr zrykg%J(Bgk8LmA<%Q65(n~o3_;_&#u%&qxhw?(nIm}!L?xs=-;ul_hY_0GO&krMEV z7q-;=G29$EZ%*%2xU0)a;>D)3!Qg#U&fT~XZu-wk5r?f-HA%s*kETO) zb;gGa{IQ-6u~WqyJ71+vO{*Z(X<9XPhCDDF!1{v&B_M+|W_&Lihyj?aL5*;li;6_v!ut5IK-bxrN$w3nvl?GGYi7;IV9`o^t zpk|`SmmM6B3a=dEJ6n-!t8_V^-$Uj;L8tXWhX2>soh4i<6d0Hl!SEl z)t{}WcuZp@jJj^{d#uIh`iPjZBdNx{S9b z3~3>EDW=dBM?|)5{8epCrtH!TEv4orynBVo)w}qrvGK_u^zx$#Iz)r`;sfL7#GPQ( ztQYa89YvuNX9%19Tgx!4ULvl}gKA(E@yv*!Sql^0@Og zEeYQZPtsLxJILmm1t+cxxNBme0+3^*=Ay`A)PJ3IApdEP)I7# z)2k7k+czFQ3&KTB3tirvj`fZ4V z!j|-7nU2yDsl!*b;Z0)Be0)Pryk>HnDYP?x6HGcP#Jln`IV1 z;v0p&P^v#x0HoUSE#2{#UgEhkXT6w?FTysSrO9dK+IAGLB>d0R&B(7y(jvlv@X`c? zHfk(7zoIdls2(YSVC=`p=p*XQ(iT^lFnvvTowm!KUN_xiDEIXmfJVc zj{L5Hw1xX^{KUF?qw>%g=YC**|$$o*xtaiL<+!woVRDUsCaSk@qbgy8|-n8>X16FuuPi9}ULeG*EHy?ks zIj^gXXWTke=7sh0qd2GH@^Qwm4y-ie-Cw8udV`upExiJRoqZ2a(1%8GF1gOx&^d1B zlaiR{-`T8fk5bZdBHbw9p;27RlZRwmU2f+xX_2uw9` z(vqS5HXtMhgb9P(UgD~dDA$g-=vB-@>LgsHZ5Q2zaLgHUaT!CkpR8%^S{%3>mfbV- znZ@k4SzJ;DgnotImyD$#((t)N1*O`(_?1??5uqRW3(Gv443x;xelWYx_^ZmK%(rCa z+ESr{kOe(SubMr}1g29#z(ahzWjeN0ewJ1h0iNMPQ*fNAeDM>l^$iJqemF=l$1(YCG8{1UF~ z(JsH&mOQC;$>AuVkCDoQQbmvjD0u8(d9D|P8)81?^@z>%0}x3Ffqvgr1s_t$bB~y25_wCXPhE02L;R%to`R zfxZDp%@FC))ij9S!7s1K-80IJ3&B^~N<14;;rum+|1T|T<8hXM4BwYTei??<7aUgu z!ULqTmuLn(pil;$M$N&au&nP1TXD@Xd^e2;~!%95tkE>MZ6Z_A8MTImie<&kE z3=BjHktE8v-$3@lo!%*nlcQ`s-yrrX>zdBSa)yT2U8rFx0V<{k<}W5Yq(gGC>Q%SU z-|~$)AhtC>yprR!q5uAl2*Dbo1Txin>Ck+bLH08H6?z-?W|_>du%= zig*kZ_;zglaU<4r4$C0Wa^+e7D%Z{C8OG6r!8)00QbF}0L8dsD)Op#F3h*~Fw<8JF-hq*H<}~XMh|Djtd1zYHa(dbv#vqhD+a=5TE>?+NME9Q zUGvo1i-&d{5=4rYOYen;IFGIGAZ}prUMW_hNT21+ISrE#S_7`6tBp~36PH%gwFJ*^ zY`>#`L&u*}^YF7!f#t6^uCHUwSGZNKEj(?U7v@)MKcp+ryh4#?9#x>s>N8cZ3M{MZ z&}VIrN|SN(T43$3E43wQB6Y5RgTRN>oBeqDN}86rtJ~%K{F3QqoLz%&0OD(06l7HY zZ40ZH^KTgutcLQACZscYQJ830zP#}8H#RkmawZW3h<(8zPY{@z42O`KDRi9ev6(N_ zRTX+fGkd^&uz5lq+z9)eV6{+%KJ@I3JsieLrQ?L~p-k_6fT_p?+jDRNdU+?iA>R1W z4Mq%OlSFi5aXyMQNB}G?YVT6{YF^_tD`^i#d*!y~EQa^X^CbAZWp^4J#^!pJp=m4P zZ;DJmHC4j9Zqu75Tfajk>X&t)4U z&e$dkBa1LOm`zMNmqcvP?Cd5pA5r;?Bv@k@^;m&t()pi-^|16Eq-@4R#*&jf#Ic_q z7mt<~!6wL9e%1kp3kekMuT+khUr&sCF?mD|<)ZR$qaWjEBGfH7bc~HZQdhm%{tTiT z&Oleu75qBa@I5Y7jwPZhzk*corI7@|C$RuH+`2XUasR+=h47Xnp+o6fUv!xuAl4k9 z!kP5DhtBW`JG~Ysx@G1{sdHh&{{0ub17W1vRxe=X`w;zIe;nse1{AF15414^OlYNF ztO+403^M!9RSb#HiC-7=^?i)X9B=we)9>=jDYt$t@Ne}7{B*XSww@Cl?6azCpVB~1 z%#Vg{RR>~E6_&+H45tVrI!(>Q%uyv*FB&lC<#kGd@xq%`y^Lwh7I;$M&c5orwtM_l z{pwN~zh4NpgC0ePTh@8Jr&D(;ull7U|1=X5gyEMJutfL6{A@_mjUYi?t^MrI!8R@) zR~k&|)`xDqAg`LYt4$tj+o|U*?z}q197*K=)#gE1-dQWdC#HJ;@q5u>FU92Zai>(n z+JMyK`Vuobxj3S3WI~;uIPP57VK63c-$dt6V<3Y7^0xsS(LDy24*td{Fxrs0mkk3^ z<|8iTpfK9Ir!Jnr#%-6JdDIwk*YYe4MypJg{bTI60lvNwdiBL7EeHm@pP4+Z;DVxm z3GAnA)lm$P4Q$wu&o z&4#?zE+;0JWBBUgiqJn#p`R&60uZU8R|&S$s-4nT^VXp?X5$~w52!`@G`%7KH$LVa zXFTKjbHrU@M3tmNHqCN~Z;PyqbXOiP`x?h2bUwbfpsz{#C{b%qXipe~v=jCYudRP?zbfOwbwP+Cz8aN zl$3mL>U^&4(-=yr4X-EPJQiJ*2fs&I@V>yaAoKpob~~F->hNT1EO-*qllPv}U|;fh z%nY}okw?FuJZQ69wy!e>%PQ0J)&8)RV~Y`H1EZ>&;@pMd;Go2WP-YfNn@&ikMjpH6 zbbx#Vnpp*8T9tRp&GjEd-IL0$*pV_BXJY~ z{N{8=UZUfIN9=-U*?H@a8|X7-#qkDi{neK$+dEfuj01sOPi&3-<yezm)5XfZsyDIS3*3tp?-u1~enp!hEv1mp(rzNNsM#6MC^EAL zbXLsK;Qma;(3*7&Z9BSo!6lS?>G7_wALLw>Gven{jxAe%; z{I|U+KO_n~eHQZ|VV-jtOA;C2+D^%j#CJdGdXx=FfXKz_$jel@n36Vdj?+Ng1K_C_CQ< zh8u}E-~frK>}zscjXlN#p&T1G=Vl!jPkjAI3OWa!LSRC1fjF)uP zKedY`Nk*sz92SAt0Ew59<=A8bSEX3wp>;nASp!)Tqm)IGvZp9sd{%UJ(}E%aLMaAr2~6J0Tf z;b68$?;_5J_4w37GFsblZMY^3XZgG_kMjG3V=aYYB)_*}!si6Ew2VFXHg0K%^{Er4 zk>Zy3Bp>mdJ$joam!`*%qvJyT2s&)-W59#4p}IqH%O11z>m}tXw_cBu^0t+ADAXL- znxe6In-WFT91XK&s#PoX*)1grn{K!K)HR+NU_P$}!yHp4LYLwl z{Kyu4*Efw+?|~`U6*W9j(zt;ocy+b2Kb@^=)gzOczg`eiZhz7Z@bIZdEOC-0dX4zm zViroM_B4D6$8L0Hxm^#GIP>E)nV=$@t4fQn_V50dYsWTA9wBkRw4S9DydZ@7ab*2NQJue)C*NkW0o`!dzd=e!I_eIIKruSkA)HwT8qkqz(q-_pcbLp$}MEoGnO33S=>i4XDm%IFRKNA_01HY*&cnYd4Gw?{4Ntj;==-(rCW%!Nc%z$~YgWlsTdEu$v)A=@89* z%^Dx=+U-lFDU25Aa%WrJiTi>*o8I-6^!%s2$}BCOp!YsjIwUz-)Z?~Cq=-tGG7OR>VxqeiOvV(+KywuiaifP&_o zcz(9Fu8$wPJ6g($R`9mdKK~p)xilvJ#0fOdYnO~_TvRj$h=m5I)@*9psT9zzg7m<@ z6rJm_4zS94A<_T9{8^4ffQn6C#-di+;pz2Oe-Ah&!DZ!RF#$UJn?%Q5!>yD;_6^Z) znR7KjJWxY5Ep5&rz>3Q3ep^8B>B5H6Xr%rx<#UH5IqkpiFY<` zw-D};1X>qCPMwpOi%m;wiFvD)0JoB!;y{y)MmIQ2%ZC(VL(HWQa|PJBQ}84igHYZ3 z7}hphfd{Q4rpLvl@e=4-zr51`^t zYCax0MD!?KqFkjmNG{YTO#HGUJw*s1Ly90`ZYa}F?jYJwXwU{|W#dQUGnwWdef%VyCe{xxnh6-X1_l&d-F>;rVg zeYmCq@;SPa*ns2Lw&6`HBC<%>elL#elBD0KA0P`@0^BJb(;ALtdp(-mL~J(0@+(DV zdC9COtVuBy0>U`$v;nY7E9O>WLU{9-$;BtQ392ZHBqbGE& zyAYnQEl?dv;Xtt4rkc_%(vC&)k7yCISEufwhoBiC-#h(gR}9fEM8HKbWRd>6#T!r` z{xE-4R*KAbxu{-T2C`}{;pevwO(zN+!(}_321(NZqWJU*fhqza)Llym!Z8B+0A|SX zg7*i=LUO}tQE~BgExvW>y!H>0pM%7hQsc<*76a^BSrZFXT}#?sd7j)@CsVZ!G!Z9i zeWti$-&<@0E`NUdu|8j+_BI}!6uv#g<9A+6LM|yB*jn1(ALevMM&5aEB~E!Xea!_l z*(HpUIaU4ZbKax`(ved7ylT4kHFPBYu&zo^h`?~DesAN9L7+UpZ%qu9d8E(9UHp!k)>kJz_!<64VP zO9RT>JWL-bh#VWbWsOHEjwStbl&=x^8)}3Awg*v`ZQN*uku$45m)XL)H2-a=s$Q01 zMyy5Cs1>D8&a_lW>hQS~konvlU+&eHPL%=fY}%GX6l+Pdfs}kmJZ=!?ahvo0RK}BStCRXvWNw@_=Hqj0%m!rUBEpTZR#QE}i9XK&{x}6X z9bx-A$ZvMM+|pm!kujjOryVb6dZQ>rP7q+e45IGda(ym+Tuy^j_2kq{Z3`s&pZp0~ z=(H_IaYm%sTQtz?ccePN!&7y3c#mC?PtTR}{em(zUR8%A$m3eUd^`*~CU-J>k^Gz5+S1^E4>RhbIEb7>yaR>X6-w`g*nQ-K3nNqvr-j; ztk);~zJ0R5M|2N;(X_tgGNH2EBLh!|2hHxNSSS5ld~O zR0#*g9eJTDcZhvdpa&WIjg8-40@Tyr_vy`)H8gxbf3`CRAGWs9Qcr~7yXZ`9)@+C#GCWD?MtwcUYM+7sW+hEn{v9bzn)NCK9irJ_gQ zH^MLN}sw{=YW`|q!8e}DXz_Vy2X zAove?phd!0+5_gRmsuDd442f=X{n2_wVYZG+j;>D@>Bld1PD^B7F+EokgS#Z4}o)3 zJ=OsGept>LYjOREezT&!q1xlCKp>jgOJp;M_+Ju%Hzh2pWdq2Ee-Grve$B#*%e5#- z!^=mQ-Gb8*G3tl=1If=%0%+z+M8J?*;GDDu^HDt+esVs%MOZ4CB>zKM0Io_U0I>!D z2P+OlD|!v6%}qQs)AelTUznvugJBO4gY?ROx$;0s;CGayqrcHF%+7VYni zZC`^tyOG9vEQR2|kawrX&OxqDpB@IC=ln{z(frp>!Cu_F)-3H6rR| z>l?lmp)eY9FT&=)*T;Ef`3`1#r-jeDk@7a)5$NRyD#lN|R+INv10H{ZROTg?@7wbz zKv4N!z#T!X6e7BskC?o?ER}X1F?P|%i^2u_;};ZB(dnPln%Q5=zx?DjfwZhvQtDhm zD=yoEnLdG$O^e>`Ap;B8glkJhOJ%PVqt0y^bt68Dzubwj+ zo3}X67%gz~S@jjPY zzf^ntClE+<^>g)I4Jv%2nEuE2oFDG$?+5-rkqkXWiGKO;hw?s-FMv=6z}JDS)J2Hs z{^dn1=e^u@b@u;&*q+e;e-M+V_ya>Ar4MpgAz;K=wp^Nys~J7#h5eM-jMBO4rtLnr z|8x^>36yo{F6go*Ho~dr#UB2<)}IBKgysC|Ri&dc)+m;KIR?y8%xs;6V;E0I z4)hNn2a6H$>X46O73m{{y&0)tF@7;@cm{OFgL(Up$>R0ebVrRcUTWp@MeYqg$EUt60&YbZty=Cs zKMTHrq2nw`>2h#@q8d4d5#Lb=mNU6GtNj-sRv&;}WwK?+@{20rY(gnD*gF1byzJ&# z_j;YIT;ixLVCS9Xlv6_0-ezH28<$)FX-W6*5!{Z5Czb>ci9OUnO z_7(A!ZW0RZn|1jRO~c5ha;~grlB-B9gORW<)kjgGDfZzRwiu4cz3uCO%=&-}8l?$e zl&!*bVN+}&@vRR+*jPdb-tceh(BKh5h4Z4WgbjgCE`JCBet{$?ut_UiJ378q@hVhF zWL6ZuiTxcQAjlWd0u{YbgO)mgl#Y_&@v9Ufm6D1W#)2;jLu>@X%hHeZfB9v5H&+ynIaMNLaD3I|__%{yDI<7K?|27)0i`jA%jR4&kHH7qSA@8u>bAjkQry z96YVjxS+wqI5#%%9O&Qm-xJGrO=@oVCqxbYXJP+F^;1IN*p)HIE?5DCpf{~x$sqkD zg}uUnz4`t9tExeNNoZ}bH}DZxzz4s-n@E_sjdiuUN?-bya5icK8~%Ir?2mu>YCmBw zi~s>{Zdtm&^;{6cAm3Z`E&g9oW^Py@787H5T;>%pD(P+Ut)YHWaP=41prE#~Gr}~9 zhWjoYl38GjSnC1!jEnNJ{^}F`0@F9T&QvOi0^iK%Dj^{ecOlW3t^OyD&C3c>7oz|g zlPY)O|L8z9kUSU-U3Gu&TVpBx`KLY*ICl3E!6dzU&AtJfXM&Cwjv?gr0e(kHjcYI> zoOESJ7|d4ESevvn>6%ms#lab(Ye@taLMLM=5PzB;GoKR;A33=nm|C828(39^slRvywYs$u?GUWh~OC$ z(X7;np;j0tD56?j96@wJOGT`RkbfjGtgFRlt(u zD(JA5B~Rd!qd0c075~?5Fdb`^N|ach6>BQqt+<#^NLKj8n)=L5fNR%Sr=)=G-N~SV zwqP4%_7G!s;lMV^Yo(ihR1X{i02*ma1$P>~gcMmyIJqID5HHv+)GcN$mkC&5!3|8BnfzLQ^QdTLTHbI8Wl5yP%rb41ui)A^p*^Rf6(w#j zYyC5w_Az2Bcx72a(3pbUK4C{&#MGrZ-4kf&-Vu`&DgtjCwWAx?Et%1YkA^U} zvaF7s+1pM@NX!&Kx8I4Q?K@>&SJ{g+sP=aO;7hoe;fSRdwi|jfUU`U2vz&E?oLS#d zL(N188_=@uk*;!BTey2XOPOg9Pp|BozHTFCgif%S;7%zB3r>=rjrBW~N zYu*?_2;f3$78U>z{e=(-Jk6o|xT3LOweUzmlyQe%vLF<6c%rP~Vnu!43(uu9E;( z#k5?9(s3y_y>!ny@%P_9i0kE9o)Y1_yz+PjwnrK$I5TDYRLXFHRoN-bN~H2(3ZZbK z#Xd(H@rGrj>ajg7Euh4S&l99Uj{Q5jqG{SPL{WIXTfIY51;woU&1_@_=)Bw6Om89D=Ie6Io>gW&2{TZrQ^;K z)2l|x74gZkQO@wL_81&fM@}m-fu@*avY}PKXRgVSZ1#%wR4R#w7*gjYJ7uDOwk2kK z_*MvgV6QFrc8GAdK86hIRI2IH+1>JW@bvX`%~sg~3P2a2YPxY%$moS!ak?euPa&ba}ZN)cc|*_mj#zv|t9yjF2lCH(N2MSZVh zM+zrTeaG3^g!#?>@o%kIki3!FyG1Ljilf>0wP&QZ8FZp|Tu-Y<=Sf_ z_J=jIkKTlC-(DNYUAsosYnN7dHYI4;>fy~ zj1`L(KVZv{@`y35~B($7l>DEzuD7NmHKnBD4>^~Za z<;zPxZ`?q}8^82bZMq6~IAedSZGL=L;$aSo<43?@YJva8wNwV(XE<&S+D5ne9xOHx z#F1B{NEz-SSVG<+Db|`y_6j5E+#$O9gy_V-;BX?{e5o;-{bE}fG;j$J_AR9P_z90( zGr4489$NIRgr>4gY>5Z0tko%~{^(YpDmeO!a3)Hs)z9j(xd{iYKyr*GihjfyP%$iHO#db|$v5`?rpjsUU>#wP`7wjhF){R^cWC2R?4VtBZ{htq z(5Bly%Mx+iVZDWjbD?CRG3wHVya5BZ@Fnw)-9|G|8gP}|PY}0uV^Oo-qWEKJ!B@Hb zhC7?ju1U?JDJ!02;fl{0U`oZ<0{Plau`q(f4qYl~u@Zq)@M3}l$mnb@%ea3?J%dck zqvSBvUNTCa52=jk447Rx{M|lf_9D*AqlTry3sm_Co;Xov-%UoBbht+lEtYFVM)ccx zx`AVWyV_Wvi=0l`(~eH>&Hw?~LRw-?1srrKu8w(21s}~ttfwg8b5ZS?T@0czsEJ*p z@5E;1eqQ?A9cYPwcuGe4&^Ym@o{7BL^c3B7@Qh~|Jy=Wvwj-G*~j)XJ9+H+QA$ zJl??R*SPN|`umAzwKl%F7Zk*vmKZ-}`H|R_ z^Cp`pOOo67}3)D7uXGe#cN@8%j1;! zS+&vVhHAaQ?g}Cm^1{IRZM4vqIWMH3b^E2?X(TB_8Z$D{;L#WvGO{VaYDOjx9sck> zcUFb!C|BN?OUQ3~M$h+rkT&T|lCI6}ek`{Y)NdC6(uY8idN@qcGx{36o>)XYC=JnI zj4#-WBVF~yeBWq@@EL5z|*SsN*u6W}MnL(ojKZ&|w<+>uH^Zv9sZq)zH~dYS6It zI{NdFv5TwmjS(6RCxLB~?NJis2HTf1)jrG?#VK)IAyH1ixJ`Frm_y3F~u$tDT5($sqctvSaW22I7Zwh%Bul{xhmxw+=UegDfL z0}i(ax5WVI>hEWK#>8z2WN%Mpz}7Ydj@9DqFtl#zPZ#_IP>?>B;7|ulDRE2EdGMa<+m{BKo2(ro&T&gfWS+dk4;u0dZY-sqS~8iXqgM1plDJ_E~=A{&U-CY0qn!xa`?}=ko)bZLlK}1-#UfbTF+#W{pTy2o5tJWpQDMBz#(m}pK^>>TG*n|!V_RqvjLzMQ|5{WLFd z1_a~0O$s=tAX+V4W{;Q2HzfB{k2V2%ZA|QyDSjF_xn=mN;qppVSv|}Mjo!8MUHq!V z%m21x@SMS!_MPK|FY;Yk^i?Avq+JC-3uD^^#!9a52(1@2XGe3WdmNPz`#cI!l09v` zPVp=eQ4zHSl!}{1FJkW|`D{^@czI(!8i&_gchh@{-8)XFSrS!a=(JvVrtzsnc4j*H zAD8L(<@^$9Qc*Ajp?u z^7tMT_lC{D-ld7N>9(n6foIuzEY%&X;nHjf`B`8VUZ{+ zI|A3SlMx?iKEw)Vo?tLP}-LcJ4*0Nc25g7hz519h1o$ z@%Lmx4}^^5m|*)SxpWS})t0d|mLj4neT3xd-|id@a~I`8v1WY+CW3a;F~k(NyD5@q zh+Fb_`N!JKk?G8{IpU@sIw;!vNDV3}BMAm6r}PqCW^3m2>~RHh5>6db<6&>FWJ7Qp z?NIEvcQgmTPaQnAZoi~7PZ7z_k$y?Scc9iaw4!BU!K|<0oaX#};Fv0mzK?Gw z@aCysl|r?DJK4vfC>6sb5JK?WXiODHU^r z(VjyL?C)y>48urN+w)!95O5*Oc1B=f`LHt)B54YWEJJ6+(^R(TKI8ft0-oB^Bz+#= z80Yme>0Zg=Z|5=-N<_vnx|LshZvjeDBOlM+sqR`davI=3=EYVO`L{o8lFE2J^`9^v zz}#-(=VlQSqF!iWF7fYh5j@ftZSP6a_&)?*3{nj?K;gZgpG#F#|3jz4r;&YkdX%E5 ztS9=V_N^UzFKq5@JfQUeEj3Uh$a#YW$jMX+QchKZjQSYZR2#~lXH;F!^_uL;N_3|j zmJ%7eitOh0Jogunr@X%FNBOMxmR{A~Gj;~4UuA!m!=tVKaqx$`AIq7rWwvj|r)V&d znu#slvk`I3@R8$3L5dt^xYvTByQQi8<1jKI>;w(FY4_IN9fQkAp>Qf=^XW+Xp66oM zr~DzI^BdC+OAOeVl3x_8p^l}AolEvaI!XTBd608$mE9ljO5EI$12KLt9jU;cyQ>^&9UVzNH7wVTS6@|$nvhHYCmNjnjP3teiqcVNwH>ask#vV zL#T1SC`kv$ZHAZ=_e4*sn&wyc3>8jRo9SIH>6ljd?G(BGSi=l+t~H%R4T*Tngs26a zHJYp2BB-&=&-?@m4ofZ zp@ZsHY(Zq#kjtll)Z=D=nc_qTi%j#t)uWK+chA-pJ@v07phNN}Q=VC*=!tkP9p5dN zAs8!zfwT3BHYgfpqg`*&*H|lIMQP^q2N16U>sQNV38Ms*x<{NS4`=t8pWaqdvbl(@F1ZK_X^EXQqqldU*XlyU>7vedmi zq+PnTnNLenuOwnfLa@RtkIg7F$~{E&6&72Z9Pzwc{P9|T-aX6RjfGe!>V`tCxe%|4 zDczUJd&5vQ@?k;ozA@vx**c5X`H^g^ajJL{VR`0i@M`nJUI*7Mao zODa;e(dCfS$;(Q?85kjJW=E^g^RQ7-$NRh~4oyvB>$D)9N98Pbw`E!W3aR($fPK(kCxP z!J{sw=MhmV;_18Vg=4kkOtjbn81uPGVncmJPgE-_SZZ$Yr`Gp`mTGxT^GY4Yb&E!B)?1N55|ZL=#2H<*dOjqBESTAqFrS8eu` zmWMKXQ9?z1A0bbDbH>G#AG$Wd?U3_pA;J0QGDj67S-C<_CRbX*9T$l53yt4-+_XU8 zCkB^Ry&Qb?m9Nq>?zg4>cJ8N40YWG|LIdDTt$SBNyLf^rNqMu%E^-n9uRVt>1?&u!jm zy>j;=r`OV1B4a1Lb|;e~-O(XeIO3!`z^iMn3k~&fltnr#i7%=+pdseMc45W6wyjP! zx2y+->TE6uu<^yO*XwT1uP`|P+P2Rv?{=L_6NzUlYc;&8e{nyd;Nlj-_>uXcXNF|c zc{N>B<#YL5&5erKOItJPit|pqVFlqz-IGa{TsNMIS<=0Y?_>+_W{3GrJtGvqWnj+X zwQF6R@$F>)e()s8Lq>>oC}L5)QaQlqbUI0WA=H}$y)E^NOkVAgdmU6ro*QUJ0p>)4 zd`q}XlqM6-20L$|8DpT-M3^(s1RR9Gp>HVaxboFppAUPtDTl+m@f5oR zYH#W18b-4DcVWjzD)Uf^Z?{%A@iSg4SUywpgQh+v7*?C@W#KYe*(ZJoTCGGL;C zdn_w6Bqe4m=SX zG^2u8@ZF8qa>pU^B64lFjmLG=c*z^K>7>MQ<84XD(!wqwx9MMn!({$H^5h-JC(JA3 zX~+vlARnEsJ_c`M^209yQa7Zub-f6zJOssHL|zyrna<)m!S+iBt{Y>@=!P_3g!&;d z|2qxc`mGc7Oszd#?l*nvI@0rmv0RDkHix1_qF7LNH0=D7m*SmbRtA45}H7$L8TXY zkSHJ^T?t4pk=|6`-Qju9hqKoC1J1XstXVU&=f3Zmz4rXB>mk`x(rG`G{h+O=^1=n0 z0FoC#e~yk=<^bBcW6`uOobt9DB`beP+rzbr!2ZKuCo7UU;NXY8>@&gH+0z-sm%3MT zOUY5&x>fXBNxCqPYI!~L{mBd*<{8p7aHW(zT)lI!gwpzJS3>Lkms^sx$vGJ%aOWk= z8|+kc3PC2CrCo%P(Nc^mKO+uLUdIu+cq*_piF~wR_0;kQ9bQ3bkEbTH#VR;`t2>D5 zt>%!bNL9_!pu#nr-96W~jSsZ9Z*Iz0{qADtWi>Ml&#lCloGsgUY=v6f-v8ZN8<)84 zeAb@8?v?m^!z-pA<|b2vGN~ETQZ!FaRsEcD1&Z?s%LoLNDu^jm#Q2Fu>;4^Y9fU3X z5=47k8lZjnXEc6B_aHKFuF{ynTa@A(!jR(BY1r{^QgruGPQ%0y>em9wPbA6?p1%II zoly-Mu_!I|8k94NbL$-xH`ZVNJFp+TBU{(-dEFE3wCv8#BsFYrv29)Fz_EVSOk?@J z+BYWEZw|iD0Dip;w&tGicIF0Oe$I(|hciPs@wEGGLb? zo@*!U1rKMAd&|$rv>ARamlN-~m$9D59882FO zorP|3Y(d6w*2q;_>_=xB8;b+1kh2fB5Tl-%llALYjJL=UjsK+fQl{F(~0> zWdQRBNv@Fx*7uPWMm^~%z z;{0}7TYlg5hP5hXjt$kPF|0ibs`DE$a#SLg_O|`lV0-hrK3q2C3nwm%p%@+qecmqO zf#Q(or_(e4Vx)(Sw+hdPk8|X~h)wX?_NEX&q3`>3rJpXfKP~|^C(Sqpdh&JBh>RFz zNfflTb)v^vn2HKLByKdjmrg8C80-I$NDu63zcVJET)v8LB>Fxp_>9S_9~8;pMc+^2 z!-&_$UF4Qf`~C=yDQ7xrBi~uXxJE9{e=)ZUWujVgoc;5uc)*6ew{@w}82*%Imd!!( z7R}~#8I;_4F)FC|-p)+A`GVYA8=|1fqEvJ~F1gn&be)zTb0mum zt)O4FbkkhwQI7bY9eb7VR)#Gul#a4$$7lR=9`x@&HAJEV|CkgV&YPtof97^)zSveP zfl6jd{y0ARwp`+vCpsa_!jR?Mz^eyx`QVadQ+pa^DNZR?HzYJ_^LPk!+j^HMIyfgoG7(;_zJjFnUX!sB(yZh zNcyh@ATSnV?TC`mhQ*0Fu7;N{oQwMU@tLUS-_YJFc%dKznADUl%3fTwu%3aibHH5J zt^Y`7U~523$YQ3%06Qw|R1ATyR=Hg{0OS&I4w0GD&q`0oN%r zRY>r1`91BIxC>eBKVlp4Bd_s+a&yW4K_2okGQVCUgf^LdW<@0w+Mn~}GMbV{ZZCS7 z2P+G>!PIVCW9Ob{R_8;7i{jEGL#H*J=4?3`Tc%i41>VE1)S?kQgd*pZv=sbJ@|+ z_iJZg_Xc@a*@tuKfJ2I>3f5*Uj_K1H%x$PjOYeU z4$+YZly}N$oBxzm;VNa`mERh!LKAje4CrmkCHholvM{@ONJm6X%XTz$CllQk|LyMg z;sg5y?%C6wFGam0B@`B4f6qwYWEhnVk%ZTLM}CBxmc5?jL>9M8v15mX5-ax^1L8DQgw`KrcABnVF)#D!c-FBzG<9dpqUocT zX=00w1v< z>8Gr#alhK?+O*vi=$)fN+OfE~6(qc#P1@@(eF&I7YL`8Tb(zN9 zY~*Svh|++PK;DSM!*2uYk83n0OW1CyzJIQ67ZT68ki&^YwV7r$(KG(<`uAM3HX!j>@5&UgTkFK55`Wcr3{|5mHQA8D)zj-m$cp9KXA1tn%AFU#a0E$@<|_EkGP!q8kZqf;6l`eo z6XJHYvUrZU<#OLm0KPlrBrTO|OF?n{pPOib39k)US762=MK5X#c7}b7Ut;Rmm}Ke9 zdZ!+0Ksi!l=_GU5O30Ln#x9m=d({Qh2O+#gFkcb6gmM2|!F_W19U<=CPVnp%32z?{ zb}79a`JX&Cv*FrT1M?S1;AAiuq%|?{)=!LbWu8aPysSPJD^ANqtH9Eij8s9nDJ5oV zEKDtzq-gE^{(@d>s`5O^Ho;|Wm^sc>@_3>T;*6@7H=gVEnZd^d1W?A<7bjlE{99@r znXfBM+L&oGvKW!xd92qiMt5{@&Du3zAWGr~(ovuf1NT?6}C zrt~?(kz~bSc`>naar#r3;DG90_0QnM|RV--&IvP2E8Q*ccq`O1)JOI#RTGiB~hEM4DNSKX2^PMCN7 zih>G$r<$KpITEg^?e$=%Gu$U#2U&+W2p%QgtI(`pI!MR1AREb>r$i0$6?eIT&_{8C zxk3J19#q9{c%I#EjbZD%uc-azR43#Ky1)Dz5J_L4Jh>CvR!RbFeOGc(Wq$VFNe$Iu zamec~Cq6~yn6A&Q8P!%;v8A#8^|{*$MIJMjv5)>HC8o9n=a_%`>E^-dr=Az|P}qQd zx_IOlJk{heQgK8;Kf}U0$DFl0G30t*UjxNNe}mgL8vi_IS~#`D>kD)fyq3s^`T~>B zK(^36%rTR^o5Ca5cSqn~3oSXWuR=!|Hg>x-62?w?jvT(@P ztQzsvmkkc$ly<#qpS0V7xpDp^nRmU1&^@Dgw(=nAe?CxfFn-`CVOB90ns+Ef;;yG@ zG`X69EF@GQ(Ih}C7Wi9p4GAz&K{^YFbM^{g*FYAiZm2Tl#oA=W7PEuP`-j)ST?cUp zOFCc=gQyo&m^lKbEWzQURGIWB>JJ_&+);wBnD`fptpJ}gP<)j4MrvIKZh~Yl6JJ(= zXQ}zM$QC@y_}Tuc{X>wS}sUA7eqUWR28Or1t_v50Zn65Q$EU8UX0DvEvH~!RIyS0x)Lo8lT>sPhVOcnEvu5 z*w6DaC?L5^K_G7Fdt~^K?^A-UKorX1Ub?^8D82fuXk40GVS6o z{V$mfM3?p7v@jw3@3a8O!CJAYVN)f}Xz+^GMDB{tRBbN6I0h^flb#vu3oMQL_tb=r zXhnanjsthiQ()x|QW7mm#}Pz1%If%Hj!LWs?1z{@OclBitOP_xQKeuVxjMD~_>7?o zxo;D-X9I)+dKtj_;+gnqjKJ}1U z{{iX9gSK1`pPueDu=!CL-!wVAl;yWS!m>R=Ags%!WL<)6JZ5rTE#(B;ohJtEu6lYb zpac?!Em)B9h3qx(QLbv2jCPy!8~|twq)BS3H}DfEQY6q22=Nefra!2^yRk~9s90t= z1)|Ow`HB11RkG_|S}H>|4NRdR|NV+&IdV+zoGK^7d@_JI?=r#y&eKUa3ScHfFLY+T zJ$J|h@dC``oa&>s^S#3M0 Date: Fri, 12 Jun 2026 10:33:39 -0400 Subject: [PATCH 4/5] docs: add mutatorIcon to mutators doc --- .../docs/docs/guides/create-custom-blocks/mutators.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/packages/docs/docs/guides/create-custom-blocks/mutators.mdx b/packages/docs/docs/guides/create-custom-blocks/mutators.mdx index 1e4c910d34d..74ecf07968a 100644 --- a/packages/docs/docs/guides/create-custom-blocks/mutators.mdx +++ b/packages/docs/docs/guides/create-custom-blocks/mutators.mdx @@ -326,3 +326,13 @@ var helper = function () { [shareable-procedures]: https://www.npmjs.com/package/@blockly/block-shareable-procedures [serializer]: /guides/configure/serialization#serializer-hooks + +### MutatorIcon class + +Blockly's default mutator UI is implemented in the `MutatorIcon` class. In most +cases, you can use the default mutator UI that Blockly provides or create your +own custom UI without instantiating `MutatorIcon` directly. If you are extending +Blockly itself to add new mutator features, you might want to extend the +`MutatorIcon` class, but note that this will not always be needed. You can +look at the [MutatorIcon](https://docs.blockly.com/reference/blockly.icons_namespace.mutatoricon_class/#iconsmutatoricon-class) +reference documentation for more details about this class. \ No newline at end of file From 954ec304a8aed0e252577f10bd3f209db1204788 Mon Sep 17 00:00:00 2001 From: zspriggs Date: Fri, 12 Jun 2026 14:53:13 -0400 Subject: [PATCH 5/5] docs: fix phrasing and aria label --- .../create-custom-blocks/define/extensions.mdx | 16 ++++++++-------- .../guides/create-custom-blocks/mutators.mdx | 12 ++++++------ 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/packages/docs/docs/guides/create-custom-blocks/define/extensions.mdx b/packages/docs/docs/guides/create-custom-blocks/define/extensions.mdx index 67a8a0fa7e7..8967cc0365d 100644 --- a/packages/docs/docs/guides/create-custom-blocks/define/extensions.mdx +++ b/packages/docs/docs/guides/create-custom-blocks/define/extensions.mdx @@ -91,21 +91,21 @@ extension. ``` ### Mutators -Mutators are a type of mixin that allow you to add extra details about the state -of a block. If the full state of your block that can't be captured by the +Mutators are a type of mixin that allow you to add state to a block, especially +when the state can't be represented using the block's standard fields or +properties. If the full state of your block that can't be captured by the block's existing properties, you may need a mutator. By default, Blockly represents mutators with a small gear icon on the block. When the user clicks the icon, a mutator UI and the user can select options that affect the shape and/or behavior of the block. -For instance, the builtin ```list_create_with``` block uses a mutator. The -mutator allows for the user to change the shape of the block and allows the -block to keep track of how many items are in the list. +For instance, the built-in `list_create_with` block uses a mutator. The +mutator tracks the item count of the list and updates the shape accordingly. -![A list_create_with block with its mutator bubble open. This lets users add -more items to the list.](/images/list-create-with-mutator.png) +![A list_create_with block with its mutator bubble open, with red arrows and +text that identify the dialog button and the mutator UI bubble.](/images/list-create-with-mutator.png) -When you create a mutator, you'll need to define the certain functions that +When you create a mutator, you define the certain functions that specify how the mutator should serialize and deserialize the state of the block, as well as how the mutator should compose and decompose the block's shape in the UI. As with any mixin, you'll also need to register the mutator before you can diff --git a/packages/docs/docs/guides/create-custom-blocks/mutators.mdx b/packages/docs/docs/guides/create-custom-blocks/mutators.mdx index 74ecf07968a..5239ee86d41 100644 --- a/packages/docs/docs/guides/create-custom-blocks/mutators.mdx +++ b/packages/docs/docs/guides/create-custom-blocks/mutators.mdx @@ -299,7 +299,7 @@ Blockly.Extensions.registerMutator( defined. Note that unlike extensions, each block type may only have one mutator. Once you -have registered your mutator, you can add it to your block's JSON definition. +have registered your mutator, you can add it to a block's JSON definition. ```js { @@ -329,10 +329,10 @@ var helper = function () { ### MutatorIcon class -Blockly's default mutator UI is implemented in the `MutatorIcon` class. In most -cases, you can use the default mutator UI that Blockly provides or create your -own custom UI without instantiating `MutatorIcon` directly. If you are extending +`MutatorIcon` manages the bubble for Blockly's default mutator UI when a mutator +is defined for a block. You don't have to instantiate `MutatorIcon` directly to +use the default mutator UI or to make a custom mutator UI. If you are extending Blockly itself to add new mutator features, you might want to extend the -`MutatorIcon` class, but note that this will not always be needed. You can -look at the [MutatorIcon](https://docs.blockly.com/reference/blockly.icons_namespace.mutatoricon_class/#iconsmutatoricon-class) +`MutatorIcon` class, but note that this will not always be needed. See the +[MutatorIcon](https://docs.blockly.com/reference/blockly.icons_namespace.mutatoricon_class/#iconsmutatoricon-class) reference documentation for more details about this class. \ No newline at end of file