fix(docs): correct invalid allOf catalog composition examples (#2219)

[sanjayrohith]

Fixes #2219

Problem

docs/public/concepts/catalogs.md documents catalog composition with an allOf array placed directly under components:

"components": {
  "allOf": [
    {"$ref": "basic_catalog_definition.json#/components"},
    {"SuggestionChips": { ... }}
  ]
}

Per specification/v1_0/json/catalog_definition.json, components is an object whose additionalProperties must each be a ComponentDefinition (a JSON Schema). allOf is therefore read as a component named allOf whose schema is an array — which is not a valid schema.

This is not just cosmetically wrong. Running the documented input through the repo's own linker, tools/build_catalog/assemble_catalog.py, produces a broken catalog:

components keys: ['allOf']
$defs.anyComponent: {"oneOf": [{"$ref": "#/components/allOf"}], "discriminator": {"propertyName": "component"}}

Neither Text nor Popup survives. The assembler's _merge_categories copies source["components"] keys verbatim, so allOf becomes the only "component" in the output and anyComponent points at an array.

Two secondary issues in the same examples:

1. The cherry-picking example referenced catalogs/basic/catalog.json#/components/Text. _process_ref special-cases any ref whose filename is catalog.json and rewrites it to the assembled catalog root, so this collapses to a self-referential {"$ref": "#/components/Text"} instead of importing the Basic Catalog's Text. Verified:

   components.Text -> {"$ref": "#/components/Text"}
   

   The name the assembler actually intercepts is basic_catalog.json (see INTERCEPT_MAP).

2. The surrounding "Catalog Linking" section pointed readers at a Node.js script, register-catalogs.js, wrapped in Xcode Build Phases / Gradle tasks. That script does not exist anywhere in the repository — register-catalogs appears only in this one doc file. The tool that actually performs linking is tools/build_catalog/assemble_catalog.py.

Changes

docs/public/concepts/catalogs.md

• Rewrote both composition examples to use valid components syntax.
  • Extending the Basic Catalog: a catalog cannot inline another catalog's whole components map, so the example now declares only the new component and pulls in the Basic Catalog at link time via --extend-basic-catalog.
  • Cherry-picking Components: imports are now $refs keyed under each component's own name, and the ref target is basic_catalog.json#/components/Text.
• Added the concrete assemble_catalog.py invocation under each example, replacing the register-catalogs.js instruction lines.
• Updated the "Catalog Linking" section to name the real tool. The Xcode Build Phase / Gradle task guidance is kept as advice on where to run the linking step, rather than a claim that a wrapper ships today.

tools/build_catalog/README.md

• The tool's own README carried the identical invalid allOf-under-components example. Corrected it to the same valid form and added the required catalogId.

Verification

Both corrected forms were run through assemble_catalog.py:

$ uv run tools/build_catalog/assemble_catalog.py hello_world_with_some_basic.json \
    --output-name hello_world_with_some_basic
components: ['Text', 'Popup']
anyComponent: {"oneOf": [{"$ref": "#/components/Popup"}, {"$ref": "#/components/Text"}], ...}
$defs: [... 'basic_catalog_Text', 'common_types_ComponentId', 'theme']

$ uv run tools/build_catalog/assemble_catalog.py hello_world_with_all_basic.json \
    --output-name hello_world_with_all_basic --extend-basic-catalog
components: ['Text', 'Image', 'Icon', 'Video', 'AudioPlayer', 'Row', 'Column', 'List',
             'Card', 'Tabs', 'Modal', 'Divider', 'Button', 'TextField', 'CheckBox',
             'ChoicePicker', 'Slider', 'DateTimeInput', 'SuggestionChips']

The corrected examples also validate against the components shape defined in specification/v1_0/json/catalog_definition.json, while the previous ones do not.

npx prettier --check passes on both edited files.

Note for reviewers

Item 2 above (register-catalogs.js → assemble_catalog.py) is adjacent to the filed issue. I included it because those instruction lines are attached directly to the two examples being fixed, and leaving them would have pointed readers at a nonexistent tool for making the corrected examples work. Happy to split it into a separate PR if you'd prefer to keep this one strictly scoped.

[gemini-code-assist]

Code Review

This pull request updates the documentation in docs/public/concepts/catalogs.md and tools/build_catalog/README.md to reflect the transition from the Node.js register-catalogs.js script to the Python-based assemble_catalog.py tool. It also updates the JSON schema composition examples to use direct component keys instead of allOf. The reviewer suggested using a relative path instead of an absolute GitHub URL for the tool's documentation link to ensure it remains functional across forks and branches.

[gemini-code-assist]

To maintain consistency with other links in this document and to ensure the link remains functional across forks or branches, please use a relative path instead of an absolute GitHub URL.

Suggested change

	To automate bundling and registering these external file references, this catalog registration process is called **"Linking"** and is performed by [`tools/build_catalog/assemble_catalog.py`](https://github.com/a2ui-project/a2ui/blob/main/tools/build_catalog/README.md). It resolves local and remote `$ref`s, merges multiple input catalogs, and emits a single freestanding catalog:
	To automate bundling and registering these external file references, this catalog registration process is called **"Linking"** and is performed by [`tools/build_catalog/assemble_catalog.py`](../../../tools/build_catalog/README.md). It resolves local and remote `$ref`s, merges multiple input catalogs, and emits a single freestanding catalog:

[polina-c]

@jacobsimionato , would you mind to review?