diff --git a/docs/blocks/grid-picker.md b/docs/blocks/grid-picker.md index 96d409c744cd..bf95708aa984 100644 --- a/docs/blocks/grid-picker.md +++ b/docs/blocks/grid-picker.md @@ -51,6 +51,45 @@ Or add them to the choice's entry in its JRES file: Tags from both places are combined, so you can use whichever is more convenient. +### Tagging choices from another package + +**Use case:** your `my-mounts` extension wants a picker for horses and donkeys +from Minecraft without changing the target's mob definitions. + +Add an `assetTags` map inside a `gridPickerCatalog`: + +```json +{ + "*": { + "namespace": "myMounts.pickers", + "mimeType": "application/x-makecode-grid-picker" + }, + "animals": { + "gridPickerCatalog": { + "name": "Animals", + "assetTags": { + "AnimalMob.Horse": ["mount"], + "AnimalMob.Donkey": ["mount"] + }, + "tabs": [ + { "id": "mounts", "name": "Mounts", "tags": ["my-mounts:mount"] }, + { "id": "all", "name": "All", "flat": true } + ] + } + } +} +``` + +The keys can be qualified API names, constants with an `enumIdentity`, or +existing JRES IDs. Write the tag without a prefix in `assetTags`; MakeCode adds +the extension's dependency name and a colon. Use the full tag +`my-mounts:mount` in tabs, groups, or `fieldOptions.filter` on a block using +`myMounts.pickers.animals` or another catalog from `my-mounts`. + +These tags are shared by the catalogs from the same extension. They don't +change the source assets or what another extension's catalogs see. If a +constant or asset can't be found, MakeCode skips it and writes a console warning. + ## Using a catalog in a block **Use case:** a Minecraft block that should only offer mobs that can ride, while @@ -225,6 +264,10 @@ Detailed behavior and edge cases, mainly for contributors and automated agents. - API `tags` and JRES `tags` are merged case-insensitively. JRES references and aliases resolve tags the same way they resolve icons. - When adding tags to an existing JRES entry, keep its icon and data properties. +- Catalog `assetTags` add picker-only tags from the catalog's owning package. + The package loader provides the prefix; it isn't read from the JRES entry. + A `?tag` becomes `?package:tag`, so it still works with shared tag filters. + Decompilation and generated snippets use the same tags as the picker. ### Filters and values diff --git a/localtypings/pxtpackage.d.ts b/localtypings/pxtpackage.d.ts index 1145a10fc8cc..4bf9989ad717 100644 --- a/localtypings/pxtpackage.d.ts +++ b/localtypings/pxtpackage.d.ts @@ -229,6 +229,8 @@ declare namespace pxt { tabs: GridPickerCategory[]; groups?: GridPickerCategory[]; filters?: GridPickerCategory[]; + /** Extra tags keyed by a qualified symbol name, constant alias, or JRES ID. */ + assetTags?: Map; } interface JRes { @@ -244,6 +246,8 @@ declare namespace pxt { tags?: string[]; weight?: number; gridPickerCatalog?: GridPickerCatalog; + /** Set by the package loader, not by authored JRES. */ + gridPickerCatalogOwner?: string; } type SnippetOutputType = 'blocks' diff --git a/pxtblocks/loader.ts b/pxtblocks/loader.ts index 94cdcda3c203..7ca38afb7572 100644 --- a/pxtblocks/loader.ts +++ b/pxtblocks/loader.ts @@ -529,9 +529,13 @@ function initBlock(block: Blockly.Block, info: pxtc.BlocksInfo, fn: pxtc.SymbolI if (syms.length == 0) { pxt.error(`no instances of ${typeInfo?.qName || fieldType} found`) } + const catalog = customField === "gridpicker" && typeof fieldOptions?.catalog === "string" ? fieldOptions.catalog : undefined; + const optionTags: pxt.Map = {}; const dd: Blockly.MenuOption[] = syms.map(v => { let k = v.attributes.block || v.attributes.blockId || v.name; let comb = v.attributes.blockCombine + const tags = pxt.sprite.getGridPickerSymbolTags(info.apis, v, catalog).map(tag => tag.toLowerCase()); + optionTags[v.qName] = tags; if (v.attributes.jresURL && !v.attributes.iconURL && pxt.Util.startsWith(v.attributes.jresURL, "data:image/x-mkcd-f")) { v.attributes.iconURL = imgConv.convert(v.attributes.jresURL) } @@ -544,7 +548,7 @@ function initBlock(block: Blockly.Block, info: pxtc.BlocksInfo, fn: pxtc.SymbolI width: 36, height: 36, value: v.name, - tags: getSymbolPickerTags(info, v) + tags } : k, v.namespace + "." + v.name, v.attributes.ariaLabel @@ -576,8 +580,6 @@ function initBlock(block: Blockly.Block, info: pxtc.BlocksInfo, fn: pxtc.SymbolI if (customField) { let defl = resolveDefault(fn.attributes.paramDefl[actName] || ""); - const optionTags: pxt.Map = {}; - syms.forEach(symbol => optionTags[symbol.qName] = getSymbolPickerTags(info, symbol)); const options = { data: dd, colour: color, @@ -1047,10 +1049,6 @@ function applyInputLabel(input: Blockly.Input, parameter: pxt.blocks.BlockParame input.setAriaLabelProvider(label); } -function getSymbolPickerTags(info: pxtc.BlocksInfo, symbol: pxtc.SymbolInfo): string[] { - return pxt.sprite.getSymbolTags(info.apis, symbol).map(tag => tag.toLowerCase()); -} - export function getFixedInstanceDropdownValues(apis: pxtc.ApisInfo, qName: string): pxtc.SymbolInfo[] { return pxt.blocks.getFixedInstanceDropdownValues(apis, qName); } diff --git a/pxtcompiler/emitter/decompiler.ts b/pxtcompiler/emitter/decompiler.ts index 4ac4409da6ff..fe2d0e80af40 100644 --- a/pxtcompiler/emitter/decompiler.ts +++ b/pxtcompiler/emitter/decompiler.ts @@ -2412,7 +2412,8 @@ ${output}`; // An out-of-filter value keeps its ordinary block, rather than being forced into this picker. const filter = field.fieldOptions?.filter; - if (typeof filter === "string" && !pxt.sprite.compileTagFilter(filter)(pxt.sprite.getSymbolTags(apis, member))) { + const catalog = typeof field.fieldOptions?.catalog === "string" ? field.fieldOptions.catalog : undefined; + if (typeof filter === "string" && !pxt.sprite.compileTagFilter(filter)(pxt.sprite.getGridPickerSymbolTags(apis, member, catalog))) { return undefined; } return getFieldBlock(U.htmlEscape(shadow.attributes.blockId), U.htmlEscape(field.definitionName), member.qName); diff --git a/pxtcompiler/emitter/snippets.ts b/pxtcompiler/emitter/snippets.ts index 72cadda98803..c17fcba9d93b 100644 --- a/pxtcompiler/emitter/snippets.ts +++ b/pxtcompiler/emitter/snippets.ts @@ -470,8 +470,9 @@ namespace ts.pxtc.service { } const filter = typeof param.fieldOptions?.filter === "string" ? param.fieldOptions.filter : undefined; + const catalog = typeof param.fieldOptions?.catalog === "string" ? param.fieldOptions.catalog : undefined; const matches = pxt.sprite.compileTagFilter(filter); - let choice = choices.find(symbol => matches(pxt.sprite.getSymbolTags(apis, symbol))); + let choice = choices.find(symbol => matches(pxt.sprite.getGridPickerSymbolTags(apis, symbol, catalog))); if (!choice) { pxt.reportError("gridpicker", "No matching default choice", { api: fn.qName, parameter: param.actualName }); // Match the block, which starts on its first choice when none fit the filter. diff --git a/pxtlib/package.ts b/pxtlib/package.ts index d67982bf8add..f1e1c3e8fff8 100644 --- a/pxtlib/package.ts +++ b/pxtlib/package.ts @@ -272,7 +272,7 @@ namespace pxt { parseJRes(allres: Map = {}) { for (const f of this.getFiles()) { if (U.endsWith(f, ".jres")) { - inflateJRes(JSON.parse(this.readFile(f)), allres) + inflateJRes(JSON.parse(this.readFile(f)), allres, this.id === "this" ? this.config.name : this.id) } } return allres @@ -1483,7 +1483,7 @@ namespace pxt { } } - export function inflateJRes(js: Map, allres: Map = {}) { + export function inflateJRes(js: Map, allres: Map = {}, packageName?: string) { let base: JRes = js["*"] || {} as any for (let k of Object.keys(js)) { if (k == "*") continue @@ -1513,7 +1513,8 @@ namespace pxt { tileset: v.tileset, tags: v.tags, weight: v.weight, - gridPickerCatalog: v.gridPickerCatalog + gridPickerCatalog: v.gridPickerCatalog, + gridPickerCatalogOwner: v.gridPickerCatalog ? packageName : undefined } } diff --git a/pxtlib/spriteutils.ts b/pxtlib/spriteutils.ts index b657ad394aa1..771bfcfe64ab 100644 --- a/pxtlib/spriteutils.ts +++ b/pxtlib/spriteutils.ts @@ -479,6 +479,70 @@ namespace pxt.sprite { ]); } + type GridPickerAssetTags = globalThis.Map; + const gridPickerAssetTags = new WeakMap>(); + + /** + * Adds the tags declared by the package that supplies the catalog, without changing the + * symbol or its JRES entry. Other catalogs and asset galleries still see the original tags. + */ + export function getGridPickerSymbolTags(apis: pxtc.ApisInfo, symbol: pxtc.SymbolInfo, catalogId?: string): string[] { + const tags = getSymbolTags(apis, symbol); + const owner = catalogId && apis.jres?.[catalogId]?.gridPickerCatalogOwner; + if (!owner || !symbol) return tags; + + let byOwner = gridPickerAssetTags.get(apis); + if (!byOwner) gridPickerAssetTags.set(apis, byOwner = new Map()); + let assetTags = byOwner.get(owner); + if (!assetTags) byOwner.set(owner, assetTags = collectGridPickerAssetTags(apis, owner)); + if (!assetTags.size) return tags; + + const symbolTags = assetTags.get(symbol.qName); + const resourceTags = assetTags.get(getSymbolResource(apis, symbol)?.id); + return symbolTags || resourceTags ? parseTags([...tags, ...(symbolTags || []), ...(resourceTags || [])]) : tags; + } + + function collectGridPickerAssetTags(apis: pxtc.ApisInfo, owner: string): GridPickerAssetTags { + const result = new Map(); + for (const catalog of Object.values(apis.jres || {})) { + if (catalog.gridPickerCatalogOwner !== owner) continue; + const entries = catalog.gridPickerCatalog?.assetTags; + if (entries === undefined) continue; + if (!entries || typeof entries !== "object" || Array.isArray(entries) || /[!?:\s]/.test(owner)) { + pxt.warn(`Grid picker catalog "${catalog.id}": invalid assetTags or package name.`); + continue; + } + + for (const [reference, values] of Object.entries(entries)) { + const symbol = Object.prototype.hasOwnProperty.call(apis.byQName, reference) ? apis.byQName[reference] : undefined; + const identity = symbol?.attributes.enumIdentity; + const target = identity + ? (Object.prototype.hasOwnProperty.call(apis.byQName, identity) ? apis.byQName[identity]?.qName : undefined) + : symbol?.qName || (Object.prototype.hasOwnProperty.call(apis.jres, reference) ? reference : undefined); + if (!target) { + pxt.warn(`Grid picker catalog "${catalog.id}": assetTags references unknown asset or constant "${reference}".`); + continue; + } + if (!Array.isArray(values) || !values.every(tag => typeof tag === "string")) { + pxt.warn(`Grid picker catalog "${catalog.id}": expected a list of tags for "${reference}".`); + continue; + } + + const extraTags: string[] = []; + for (const tag of parseTags(values)) { + if (!/^\??[^!?:\s]+$/.test(tag)) { + pxt.warn(`Grid picker catalog "${catalog.id}": invalid asset tag "${tag}" for "${reference}".`); + continue; + } + // The optional marker must stay before the prefix for the shared tag filter. + extraTags.push(tag.startsWith("?") ? `?${owner}:${tag.slice(1)}` : `${owner}:${tag}`); + } + if (extraTags.length) result.set(target, parseTags([...(result.get(target) || []), ...extraTags])); + } + } + return result; + } + /** Indexes merged API/resource tags for both symbolic and gallery resource IDs. */ export function getSymbolTagsById(apis: pxtc.ApisInfo): pxt.Map { const result: pxt.Map = {}; diff --git a/tests/blocklycompiler-test/test-library/enums.ts b/tests/blocklycompiler-test/test-library/enums.ts index 517a4ef0d449..193f66668dac 100644 --- a/tests/blocklycompiler-test/test-library/enums.ts +++ b/tests/blocklycompiler-test/test-library/enums.ts @@ -172,6 +172,24 @@ namespace pickerTest { //% choice.fieldOptions.enumNames="PickerAnimal" export function chooseAlias(value: number): void { } + + //% blockId=picker_choose_featured block="featured %choice" + //% value.fieldEditor=gridpicker + //% choice.fieldOptions.catalog=testlib.pickers.animals + //% choice.fieldOptions.enumNames="PickerAnimal" choice.fieldOptions.filter="testlib:featured" + export function chooseFeatured(value: number): void { + } + + //% blockId=picker_featured_shadow block="$value" shim=TD_ID blockHidden=1 + //% value.fieldEditor=gridpicker + //% value.fieldOptions.catalog=testlib.pickers.animals value.fieldOptions.filter="testlib:featured" + export function featured(value: PickerAnimal): number { + return value; + } + + //% blockId=picker_use_featured block="use featured $animal" animal.shadow=picker_featured_shadow + export function useFeatured(animal: number): void { + } } declare namespace agent { diff --git a/tests/blocklycompiler-test/test-library/pickers.jres b/tests/blocklycompiler-test/test-library/pickers.jres new file mode 100644 index 000000000000..3830d71496d9 --- /dev/null +++ b/tests/blocklycompiler-test/test-library/pickers.jres @@ -0,0 +1,21 @@ +{ + "*": { + "namespace": "testlib.pickers", + "mimeType": "application/x-makecode-grid-picker" + }, + "tags": { + "gridPickerCatalog": { + "name": "Tagged animals", + "assetTags": { + "PICKER_COW": ["featured"] + }, + "tabs": [{ "id": "all", "name": "All", "flat": true }] + } + }, + "animals": { + "gridPickerCatalog": { + "name": "Animals", + "tabs": [{ "id": "featured", "name": "Featured", "tags": ["testlib:featured"] }] + } + } +} diff --git a/tests/blocklycompiler-test/test-library/pxt.json b/tests/blocklycompiler-test/test-library/pxt.json index 52fa3837749d..b80492783652 100644 --- a/tests/blocklycompiler-test/test-library/pxt.json +++ b/tests/blocklycompiler-test/test-library/pxt.json @@ -4,6 +4,7 @@ "files": [ "actionEvent.ts", "enums.ts", + "pickers.jres", "mbit.ts", "expandableBlocks.ts", "spritekind.ts", diff --git a/tests/blocklycompiler-test/test.spec.ts b/tests/blocklycompiler-test/test.spec.ts index d6e3e3854002..b9cb70eb305d 100644 --- a/tests/blocklycompiler-test/test.spec.ts +++ b/tests/blocklycompiler-test/test.spec.ts @@ -585,7 +585,7 @@ describe("blockly compiler", function () { it("should generate picker snippets that compile back through their dropdown fields", async () => { const { program, info } = await decompilePickerSource(""); const checker = program.getTypeChecker(); - for (const qName of ["pickerTest.chooseMount", "pickerTest.chooseItem", "pickerTest.chooseAsset"]) { + for (const qName of ["pickerTest.chooseMount", "pickerTest.chooseItem", "pickerTest.chooseAsset", "pickerTest.chooseFeatured"]) { let declaration: ts.FunctionDeclaration; const visit = (node: ts.Node) => { if (ts.isFunctionDeclaration(node) && node.name) { @@ -599,6 +599,7 @@ describe("blockly compiler", function () { const snippet = pxtc.service.snippetStringify(pxtc.service.getSnippet({ apis: info.apis, blocksInfo: info, checker, takenNames: {} }, info.apis.byQName[qName], declaration)); + if (qName === "pickerTest.chooseFeatured") chai.assert.include(snippet, "PickerAnimal.Cow"); const restored = await roundTripPickerSource(snippet); chai.assert.deepEqual(sourceCalls(restored), sourceCalls(snippet), snippet + "\n=>\n" + restored); const { result } = await decompilePickerSource(snippet); @@ -616,6 +617,14 @@ describe("blockly compiler", function () { } }); + it("should decompile a value allowed by another catalog from the same package into the filtered shadow", async () => { + const { result } = await decompilePickerSource("pickerTest.useFeatured(PickerAnimal.Cow)"); + chai.assert.isTrue(result.success, JSON.stringify(result.diagnostics)); + const xml = Blockly.utils.xml.textToDom(result.outfiles[pxt.MAIN_BLOCKS]); + const field = xml.querySelector('block[type="picker_use_featured"] > value > shadow[type="picker_featured_shadow"] > field'); + chai.assert.equal(field?.textContent, "PickerAnimal.Cow"); + }); + it("should round trip configured gridpicker enum sources and resolved parameter names", async () => { await getBlocksInfoAsync(); const source = [ diff --git a/tests/pxt-editor-test/editorrunner.ts b/tests/pxt-editor-test/editorrunner.ts index 6728eb5ce505..46b41e50a7c4 100644 --- a/tests/pxt-editor-test/editorrunner.ts +++ b/tests/pxt-editor-test/editorrunner.ts @@ -106,12 +106,19 @@ describe("library-owned picker catalogs", () => { dep.isLoaded = true; files[id] = { "pickers.jres": JSON.stringify({ "*": { namespace: `${id}.pickers`, mimeType: "application/x-makecode-grid-picker" }, - icons: { gridPickerCatalog: { + icons: { gridPickerCatalogOwner: "alpha", gridPickerCatalog: { name: "Images", tabs: [{ id: "all", name: "All", flat: true, weight: 0 }, { id: "animals", name: "Animals", tags: ["animal"], weight: 80 }], groups: [{ id: "birds", name: "Birds", tags: ["bird"] }], - filters: [{ id: "playable", name: "Playable", tags: ["playable"] }] - } } + filters: [{ id: "playable", name: "Playable", tags: ["playable"] }], + assetTags: id === "alpha" ? { + "TEST_HORSE": ["mount", "MOUNT"], + "animals.Horse": ["wild"], + "assets.horse": ["?favorite"], + "Missing.Constant": ["mount"] + } : { "animals.Horse": ["mount"] } + } }, + more: { gridPickerCatalog: { name: "More", tabs: [{ id: "all", name: "All", flat: true }] } } }) }; main.deps[id] = dep; } @@ -126,6 +133,40 @@ describe("library-owned picker catalogs", () => { chai.expect(Object.keys(resources)).contains("alpha.pickers.icons").and.contains("beta.pickers.icons"); }); + it("shares namespaced tags across the owner's catalogs and warns without failing on unknown references", () => { + const jres = catalogPackage().getJRes(); + jres["assets.horse"] = { id: "assets.horse", data: "", mimeType: "image/png", tags: ["animal"] }; + const horse: pxtc.SymbolInfo = { + kind: pxtc.SymbolKind.EnumMember, qName: "animals.Horse", name: "Horse", namespace: "animals", + fileName: "animals.ts", parameters: [], retType: "animals", + attributes: { callingConvention: 0, paramDefl: {}, jres: "assets.horse", tags: "tameable" } + }; + const alias: pxtc.SymbolInfo = { + ...horse, qName: "TEST_HORSE", name: "TEST_HORSE", kind: pxtc.SymbolKind.Variable, + attributes: { callingConvention: 0, paramDefl: {}, enumIdentity: horse.qName } + }; + const apis: pxtc.ApisInfo = { jres, byQName: { [horse.qName]: horse, [alias.qName]: alias } }; + const tags = (id?: string) => pxt.sprite.getGridPickerSymbolTags(apis, horse, id); + + const warnings: string[] = []; + const warn = console.warn; + console.warn = (message: string) => warnings.push(message); + try { + const alpha = ["tameable", "animal", "alpha:mount", "alpha:wild", "?alpha:favorite"]; + chai.expect(tags("alpha.pickers.icons")).deep.equals(alpha); + chai.expect(tags("alpha.pickers.more")).deep.equals(alpha); + chai.expect(tags("beta.pickers.icons")).deep.equals(["tameable", "animal", "beta:mount"]); + chai.expect(tags()).deep.equals(["tameable", "animal"]); + chai.expect(jres["assets.horse"].tags).deep.equals(["animal"]); + chai.expect(pxt.sprite.compileTagFilter("alpha:mount alpha:favorite")(alpha)).equals(true); + chai.expect(pxt.sprite.compileTagFilter("mount")(alpha)).equals(false); + chai.expect(warnings).to.have.length(1); + chai.expect(warnings[0]).to.include("Missing.Constant"); + } finally { + console.warn = warn; + } + }); + describe("picker weight ordering", () => { it("uses descending toolbox-style weights with stable default priorities", () => { const items = [