Xplat docs xplat json snippet support and refactor and automated docs testing - #497
Open
gmurray81 wants to merge 158 commits into
Open
Xplat docs xplat json snippet support and refactor and automated docs testing#497gmurray81 wants to merge 158 commits into
gmurray81 wants to merge 158 commits into
Conversation
…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>
The Angular and React blocks used to resolve the Bing REST URI against the hosting page's protocol before assigning the imagery -- Bing serves tiles over the protocol its URI names and refuses a page served over the other. Without it a reader following the topic gets an empty map on half the deployments. It could not survive the collapse and nothing was wrong with the collapse: the logic is not in the display-bing-imagery sample, which has only descriptions and modules and no onViewInit at all, so there was nothing for a fence to emit. It was hand-written prose in the old pages. Hand-written again, after the emitted snippet, and naming roadImagery -- the variable that snippet actually creates, where the old block named a tileSource of its own. Gated to Angular and React because that is where it was: the same logic would presumably serve Web Components, but adding it there is authoring rather than restoring, and I cannot confirm it is needed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Both handler blocks open with `var map = this.map;` and nothing in them said what `this.map` is. The fences ask for the handler and its imports, and auto leaves field declarations out by default, so the reader was given a body that reaches for a field the page never shows. Asking for bindingFields supplies it. Named after handlersImports rather than before it so the imports stay at the top -- the channel list is emitted in the order it is written, and putting the field first read oddly. Web Components, React and Angular gain the declaration. Blazor already had one and I had missed it looking for the TypeScript idiom rather than `private IgbGeographicMap map;`. WinUI needs none: its map is named in the XAML, and a named element is the field, so `this.map` in the code-behind already resolves. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Its Dependencies section listed type imports and stopped there. Pre-branch it also registered the two modules the sample needs -- IgrGeographicMapModule and IgrDataChartInteractivityModule -- and without them a reader who copies the imports still has an unregistered map. Asking for the channel is not enough on its own: the definition has to carry the modules and mark them, which is how geo-map-binding-multiple-shapes does it. So the fence gained a modules array and a $modules marker naming modulesImports and moduleRegistration, and the channel now asks for both. Each platform registers in its own idiom, which is worth recording because it fooled my check twice: Web Components emits ModuleManager.register, React builds a mods array and calls register over it, and Angular emits an @NgModule with the modules in imports. WinUI's section is using directives, as it should be -- there is nothing to register there. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
chart-axis-types asked for radial-proportional-category-angle-axis. The route dropped "pie-": the sample its heading describes is radial-pie-proportional-category-angle-axis, which is defined and built; nothing has ever existed under the shortened name. stacked-chart opened with a drop-down that switched between all ten stacked types. That sample lived only in igniteui-wc-examples and a generated one cannot switch series type -- but the topic already embeds each of the ten types in the sections below, so nothing was lost by saying that instead. The prose no longer promises a drop-down. chart-titles now has a sample to embed, and its alt text no longer says Chart Synchronization.
Every PlatformBlock around a json-snippet is a place no check can reach: the emission check asks platformsAllowedAt before it emits, so a fence inside a block is never run for the platforms the block excludes -- not by the build, and not by the check that exists to catch what the build cannot say. Fifteen fences sit inside one. Twelve are the modules sections, where the gating is the point. The other three were hiding output. geo-map-binding-multiple-shapes "Importing Components" was gated to the four web platforms, and its fence emits `using Infragistics.Controls.Maps; using System;` for the XAML platforms -- the imports the handler code further down the same page needs. The heading was outside the block before the collapse and the section was empty for XAML; it is now the section it always claimed to be. The modules fence beside it keeps its own exclude="Xaml". geo-map-binding-multiple-sources "Summary" was gated to Angular, React and Web Components, which also dropped Blazor -- a section the hand written page did show it. Nothing in the prose says the summary is for some platforms; it says the snippets above are combined into one block to copy. That fence asked for channel="allCode", which on the XAML platforms is empty: their whole sample is markup, so the summary a page promised came out as a heading and nothing else. channel="auto" takes what the platform actually has, so every platform's summary is its own combination -- markup for XAML and Blazor, imports and template for the web. Angular's fields-and-ViewChild block is gone with it, which is the right trade: it appeared nowhere else on the page, and the four sections it summarises are markup for Angular too. The imports fence beside it states exclude="Blazor,Xaml". XAML resolves types through xmlns and has no import to show. Blazor has one -- @using IgniteUI.Blazor.Controls -- but the razor template hardcodes it above every insertion point and declares no bindingImports one, so the emitter has nowhere to put it. Twelve collapsed pages lost that line for the same reason. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Found by measuring the published pages rather than the sources: for each of the 55 collapsed
topics, every heading, on all six platforms, does the reader get code where the prose says code
follows. Two sections came back, and both predate the collapse -- of the 475 code-bearing sections
in the pre-collapse pages, 474 match by heading and every one of them still publishes code, the
475th being the Summary ungated in the previous commit.
chart-performance "Data Structure" teaches flattening a data source and had a Blazor block and a
web block, no XAML block and no fence, so WinUI and Uno got the paragraph and nothing under it. The
C# is what those platforms need too, with their own data property, so they have it now.
Two errors in that C# went with it, in the block that was already published: "1996" was assigned
to an int Year, and MultiDataSources.Create returned a list of lists from a method declared to
return one list. Neither compiles.
dashboard-tile said "you could define the Dashboard Tile like so:" above a {/*TODO SAMPLE*/} marker
and no code, on every platform -- and since its only other code is the npm and modules section, the
XAML platforms read the whole page without seeing a tile declared. It now shows the tile with the
property the sentence is about. The Japanese page never carried the marker, so the fence goes where
the same sentence ends.
The fence states no dataSourceRef, and not only because binding is not what the passage teaches:
Angular emits nothing at all for a DashboardTile's data reference -- the tile's metadata declares no
DataSourceRef, unlike Series, CategoryChart and PieChartBase -- and a property that emits nothing as
the last one on an element also swallows the > that ends the opening tag. Nothing published hits
that today: 6412 markup blocks across both languages and six platforms are well formed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Seven conflicts, all of them a key of mine landing beside a key of vnext's on the same entry. toc.json, both languages: this branch gates the Badge and Button Group entries to Web, vnext marks them updated. Thirty entries already carry both, "updated" first, so these do too. Five topics' frontmatter: vnext rewrote the llms description, this branch added apiTerms next to the old one. Their wording stands -- it is the deliberate rewrite -- with the key kept, indented two spaces the way all 602 other pages indent it rather than the four this hunk arrived with. Verified on the merged tree: 304 snippets valid against the schema, 766 emissions across five platforms with none failing in either language, casing and exclusion checks clean, and all twelve platform/language generations succeed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Markdownlint failed on this branch, and the cause was mine: four {/* TODO */} comments I left in the
WinUI and Uno sections, whose second line begins with an asterisk that MD037 reads as an emphasis
marker. Reformatting the comments would have silenced the lint and kept the holes, so the work is
done instead. Every fact came from this repository or the packaging branch rather than from memory.
The screenshots: dropped deliberately, which the note offered as the alternative. The Blazor
screenshots are of the Blazor flow and cannot be reused, and these steps name the menus they use.
The licensed feed: already documented. general-nuget-feed.mdx carries the URL and the walkthrough,
and the Blazor section links it for exactly this purpose, so the WinUI and Uno sections link it too.
Add Your First Component: a radial gauge, declared in markup, from the needle sample -- one control
with a value and a scale, using the igGauges prefix the section above just told the reader to
declare. A fence rather than a hand written block, so it stays true to the sample and is emitted the
way every other snippet is.
Uno: its own section. Package creation and prerequisites are Uno's own and move faster than a topic
can, so those link Uno's getting started guide rather than restating steps that would go stale; what
this repository can state is stated. The five packages and three Wasm variants are the nuspecs on
gmurray/winui, and they are a narrower set than WinUI's -- no map, dashboard tile, inputs, layouts,
sparkline or treemap -- which the section says out loud rather than implying parity. Namespaces and
XAML are identical to WinUI's, as the note said.
Each fence sits inside the PlatformBlock for its own platform. That is the one shape of gating the
audit leaves alone: the page is a per-platform walkthrough, so a WinUI reader is meant to see the
WinUI steps and not Uno's.
markdownlint clean on both files, 308 snippets valid against the schema, 767 emissions with none
failing in either language, and all twelve platform/language generations succeed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Lint's markdownlint half passes now that the TODO comments are gone, and cspell's half took over. Four words, all of them mine: "organisation" and "colour" in a doc set that writes color and behavior the American way, and "backticked" twice, which is not a word -- an API name is in backticks. TINYCLR is not a misspelling. It is the build constant the product compiles the portable sources under, so it goes in the dictionary beside OHLC and WCAG rather than being reworded away. Both linters now pass over every markdown and mdx file this branch touches, all 614 of them, not just the ones that happened to fail. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The beta the checks pinned predated $styleOptions.preferNameBindings, so three jobs failed on two pre-existing chart fences that use it -- the schema check, the build, and the link check, which generates before it can look for links. beta.12 has it: with the published emitter rebuilt from it, 308 snippets validate and 767 emissions pass in both languages. The load check was not that, though it looked like it. Two fences failed as "animations never settled", and they still failed on beta.12, because the fault was here. A host page has fixed insertion points and index.html mirrors them. A documentation fence does not: it names its holes after its components -- "financialChart" beside "dataChart" -- because two components in one fence need two names, and the generator only reads them as labels. Every such definition went into containers this page does not lay out, so nothing was cleaned up, nothing was flushed, and the handler that resolves the animation wait was provided on "content", where the renderer never looked. The fence timed out whatever it held. A CategoryChart in a hole named financialChart failed the same way; a FinancialChart in "content" passed, which is what says it was never the chart. So a container is made for whatever hole a definition names, teardown and flush walk the holes in play rather than a fixed list, and both the animation handler and the idle wait follow the containers the definition actually uses. 304 of 304 fences now load clean across both languages, up from 302. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
With the emitter unstuck, the build got as far as rendering and stopped on an ApiLink the beta.12 registry made ambiguous: "DateRangeDescriptor.rangeType" now also matches IgbDateRangeDescriptor, and the component asks to be told which. The page had already answered that question three times -- pkg="core" -- and left seven links bare. They say pkg="core" too now, in both languages. All four platforms CI builds -- angular, react, webcomponents, blazor -- build clean locally against beta.12, so this is the whole of it rather than the first of a series. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Twelve fences failed the load check as "MapShapeRandomStyling threw: Style is not defined", and only in CI: locally the templates come from a peer dev-tools checkout, and CI has none, so it reads the copy in this repository -- which had drifted. dev-tools' handler.ts declares a supportingImports region and this copy did not. Style is declared by the ShapeStylingUtility supporting item, so with nowhere for its import to go, every handler built on that utility referenced a name the emitted file never imported. supporting.ts had the older spelling of the same region, handlersImports. The toolchain had been saying so all along -- resolveItemTemplates compares the two and prints which files differ -- and I had been grepping past it for FAIL lines. Read the whole output. Verified with CI's own inputs rather than mine: the published beta.12 emitter through IG_SNIPPET_API and the vendored templates through IG_ITEM_TEMPLATES, 304 of 304 fences loading clean in both languages. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The grid this work is about is the data grid -- igniteui-<platform>-data-grids. grids/grid, grids/tree-grid, grids/hierarchical-grid, grids/pivot-grid and grids/_shared are the web grid's, and two changes of mine reshaped them. Both are reverted. The split: the Japanese grids/theming-grid.mdx became three per-family copies, to match an English split someone else had already done. English's dangling toc href was a real fault, but it is their fault to fix in their doc set, and splitting a topic of theirs to tidy it is not this branch's business. The Japanese topic is back at its own path with the apiTerms line this branch adds everywhere, the three copies are gone, and the toc entries name what upstream names -- one Theming entry, Angular excluded -- keeping only the include: ["Web"] that stops a CSS topic reaching a XAML reader, which is about what our platforms publish rather than about their content. The widening: six of their shared topics had a block opened up so Blazor, Web Components or React would see a heading that had been Angular's alone. The reasoning holds in the abstract and it is why generated output grew from 72 lines to 253 on one page, but deciding what a web grid topic shows a web grid reader is theirs to decide, not a side effect of our snippet work. That also settles the 209 broken links, all of them consequences of those two changes: 193 of them the split, and the rest a Styling section that the widening published to Blazor and Web Components carrying a themes/index.mdx href -- correct in the Angular tree, where that file exists, and wrong in this one, where the file is themes/overview.mdx. Not ours to rewrite either; Angular-gated again, it is not published here. The xplat link check is back to 0 broken, which is what vnext reports. Schema 308 valid, 767 emissions in both languages, casing and exclusions clean, all twelve generations succeed. What stays in their pages is this branch's mechanical work: the apiTerms frontmatter, the API terms resolved against the api maps, and the nesting normalization from 700b53c, whose 158 blocks across 96 files were checked to leave generated output byte identical on all five platforms. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
An audit of the guide against what the scripts actually read. Six things were missing, and each one had already cost something. include= and omit=, which channel="auto" takes, and what auto asks for when a fence says nothing. That code= and channel= are not two spellings of one thing: code="allCode" is markup plus its code, channel="allCode" is code instead of markup -- and the XAML platforms, whose samples are markup throughout, have none, so such a fence emits nothing and drops out. That published a heading with nothing under it. More than one component in a fence, both ways: an array, and named holes under descriptions. Hole names are labels rather than layout, content being the one a host page lays out. skipAlterDataCasing, which decides whether the web emitters camelise a member path, has to agree with the sample it mirrors, and is what check-snippet-casing.mjs compares. preferNameBindings, and the fact that indentXamlAttributes only indents an element with children: a self-closing root's attributes come out flat whatever a definition says, which is 234 of the 408 XAML blocks published today. That gating is a blind spot as well as a tool. The emission check asks platformsAllowedAt before it emits, so a fence inside a PlatformBlock is measured by nothing at all -- which is why every one of them is worth auditing, and why two that were hiding real output went unnoticed until they were. Also: the sixth check, code-channels, in the table that said five; the harness flags that cut a failure down, --sample= above all; and the three environment variables that decide what a run is testing, with the vendored template drift that failed twelve fences in CI and nowhere else. Both linters pass. Every fence attribute the code reads is now in the table, every style option the schema declares is described, and every script the guide names exists. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A link resolves for the link check if the file exists. Whether the platform reading the page publishes that file is a different question, and nothing asks it -- so a page can link a topic its own readers cannot reach and every check stays green. Twenty-three such links reach out of the DV topics on a WinUI build. Two are ours. The Infragistics NuGet feed, which I linked yesterday from the WinUI and Uno getting-started sections: general-nuget-feed.mdx is include: ["Web"], so those readers got a link to nothing. The sections state the feed instead -- the source URL and where Visual Studio takes it -- which is what the topic would have told them. The Shape Styling Utility, linked from geo-map-shape-styling since "Say where a handler's args come from": its entry was include: ["Web"] with Blazor excluded, while the page that links it is only Blazor excluded. One step narrower than its own family for no reason, and the page emits a complete C# utility class with its usings for the XAML platforms -- verified by emitting it for WinUI, which the emission check does regardless of gating. The include is gone, the Blazor exclusion kept, and WinUI and Uno publish 132 pages instead of 131. The remaining twenty-one predate this branch: a Web-only stock chart type linked from chart feature pages, two more geo-map resource topics gated the same way this one was, and the web grid's hub page. Not ours, and not touched. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
An agent following the skills as they stood would write an xplat topic that does not build, and would hand write one code block per platform because nothing told it not to. New skill, xplat-docs-json-snippets: what a fence is and what it emits, the attribute table, and the five traps that actually bite -- that code="allCode" is markup plus code while channel="allCode" is code instead of it, and so emits nothing on the XAML platforms; that a PlatformBlock around a fence is a blind spot the emission check never measures; that an exclude= can leave a reader with prose and no code; that en and jp move in one commit; and that a page without apiTerms does not build. Then the six checks with the commands, and the environment that makes a local run reproduce CI. It routes to JSON-SNIPPETS.md rather than restating it. xplat-docs-api-links gains the processing mode it never mentioned: apiTerms is required frontmatter with no default, full and passthrough both emit a link while none deliberately does not, and a term resolves canonical-first then in reverse through the platform affixes. Plus the authoring scripts, and the trap that cost a CI cycle yesterday: ambiguity arrives when the packages move, only the build catches it, it names the page it died on, and the answer is usually already on that page -- calendar had pkg="core" three times and seven bare links. So build all four platforms after a beta bump; each stops at the first ambiguity, and a clean link report is not a clean build. house-style, the set's normative field contract, gains apiTerms and a json-snippet rule ahead of the inline-snippet bullet, which is now scoped to the blocks a topic still writes by hand. The doc-skill set is bumped to v4 across all nine files with a CHANGELOG entry, per its own convention, and the routers and descriptions are untouched so the .claude and .codex adapters still byte-match. AGENTS-README said four platforms and two recurring tasks; it now says six and three, lists the new skill and api-map-sync, which was in the tree but in no index, and routes the situations that send a reader to each. Verified: the new skill's frontmatter matches its three xplat siblings, every script it names exists, and markdownlint is clean on all twelve files. These paths are outside the Lint workflow's docs/** scope, so the pre-existing cspell words in the .ai set are unaffected either way. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The skills I just wrote stated one standard for the whole content tree. There are two populations in it, and holding the wrong one to the DV rules is as much a mistake as holding the right one to none. An **xplat doc** publishes to WinUI and Uno as well as the web platforms — the DV set: charts, gauges, maps, dashboard tile, data grid, toolbar, zoom slider. A **web-only doc** — inputs, layouts, notifications, scheduling, themes, the web grid families, grid lite — reaches the four web platforms and no further, owes neither rule, and is not to be reworked to match the DV set. That last part is stated as plainly as the rules themselves, because an agent told to prefer json-snippets will otherwise go and "fix" 229 pages that were never in scope. The test is mechanical: does the page publish to WinUI or Uno. A generate run for WinUI is the definitive answer, 132 pages today; before a build, the subject and the page's toc entry answer it. The two rules are deliberately of different strength, which the first draft got wrong by making both absolute: apiTerms: full, with canonical names in backticks, is absolute on an xplat doc. A bare name that no map resolves is an API claim nobody checked, and no DV topic wants that. 128 of the 132 xplat pages already declare it; of the four that do not, three are untoc'd web grid pages that only land in the set because an untoc'd page publishes everywhere, and one is a page whose gating I widened yesterday without its frontmatter following. A json-snippet is the strong default, not a ban. The reason to prefer it is drift — four to six copies of one lesson — so reach for a definition first and expect to justify not doing so. But a platform-specific snippet stays a legitimate tool where a definition genuinely cannot carry the lesson: a data shape with no component in it, a namespace declaration, a package install, a step only one platform family has. What is not legitimate is reaching for one because the definition looked like more work. Stated in all four places that will be read: the json-snippets skill, the api-links skill's mode table, house-style as the normative contract, and AGENTS-README's context. The doc-skill set stays at v4 with its changelog entry amended rather than bumped again, since v4 is unreleased and this corrects its own text. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two standards share this content tree and nothing recorded which one a page was held to. It was
inferred -- from where a page published, from whether it had been collapsed -- and inference got it
wrong: the data grid's accessibility topic is an xplat document that reaches no desktop platform, and
three collapsed geo-map resource topics were gated to the web. A page cannot be read for its own
identity, so it states it.
platformType: xplat the cross-platform (DV) set
platformType: xplat-unmapped the same set, where the full treatment cannot be applied yet
platformType: web-only the web platforms and no further
Required, no default, and it throws naming the file -- the rule apiTerms used to carry, moved to the
field that can actually answer it. apiTerms now follows from the population (full, passthrough, none)
and is stated only to differ, which 578 pages no longer need to do. What that removes is a decision
nobody was making: the comment on apiTerms said the answer "follows from whether the page ships
outside the web, and that lives in the toc", and now it lives in the page.
xplat-unmapped is not a soft xplat. It is for a topic whose names genuinely cannot resolve, and two
things sit there: the Excel library, whose API no generator describes, and the accessibility topic,
whose XAML shape is undecided. An xplat page may not declare apiTerms: none -- that is opting out of
what makes it xplat -- and check-doc-scope.mjs fails on it. It caught one on its first run.
146 xplat, 9 xplat-unmapped, 157 web-only, each call reviewable in a manifest. Identity is not
publication, so the check reports rather than fails where they disagree: 19 xplat topics reach no
desktop platform (all of Excel and spreadsheet, which have no XAML package, plus accessibility), 4
web-only topics publish to WinUI and Uno anyway (the untoc'd web grid theming pages and a legacy hub
whose own toc note calls it "THIS MAIN NODE FOR OLD XPLAT GRID"), and 4 DV changelog pages sit in
web-only unprocessed.
Seven topics that were xplat all along had been gated to the web, so they are published too, which is
what takes WinUI from 132 pages to 140 and dead links out of its DV topics from 21 to 6 -- the rest
belong to that legacy hub. chart-api, stock-chart and map-api are API tables with no code in them;
the three geo-map resources and the shape file reference were collapsed long ago.
Verified rather than assumed: 2621 of 2651 generated pages are byte identical in the body, the only
frontmatter change on an untouched page being apiTerms: none becoming platformType: web-only. The 30
that differ are the pages deliberately moved to full resolution, and the difference is the treatment
working -- `RangeBarSeries` became an ApiLink among its already linked siblings, and Web Components'
`Hyperlinks` picked up its own casing as `hyperlinks`. Schema 308, 767 emissions per language,
exclusions clean, links 0 broken, twelve generations, and the WinUI site builds.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The four general-changelog-dv pages narrate the data visualization product's own history, so they belong to the cross-platform set whatever platform each of them is addressed to. They were the last web-only pages whose subject looked like the DV set, which is what check-doc-scope reports them under. The seventeen per-package changelogs were already xplat. Full resolution costs something here and it is worth stating plainly: 361 names in backticks across the four, of which 195 resolve against the api maps and the rest are now reported. That report is noisier than it looks. 65 of them are in src/data/api-link-index -- the registry ApiLink resolves against at build time -- but not in src/data/api-map, which is the registry the term resolver reads during generation. Those names are resolvable; the stage that decides whether a name is API at all never asks the registry that knows them. The remaining 101, GridBase and DisplayDensity among them, are in neither and are a real report. Not fixed here, deliberately. The obvious fallback -- ask the index when the maps miss -- would link those names on the four web platforms and leave them as plain text on WinUI and Uno, because the index carries no XAML data, and a term rendering differently per platform for a reason unrelated to the API is the drift this system exists to prevent. It also changes every page on full, not these four. Left as it stands. 0 errors in both languages, schema 308, twelve generations, links 0 broken. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The skills learned the three populations when the field was added; four other places an author or an agent actually reads did not, and the most important was the guide the skill routes to. JSON-SNIPPETS.md is normative for fences and said nothing about who its rules apply to, so every stricture in it read as universal. It now opens with the three populations and two consequences: read the frontmatter before applying anything below, because a per-platform block on a web-only topic is not a defect; and identity is not publication, because a topic can be xplat and reach no desktop platform, which is true of everything Excel and of the accessibility topic. Create step 4 now begins with platformType rather than title. It is required, has no default, and decides the standard the rest of the work is held to -- an author following the old order wrote a topic that did not build. Audit check D0, a blocker: no platformType, or one that does not match the topic. It names the trap that makes the audit worth running, which is that the same observation flips meaning between populations -- a per-platform code block or a non-full apiTerms is a finding on an xplat topic and perfectly fine on a web-only one. scripts/README.md lists check-doc-scope.mjs among the CI checks, and JSON-SNIPPETS.md counts seven checks rather than six. The doc-skill set stays at v4 with its changelog entry extended, since v4 is unreleased and this is the same change reaching the files it should have reached the first time. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The CI failure from the previous commit, and it is mine: putting the DV changelog pages on full resolution turned 96 names in backticks into ApiLinks on the Blazor page, and 42 of those could not be resolved to one URL. The Blazor registry documents each web component twice, in IgniteUI.Blazor and in IgniteUI.Blazor.Lite, so Checkbox, Input, Rating, Select, Slider, Textarea, DateRangePicker and Tree each matched two candidates and the build stopped on the first one. The page had already answered this two hundred and four times: every hand written link on it carries pkg="core". So the nineteen terms in English and twenty-one in Japanese that the resolver was turning into bare links are written as explicit links with that same pkg, using the resolver's own idea of which type and member each meant, so nothing a reader sees changes. Two of them were not a package question. `Change` appears under a Checkbox bullet and again under a Radio bullet, and the resolver scoped the second to Input -- not unreasonably, since a nearer link on the line above names Input, but wrong: the bullet is Radio's. Both now name their own type, which is a misattribution the full treatment surfaced rather than caused. Predicted with the registry rather than found by rebuilding: ambiguous links on the Blazor pages went 42 to 0, and Angular, React and Web Components had none to begin with -- their registries carry no Lite twin. All four platforms then built clean locally, which is the only check that catches this. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nothing enforced it and nothing ever did: generation validates the path only when a fence states one, the casing check skips a fence without one, and 30 of the 158 fences in en name no sample at all. What made it read as required was the documentation, which listed it first with no note and led every example with it. The attribute table now marks it optional in both the guide and the skill, and the guide says what it buys -- it is what check-snippet-casing.mjs compares a fence against, and what tells a later reader where the values came from -- alongside why a fence may legitimately have none: a definition teaching one property, composed from two samples, or stating something no sample runs. Two instructions with it, because the wrong instinct here is to tidy: do not invent a source to satisfy a rule that does not exist, and do not remove one that is already there. The skill carries the same as a trap, since "add the missing source" is exactly the kind of thing an agent does unasked. No behaviour changed. Schema 308, 767 emissions, casing 102 agreeing, generation clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
IGvaleries
reviewed
Sep 2, 2026
IGvaleries
left a comment
IGvaleries
left a comment
Contributor
There was a problem hiding this comment.
changing from the syntax to the more detailed ```json-snippet source=... no longer shows the actual running sample. This can be seen in the dashboard tile topic
Contributor
I was mistaken the tag still exists in the doc. Not sure but for some reason this was not being fully displayed in the sample viewer. Looking again for this sample I only see the toolbar. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #
Checklist:
preview/beta./page.mdxor../relative/path.mdx(.mdxextension required)IgxSelectComponent,<igx-combo>code blocksfor the names of classes / tags / propertiescode blockscheck-api/mdxnpm commandsllms.descriptionmetadata and runnpm run check:llms-metadata