Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions docs/blocks/grid-picker.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
4 changes: 4 additions & 0 deletions localtypings/pxtpackage.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string[]>;
}

interface JRes {
Expand All @@ -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'
Expand Down
12 changes: 5 additions & 7 deletions pxtblocks/loader.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string[]> = {};
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)
}
Expand All @@ -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
Expand Down Expand Up @@ -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<string[]> = {};
syms.forEach(symbol => optionTags[symbol.qName] = getSymbolPickerTags(info, symbol));
const options = {
data: dd,
colour: color,
Expand Down Expand Up @@ -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);
}
Expand Down
3 changes: 2 additions & 1 deletion pxtcompiler/emitter/decompiler.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2412,7 +2412,8 @@ ${output}</xml>`;

// 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);
Expand Down
3 changes: 2 additions & 1 deletion pxtcompiler/emitter/snippets.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
7 changes: 4 additions & 3 deletions pxtlib/package.ts
Original file line number Diff line number Diff line change
Expand Up @@ -272,7 +272,7 @@ namespace pxt {
parseJRes(allres: Map<JRes> = {}) {
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
Expand Down Expand Up @@ -1483,7 +1483,7 @@ namespace pxt {
}
}

export function inflateJRes(js: Map<JRes>, allres: Map<JRes> = {}) {
export function inflateJRes(js: Map<JRes>, allres: Map<JRes> = {}, packageName?: string) {
let base: JRes = js["*"] || {} as any
for (let k of Object.keys(js)) {
if (k == "*") continue
Expand Down Expand Up @@ -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
}
}

Expand Down
64 changes: 64 additions & 0 deletions pxtlib/spriteutils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -479,6 +479,70 @@ namespace pxt.sprite {
]);
}

type GridPickerAssetTags = globalThis.Map<string, string[]>;
const gridPickerAssetTags = new WeakMap<pxtc.ApisInfo, globalThis.Map<string, GridPickerAssetTags>>();

/**
* 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<string, string[]>();
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<string[]> {
const result: pxt.Map<string[]> = {};
Expand Down
18 changes: 18 additions & 0 deletions tests/blocklycompiler-test/test-library/enums.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
21 changes: 21 additions & 0 deletions tests/blocklycompiler-test/test-library/pickers.jres
Original file line number Diff line number Diff line change
@@ -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"] }]
}
}
}
1 change: 1 addition & 0 deletions tests/blocklycompiler-test/test-library/pxt.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
"files": [
"actionEvent.ts",
"enums.ts",
"pickers.jres",
"mbit.ts",
"expandableBlocks.ts",
"spritekind.ts",
Expand Down
11 changes: 10 additions & 1 deletion tests/blocklycompiler-test/test.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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);
Expand All @@ -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 = [
Expand Down
47 changes: 44 additions & 3 deletions tests/pxt-editor-test/editorrunner.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
Expand All @@ -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 = [
Expand Down
Loading