Skip to content

Xplat docs xplat json snippet support and refactor and automated docs testing - #497

Open
gmurray81 wants to merge 183 commits into
vnextfrom
docs/json-snippets
Open

gmurray81 wants to merge 183 commits into
vnextfrom
docs/json-snippets

Conversation

@gmurray81

Copy link
Copy Markdown
Member

Closes #

Checklist:

  • check topic's TOC/menu and paragraph headings
  • Include TOC topic labels in the topic content when it has a valuable update, is new, or is considered preview / beta
  • link to other topics using ./page.mdx or ../relative/path.mdx (.mdx extension required)
  • at the References section at the end of the topic add links to topics, samples, etc
  • reference API documentation instead of adding a section with API

  • use valid component names - [Data] Grid, IgxSelectComponent, <igx-combo>
  • use spell checker tool (VS Code, Grammarly, Microsoft Editor)
  • add inline code blocks for the names of classes / tags / properties
  • add language descriptor for the code blocks
  • check if links function by running the check-api/mdx npm commands
  • check if sample is working and fully visible in the topic
  • check if sample is working and fully visible in the StackBlitz
  • check if code blocks match the code in StackBlitz demo
  • add or update meaningful llms.description metadata and run npm run check:llms-metadata


  • do not resolve requested changes (leave that to the reviewer)

gmurray81 and others added 30 commits August 8, 2026 06:07
…ration

A ```json-snippet block holds one sample as JSON and becomes this platform's
markup as the page is generated, replacing the four or five hand written blocks a
topic otherwise carries for the same sample.

Purely additive: every other block is left exactly as it was, so a topic can hold
both forms and a platform specific snippet with no JSON equivalent keeps working.
Verified by generating every platform against the unmodified repo — the platforms
whose blocks were not collapsed come out byte identical.

The emitter is the locally built renderer, loaded through a CommonJS bundle and
only when a page actually contains a json-snippet, so pages without one are
untouched. A failure fails the build rather than publishing a page with a hole
where a sample should be.

Collapses one section of bullet-graph as the first case: three PlatformBlocks and
76 lines become one 22 line block, and Angular, React and Web Components each
come out matching what was there before.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Collapsing a per-platform snippet group into one JSON definition forces a single
answer. Where the platforms already agree that is mechanical; where they differ,
the difference is almost certainly a mistake that has to be fixed first, because
collapsing would otherwise silently pick a winner and change what some platform's
page has always shown.

Compares content rather than dialect: element names, attribute names, quoting and
layout all differ legitimately between platforms, so all of these read the same
and report nothing —

    <igx-bullet-graph minimumValue="5">      <IgrBulletGraph minimumValue={5}>
    <igc-bullet-graph minimum-value="5">     <IgbBulletGraph MinimumValue="5">

It reports when one of them says 55 and the others say 5.

Two things had to be got right before the output meant anything. Only elements
carrying a platform prefix count, so a topic wrapping a sample in a <div> and
XAML's property elements do not shift everything after them. And a group ends
when a platform repeats, not only when prose intervenes: not every sample carries
a block for every platform, and without that a group missing one swallows the
next sample's first block. That alone took the false "different component"
reports from 534 to 86.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…riance

The generator now states the style a documentation snippet is written in — one
line of attributes, no invented element names, and no dimensions on the XAML
platforms — so a sample only says what is particular to it.

The divergence check now sets aside the differences that are expected rather than
wrong:

  * dimensions, which are presentation and now handled by a style option
  * property renames, taken from the vendored apiMap rather than a hand kept
    list, so ItemsSource and dataSource are recognised as one property
  * binding syntax, so {Binding SalesData}, this.state.salesData and SalesData
    are recognised as naming the same thing
  * an absence explained by binding, where the platforms that do write the
    property are binding and another binds in code instead
  * colours and numbers, which the topics pick freely as illustration

What is left is content that says something: a field, a data type, an icon, a
class. 747 differences over 246 groups, down from 2008 over 455 when everything
was reported.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Lining elements up by position made one legitimate difference throw off every
comparison after it. A platform carries an element the others do not — XAML
declares the axes a CategoryChart infers, Angular groups columns in a layout —
and everything past that point was reported as different when only one thing was.
That was what "is a different component" and a bare "element count" were: 169
reports that said nothing usable.

Comparing per component instead says what is actually wrong, and where:

    how many column: Angular: 0, Blazor: 6, WebComponents: 6, React: 9
    column 2 datatype: Blazor: string, React: number

Also splits a platform showing none of a component from the platforms that show
it and disagree about how many. The first is a topic illustrating a feature with
a smaller piece of the sample, which is deliberate; the second is a real
disagreement.

Two further corrections to what the apiMap was doing. A rename was applied
globally, so one type renaming IconName to `name` turned every name attribute in
the docs into an icon — a rename is now ignored when the platform's name is
itself a canonical name elsewhere, or maps to more than one. And the plumbing
attributes are recognised on the name as written, before a rename can disguise
them. Razor's @salesdata now reads as the binding it is.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The product names a web-only description WebGridDescription, WebColumnDescription,
WebDatePickerDescription, while a component shared with the XAML platforms has no
such prefix — DataGridDescription, BulletGraphDescription. The presence of a
Web<Name>Description in the apiMap is therefore the product's own statement that
a component is web only, and those are out of scope: collapsing a group into one
definition pays where the definition serves every platform, and a web-only
component has no XAML counterpart to reconcile against.

That takes the field from 710 groups to 153, and the topics to reconcile from 116
to 49.

Renames are also looked up per component now rather than globally, since a rename
belongs to a type: ItemsSource is written dataSource on some types while
DataSource is a property in its own right on others.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The apiMap cannot answer what a XAML attribute is called canonically: its files
are generated per transpile target and XAML is the canonical side, so there is
nothing there to map from. The description metadata records every platform's name
for a property in one entry, and is the only thing that knows dataSource and
ItemsSource are one property. The check now asks it, through the snippet emitter
it already depends on.

A data source is a special case worth stating: the description carries both
DataSource and DataSourceRef — the value and a reference to a named one — and a
topic writes whichever suits it, XAML almost always the reference and a sample
configuring an inline source the value. They are one concept for comparing, so
the Ref is folded in.

Two things this needed. The metadata is keyed by the description's own casing
while a doc tag arrives lowercased, and a web-only description is also reachable
by its bare name since <igc-grid> canonicalises to "grid" rather than "webgrid".
And a PlatformBlock gates on groups as well as platforms — "Xaml" is not a
platform the metadata knows — so the block's audience is resolved to a member of
its group.

With that, the 25 reports of datagrid's data source splitting into two properties
become 14 real ones.

The apiMap is still what says a description is Web-prefixed, which is what scopes
the check.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… peers

Decides whether a group can become a json-snippet referencing its sample, by
reading each platform's block back into the properties it states, resolving those
to their description names, and comparing each with the sample's value.

A group that is a subset of its sample can be collapsed mechanically: the sample
is provably the source, so the block becomes a reference plus the properties it
illustrates, and the topic stops being able to drift from what it shows. A group
that is not a subset needs a person, and the tool prints every platform's version
so the call is made from what the topic actually says.

Three things had to be right before the answer meant anything. A sample writes
its properties camel cased while a description names them Pascal cased, so
lookups go through a lower cased index. Web Components writes them spinal cased,
so the dashes come out before asking the metadata. And a sample sitting between
two blocks starts a new section — the topics write some platforms, then the
sample, then the rest — which without handling pairs a group with the wrong
sample and makes every property look like a disagreement.

Current reading: 4 collapsible, 56 needing a decision, 138 with no peered sample.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A platform stating the sample's own values settles that the sample is the
scenario the section is about. The others have drifted from it, so the group
collapses to the sample and they come back into line — bullet-graph's measures
section has React and Web Components on the sample's numbers while Blazor is on
an entirely different set and Xaml on a third.

Pairing decides which sample a group belongs to, and direction turned out to be
the wrong axis: a topic's opening sample sits above its first snippet while a
section further down writes the snippets and shows the sample under them. Both
orders occur, so pairing uses the enclosing heading section instead — a section
is about one thing, including its sample. A section with more than one sample is
left unpaired rather than guessed at.

--plan prints what each collapse changes, per platform, so the editorial
consequence is visible before anything is rewritten.

13 groups collapse on this rule, 14 have no platform agreeing with their sample
and need a decision, 171 have no sample in their section.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Splits the unpaired count into its causes: no sample in the section, more than
one, or a sample whose file is not in the examples checkout. The last is the
one that matters — it is not a property of the docs but of which branch of the
examples repo is being read, and the counts move with it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… say

Three pairing rules were wrong before this one. Nearest by distance pairs a group
with the previous section's sample. Looking only backwards, or only forwards,
each mispairs about half, because a topic's opening sample sits above its first
snippet while a section further down shows the sample under them. Sectioning by
heading rejects pairings that are plainly related: of the blocks with a sample
within a screen's distance, more than half have a heading in between.

What actually separates one sample from another is another snippet group, so a
group owns everything between the group before it and the group after. That took
paired groups from 27 to 62.

Where position cannot decide, content can: a sample of the same component that
covers the properties a platform states is likely the one being illustrated.
Matched on which properties are set rather than their values, since values are
exactly what has drifted — a topic states value=70 beside a sample running
value=80, so matching on values finds nothing.

Also adds the fallback to igniteui-wc-examples: a sample missing from the
examples repo but present there is not missing, it is not yet back ported.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Many snippets appear to be written from scratch rather than narrowed from a
sample: for one gauge topic, twenty samples of that component existed and none
set even the same properties, let alone the same values. So requiring agreement
finds nothing, and the useful question is which sample best covers what the
snippet sets, preferring one the topic already shows.

That takes content matches from 3 to 26 and paired groups to 88 of 198.

Reported separately from positional pairing because the quality differs. It gets
the obvious ones right — geo-map-binding-data-csv to the csv sample — and pairs
some confidently wrong: a topic about binding multiple sources matches the csv
sample, because with values excluded the two set the same properties. A wrong
pairing is worse than none when the purpose is to re-anchor a snippet to the
sample's values, so these want confirming rather than applying.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…t the schema

The topic carried five hand-written blocks per section saying the same thing in five
spellings, and they had drifted apart. Nine sections become nine JSON definitions, 1374
lines become 418, and en and jp are collapsed together.

Every XAML block in the topic turned out to have been written from the hero animation
sample rather than each section's own, in all six sections that have one. The XAML in these
topics has never been compiled or run, so where it disagreed with the web platforms the web
platforms won. SNIPPET-COLLAPSE-DECISIONS.md records that and the three sections that did
not collapse trivially.

Generation now emits the JSON schema and checks every json-snippet against the description
it names before writing any output, reporting all the problems at once rather than failing
on the first property the renderer happens to reach.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The topics write isScaleInverted={false}, not "false". Matches how React's numbers were
already handled.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…hows

chart-annotations displays three data-chart samples while every one of its snippets is a
CategoryChart, and the CategoryChart annotation samples it was written from are never
mentioned on the page. Pairing on the embedded <Sample> reported it as needing samples
back-ported from another repo when the JSON was already in this one.

Indexes every sample by the property names it sets, compared without each platform's
spelling, and ranks by how much of the snippet a sample covers. Across the 125 DV snippet
groups, 42 have a sample covering at least 80% of what they set, and 29 of those name a
sample the page never shows.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…n from

Every snippet on the page is a CategoryChart while the three samples it embeds are
DataCharts. The CategoryChart annotation samples the snippets came from are never mentioned
on the page, which is why this topic first looked like it needed samples back-ported from
another repo. The XAML binding to TemperatureAnnotatedData gives it away — that is
annotations-custom's own dataSourceRef.

Two of the three callout member paths named fields that do not exist in the data. Taken from
the running sample.

The XAML callout snippet sat after the Timeline Styling section rather than with the callout
markup it duplicates; folded in. en and jp collapsed together.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The emitter was dropping enum collections on every platform but XAML, so the property the
Callout Layer section describes appeared in no snippet. Now that it emits, it is in the JSON.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…y tool

radial-gauge goes from 1497 lines to 467, ten sections becoming ten JSON definitions in en
and jp together. Same cause as bullet-graph: every XAML block carried the hero animation
sample's values rather than its own section's.

The candidate matcher now prefers a sample of the same component. The gauges share most of
their property names, so a radial gauge section about ranges matched the linear gauge's and
the bullet graph's ranges samples at 100% on properties alone; only the element being shown
says which component the reader is looking at.

mirror-collapse-to-jp.mjs replaces the ad hoc scripts. It walks both copies as ordered
sequences of snippet positions rather than matching fences to groups, which misaligns as
soon as one group in a topic is left hand written — as Dependencies is here — and it refuses
to write at all when the counts disagree, since two copies that have drifted need a person.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1448 lines to 413, nine sections in en and jp together. Six matched their own sample
outright; the three that did not are recorded in SNIPPET-COLLAPSE-DECISIONS.md.

Every XAML block again carried the hero sample's values rather than its section's —
NeedleShape="Needle" where every web platform says Custom, #79797a where they say
DodgerBlue. Third topic in a row, and the same cause each time.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… need code

Both topics carried a bare map plus, for every platform, a code block constructing the
imagery and assigning it to backgroundContent. backgroundContent is an ordinary described
property whose value is another description, so each becomes one JSON with the imagery
nested, and the generated markup needs no code at all.

check-snippet-code-channels.mjs is what makes that claim checkable rather than hopeful. Some
properties cannot be written as an attribute on some platforms — a data source on Web
Components is assigned in script — and a topic showing only markup would then tell the reader
to bind a source without saying where it comes from. The renderer already decides what it
cannot write as an attribute, so the check asks it: 2 of 32 collapsed snippets set something
in code, both Web Components in chart-annotations, and both still have a companion code block
beside them.

The mirror tool now aligns on heading sections rather than snippet positions, since a collapse
often replaces several groups with one JSON, which the positional match refused outright.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…dropped something

Some properties cannot be written as an attribute on some platforms — a data source or a
tooltip template on Web Components is assigned in script — and a topic showing only the
markup leaves that platform's reader with a series bound to nothing. The emitter is what
decided to leave it out, so it is what says a code block is needed: if anything was dropped
it appears, and if nothing was, nothing appears. Angular binds in the template and gets no
block; Web Components gets its two assignments.

What that block shows is the assignments alone, which is what 149 of the 192 code blocks in
the hand written topics show. The 36 that also show how the reference was obtained and the
27 that declare a field are the introductory pages: code="allCode" gets that fuller form,
and code="none" turns it off for a topic that would rather write its own. A ref= fence can
still name a channel explicitly.

geo-map-type-scatter-symbol-series is the first topic collapsed this way: eight hand written
blocks become one definition, and the generated shape matches the original per platform —
one block for Blazor and XAML, two for Web Components.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
bubble series, polygon series, polyline series and the shapefile binding page: 37 hand
written blocks become four definitions, en and jp together. The shape data sources nest
declaratively, so the shapefile and database URLs are in the markup where the topics used
to assign them in code.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ode blocks

Creating Series and Map Background collapse; the shapefile loading and per-record processing
sections stay, since they are handlers rather than configuration.

The collapse found a typo the hand written markup had carried: Web Components wrote
shape-memberPath where the attribute is shape-member-path, so that property had been doing
nothing.

Two faults in the mirror, both found by the Map Background section:

  - it grouped only markup fences, so a section whose blocks are all ts was not seen and the
    snippet was inserted after the blocks it should have replaced, leaving the page with
    both. Seven earlier mirrors had silently left the Japanese copy holding code blocks the
    English one had dropped; those are re-mirrored here from the pre-collapse originals.
  - replacing every group in a collapsed section would have taken the hand written Web
    Components block chart-annotations deliberately keeps. A block the English copy still has
    is now left alone, recognised by its body, since only the prose is translated.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Data aggregations matched its sample outright. Its initialGroups and initialSummaries now
read Country and Sum(Sales) as Sales, from the sample, where the page wrote them lowercase;
the sample is what runs against the data.

The overlay text section had Web Components and XAML declaring a DataAnnotationSliceLayer
and Blazor building the same thing in a method with three styling properties the other two
did not show. Collapsed to the union, so every platform now shows the border thickness,
border radius and padding that only Blazor had.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… was missing

The XAML block under Chart Marker Size was the wrong snippet: the section is about
MarkerSize on a ScatterLineSeries and XAML showed a LineSeries chart with callout, final
value and crosshair layers and no marker size at all. Collapsed to what the three web
platforms agree on and the prose describes, so XAML now demonstrates the property the
section is named after. The web blocks referred to axes they never declared; the definition
declares them.

The reset example uses null, which is how the description API spells NaN.

The Japanese copy was missing the Chart Checkmark Marker Type section entirely, which is why
the mirror refused to run on this topic. Translated and added, so the two copies have the
same structure again. The translation is mine and has not been through localisation review.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The window coordinate section offers two forms of the same thing — a windowRect, or the
three positional properties — so it becomes two snippets with the page's own "or" between
them, which is what it already said.

Geographic Coordinates is left alone: it calls zoomToGeographic, and a description says what
a thing is rather than what to call on it. The library has MapNavigationOnViewInit holding
exactly that call, so this wants the handler channel rather than hand written code.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…t out

The Geographic Coordinates section showed a zoomToGeographic call, and the library already
holds exactly that call as MapNavigationOnViewInit. The snippet names the handler and the
build emits its body, per platform: a Rect literal on Blazor, a constructor on XAML, an
object on the web.

The new missing library item check earned itself immediately — it caught a dangling
tooltipTemplateRef the multiple shapes collapse had introduced, pointing at that page's own
ng-template rather than anything in the library, which would have emitted a reference to
nothing.

The mirror now refreshes a snippet that is already collapsed on both sides but has since
changed in English, which is how that stale reference would otherwise have survived in the
Japanese copy. Two snippets under one heading still cannot be placed automatically, but they
no longer block refreshing a section that has nothing left to place.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The CSV binding, JSON points binding and high density series pages each build their series in
a routine the library already holds — MapBindingDataCsvOnViewInit and the other two — so the
topics name the handler and the build writes it out per platform. 24 hand written blocks
become three definitions and three handler references.

Two faults in the mirror, both surfaced by these being the first topics with two snippets
under one heading:

  - it placed one snippet per section, so the second was silently dropped. A section is now
    replaced whole, with its snippets in the order English has them, which also removes the
    need to work out which snippet replaced which group.
  - its fence pattern required a body, and a ref fence has none, so those were invisible to
    it entirely.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…e with it

A few sections show two components side by side because the point is the comparison — an
ordinal axis on a FinancialChart and on a DataChart, markers off on a CategoryChart and on a
DataChart's LineSeries — and neither is a child of the other. A snippet body that is a JSON
array emits them in order, one blank line between, which is what the hand written block did.
This is the case that justified the form; nothing else in the set needed it.

The two guideline sections showed property assignments on a chart the reader already has and
now show the properties on the components, which is how the rest of the documentation states
them and what the comments in the original were already describing. It does change what those
sections demonstrate, and SNIPPET-COLLAPSE-DECISIONS.md says so, along with the two faults it
corrects: this.Chart.Resolution with a capital R on the platforms where that is not the
property, and the Blazor block setting it twice.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ling

The two guideline sections show a property being set on a chart the reader already has. That
is the lesson, so they are emitted as code rather than markup: asking for a component's code
channel now forces code behind, which is what that work was for. All five platforms show the
assignment again rather than a declaration.

Also stops two styling differences that the style options exist precisely to prevent:
selfCloseEmptyElements was set for React alone, though the topics close an empty element on
its own tag in Blazor and XAML as well.

An enum qualification option was added and then removed: the docs write MarkerType.Circle 315
times and the bare form never, so the emitter was already right and the one unqualified block
in chart-markers was an error.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Spreadsheet has no description type — not among the 1190 the schema is generated from, and
there are no spreadsheet sample JSONs in the examples repository at all. The renderer has
nothing to emit from, so this is a limit of what is described rather than a view about the
pages, and they become collapsible the day the component is described.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@gedinakova

gedinakova commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

@gmurray81 In Angular (and WebComponents) component names do not have prefix and suffix.
image

In blazor:
image

I would expect IgxBulletGraphComponent in the Angular topic.

@gmurray81

Copy link
Copy Markdown
Member Author

@gmurray81 In Angular (and WebComponents) component names do not have prefix and suffix. image

In blazor: image

I would expect IgxBulletGraphComponent in the Angular topic.

this should be resolved now @gedinakova

gmurray81 and others added 6 commits September 30, 2026 13:26
Conflicts resolved keeping the json-snippets work and vnext's changes:
- jp geo-map topics: vnext's className -> class fix was inside the code
  blocks these topics now emit from json-snippet fences, so ours stands.
- Frontmatter (color picker, virtual scroll, accordion, CLI overview):
  ours keeps platformType. Theirs brings the updated llms descriptions,
  related components, and color picker's dropped Color Editor link.
- toc.json (en, jp): merged entry by entry. Ours keeps the include lists,
  grid restructuring and added topics. Theirs brings the badge reset,
  removes the grid theming and Color Editor entries, and adds the
  breadcrumbs, color picker and QR code entries (jp).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
vnext's regenerated registries list a symbol as a single entry, and as an
array only where packages share the name, as ApiLink and check-mdx-links
already read them. The API term lookup assumed an array everywhere and
stopped every generation.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The grid and tree grid theming, color picker, QR code and breadcrumbs jp
topics came in without one, which the API term check requires. All are
web-only, matching their en topics.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
gedinakova
gedinakova previously approved these changes Oct 12, 2026
agoldenbaum
agoldenbaum previously approved these changes Oct 13, 2026
@ChronosSF

Copy link
Copy Markdown
Member

I started checking this today in more detail. I am trying to run it from the branch. After generating the snippet-emitter build - cd .\docs\xplat\scripts\snippet-emitter\ & npm install & npm build. I am trying npm run xplat:dev:react results in

file:///C:/Users/SStoychev/Documents/Git/docs-template/docs/xplat/scripts/generate.mjs:673
            throw new Error(`json-snippet source names a sample that does not exist: ${attrs.source}`);
                  ^

Error: json-snippet source names a sample that does not exist: /gauges/bullet-graph/animation

Additional findings. For some reason the agentic passes modified existing non-DV files and in a weird way - notice https://github.com/IgniteUI/igniteui-documentation/pull/497/changes#diff-8ffa628a80a5c4d9838b1a1ace4eea116b04cd915d9c5f9b1d748a61137e38eeR335 around line 346 of the changed file. It closed an open Angular platformblock only to open it again, then to close it then to open it again. As though it thinks a platform block should only contain 1 paragraph or codesnippet which makes the files even less readable than they already are. Can we fix that? If we can also stop it from adding new lines around the platformblocks which are also not needed, the number of changed lines will be significantly less frightening.

@gmurray81

Copy link
Copy Markdown
Member Author

I started checking this today in more detail. I am trying to run it from the branch. After generating the snippet-emitter build - cd .\docs\xplat\scripts\snippet-emitter\ & npm install & npm build. I am trying npm run xplat:dev:react results in

file:///C:/Users/SStoychev/Documents/Git/docs-template/docs/xplat/scripts/generate.mjs:673
            throw new Error(`json-snippet source names a sample that does not exist: ${attrs.source}`);
                  ^

Error: json-snippet source names a sample that does not exist: /gauges/bullet-graph/animation

Additional findings. For some reason the agentic passes modified existing non-DV files and in a weird way - notice https://github.com/IgniteUI/igniteui-documentation/pull/497/changes#diff-8ffa628a80a5c4d9838b1a1ace4eea116b04cd915d9c5f9b1d748a61137e38eeR335 around line 346 of the changed file. It closed an open Angular platformblock only to open it again, then to close it then to open it again. As though it thinks a platform block should only contain 1 paragraph or codesnippet which makes the files even less readable than they already are. Can we fix that? If we can also stop it from adding new lines around the platformblocks which are also not needed, the number of changed lines will be significantly less frightening.

Will look into it. It's possible it initially tried to act on those files mistaking them for xplat and needed to segment that platform blocks differently and then didn't revert things properly after. For the new lines around the platform blocks I think some of that might be coming from merges from the base, since I think you guys have changed the linting rules multiple times while I've been trying to land this and that is getting very frustrating.

@gmurray81

Copy link
Copy Markdown
Member Author

@ChronosSF I'll see if an agent can audit the remaining mutations to the non json-snippeted files. I see a few instances where a code term was transformed that shouldn't have been

Technically we could probably remove the web-only mutations from the front matter to make the blast radius easier to see, but I wanted that there just to make sure that each document had been positively identified one way or the other, and I think we still want that for future, so it would likely need to be a follow up pr either way.

@gmurray81

Copy link
Copy Markdown
Member Author

Did you have an example of the newline issue?

@gmurray81

Copy link
Copy Markdown
Member Author

On the better news front I think we can do this without the api maps now, and just use the product like the snippet tooling.

gmurray81 and others added 4 commits October 14, 2026 08:51
- src/platform.ts: vnext's snapshotted header and footer registry (no
  navType, no getNavConfig), with this branch's winui and uno entries in
  its form.
- jp/components/general-changelog-dv-react.mdx: vnext's rebuilt page. The
  web-only commit that follows leaves it exactly as vnext has it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
So the owners of the web-only pages have nothing of this PR's to review:
- A page that states no platformType is read as web-only, temporarily
  (lib/api-terms.mjs, check-doc-scope.mjs, the WinUI/Uno skips in
  generate.mjs). API-TERMS.md and AGENTS-README.md say so.
- The web-only pages drop "platformType: web-only", and the DV changelog
  pages, which each ship for one web platform, drop "xplat-unmapped". So
  vnext's new release notes are left as written rather than linked by rule.
- The 153 web-only pages that still differed from vnext go back to it. The
  edits were API-term markup, whitespace, and block restructuring the term
  and code-block work needed. None was published for WinUI or Uno, and none
  holds a json-snippet.

After this PR merges, the error comes back and the web-only pages state
platformType again.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- generate.mjs: the code-block filter this branch added skips web-only
  pages. On the restored pages it removed fences that vnext shows, such as
  React's DataPipelineParams and the grid date summary sample.
- toc.json (en, jp): drop the 13 web grid entries that were listed for the
  web only to keep their pages off WinUI and Uno, which web-only pages now
  are anyway. Restore the old "Grids & Lists" node, excluded everywhere, so
  grids/grids.mdx is built nowhere, as vnext has it for the web. Restore the
  updated badges vnext gave Accordion, Button, Switch and (jp) Avatar,
  which the merge dropped.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Breadcrumbs, color picker, QR code and themes accessibility were linked in
the jp toc without the Web gate their en entries carry, so the WinUI and Uno
jp builds published them.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@gmurray81
gmurray81 dismissed stale reviews from agoldenbaum and gedinakova via 6e29eee October 14, 2026 12:51
gmurray81 and others added 4 commits October 14, 2026 09:21
…scriptions

API terms on xplat pages resolve through description-terms.mjs, which reads
the product's description metadata and the api-docs indexes. The maps were
left feeding only:
- the old map-based resolver in api-terms.mjs (resolveApiTermsFromMaps
  and its helpers), which nothing called;
- generate.mjs's "unresolved", "ambiguous" and "patch the maps" reports,
  which that resolver used to fill;
- check-api-map-accuracy.mjs, backtransform-api-links.mjs and
  api-map-names.mjs, migration and regression tools for the maps;
- the class hierarchy description-terms.mjs walks when an index lists only
  a class's own members (every WinUI and Uno class).

That hierarchy now comes from the description classes, which carry it:
snippet-api.ts gains descriptionBaseType(), read from each description's
type marker. Of the 501 map base relations among described types, 348 match
it exactly and none differ. The other 153 end at framework types such as
EventArgs and Control, which no index lists members for.

Removes src/data/api-map (308 files, none on vnext), those three scripts,
and the check:api-map-accuracy npm script, and rewrites the docs that
described resolution through the maps. The upstream xplat-docs-api-map-sync
skill and resolve-api-links.mjs, which read igniteui-xplat-docs's own maps,
are unchanged from vnext.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…nearby

docs/xplat/xplat-examples.lock.json names the examples repository, a ref
and a commit, and every build reads that commit: fetched shallow, sparse
(code-gen-library, editor-templates, samples) and blob-filtered into
.snippet-cache. Before, a peer checkout beside the repository, or an
existing cache, was used as it stood, so a stale one could feed a build
months-old samples and report the gaps as page errors. The branch-name
matching that chose a fresh clone's branch goes too.

- XPLAT_EXAMPLES still names a checkout to use as it is, and says when it
  is not at the locked commit.
- Only a cache this made is moved. A worktree or a checkout with local
  changes is refused, with what to do.
- A ref with no commit follows the ref's tip and says so; resolve-examples
  --pin [ref] writes the tip into the lock.

Pinned at 7776e0d1, the gmurray/json-snippets commit CI was already
resolving to.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… lock

- --examples=peer (the igniteui-xplat-examples beside this repository) or
  --examples=<path> makes any script that reads the examples use that
  checkout as it is, generate.mjs and the snippet checks alike. It wins
  over XPLAT_EXAMPLES. npm run generate:peer is the short form.
- resolve-examples.mjs --check-pinned fails unless the lock names a commit
  already in the examples mainline (main, or the lock's "mainline"). The
  new Examples lock workflow runs it on every pull request into vnext and
  master, with no path filter so it can be a required check.
- JSON-SNIPPETS.md documents both.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@gedinakova

gedinakova commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

@gmurray81 Graham, styling properties in React, WebComponents and Angular are not properly listed:
image

gmurray81 and others added 2 commits October 16, 2026 09:12
On Web Components, React and Angular the group and header font size,
family, style and weight are one property, groupTextStyle and
headerTextStyle, so four bullets rendered the same name four times. Written
as one slash group, like the margins beside them, they render once on the
web and as the four properties on Blazor and the XAML platforms. Data
tooltip and data legend, en and jp.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants