codelessly_api 32.0.0
codelessly_api: ^32.0.0 copied to clipboard
Flutter's widgets and layouts as plain, immutable data with a JSON format. The model behind the Codelessly Editor and the Codelessly SDK. Pure Dart.
32.0.0 #
Released with codelessly_sdk 32.0.0. Stored documents and the JSON format are unchanged; the one breaking change
is in how the compact notation reads Column center.
Breaking #
- Notation:
centerandmiddleon aColumnswapped.centernow centers children side to side;middlegathers them at the column's middle. Notation that wroteColumn centerexpands differently.
Added #
- Notation, meters and charts:
Gauge/Dial(limit:,unit:),Ring,Sparkline,LineChart labels:[…] series:[…],AreaChart,Donut. - Notation, motion:
animate:<word>(fade, slide-up, slide-left, scale, pop, bounce, shake, pulse, spin, shimmer) withduration:,delay:,stagger:;swipe:left -> …. - Notation, layout: several top-level lines are a page's sections, stacked; a
Stackplaced withleft,right,top,bottom, or centered withcenter middle;maxw:;grow:=value. - Notation, parts and props:
Avatar;Input … password/multiline; a slider'sstep:;Text … center/strike; anIconButton'scolor:andsize:;gradient:[…]; aneverywith its actions on the next line. TextProps.markdown: a text shown as Markdown (bold, italic, code, links, @mentions, lists) with the markers taken out. Same keys asTextFieldProps.markdown.- Two schema 2 → 3 migration steps for projects made before the v2 SDK:
text.markdownmoves a text's Markdown look toprops.markdown;trigger.fieldResultrewrites a text field reaction'sresult.value,result.word,result.cursor,result.selectionStartandresult.selectionEndtofield.*. - Theme names the notation uses when present:
sizes.widewith atitleWidetext style (wide page titles fromNotationOptions.fromTheme(width:)),sizes.ring, text stylesgaugeValueandgaugeUnit,colors.pageFill. A theme without them is unchanged.
Changed #
- Notation is more forgiving: props guessed in a JSON tail are read as the notation's own keys, or reported at their line; single quotes hold spaces in an expression; fixed text widths in a row become shares when they do not fit.
Fixed #
- A required component parameter set to its default value is kept.
Propsdropped it, and the call then reportedmissing_prop.
31.0.0 #
Released with codelessly_sdk 31.0.0. Nothing a document written for 30.1.0 uses has changed.
-
The compact notation (
package:codelessly_api/notation.dart):Pages =page(swiped pages bound both ways,peek),Dots =page count:n,Row scrollscrolls sideways, sideways scrollers fade at their edge, and a value that follows state is read as a model writes it: the name bare (choice:pick), in braces, or the expression with no mark (enabled:!voted); a list holding expressions is a formula;true,falseandnullafter:=are values. On a block's line, a bare word one enumerated parameter has,key=valueand a further string are read as the parameter they can only mean.NotationOptions.fromTheme(named: true)writes looks as the theme's names. -
notationPromptcarries a design system's composition brief (its PATTERNS.md "In brief"). -
More of what models write is read (each from a recorded answer, each with a test): a handler as a key (
onPressed:{…},tap:"…"), statements after->as in code (n += 1,row.done = !row.done,rows.add(x),rows.remove(row),if (c) { a = 1 }),let name = expressionfor a worked-out value,for x in list,else,and/or/not, calls on a value (total.toFixed(2),rows.length); a condition in braces with spaces and quotes;key:={…}; a text inside a list or inside a formula that reads a value (items:["Lemons, {2 * n}"]); a list written over several lines; a value in braces that holds its own braces; a property written after the actions; a code fence around the answer; a parameter named like a handler (change:1.84);formatTime(seconds)asduration. An action that sets a worked-out value is dropped (the value follows the state by itself) instead of corrupting the line. -
Wanted "Name" "what it shows": a part no component fits, built from plain types under the line and shown as written; the request is inNotationResult.wantedandNotationStream.wanted(WantedBlock).notationPrompt(wanted: true)teaches it;notationPrompt(natural: true)is a variant that teaches values and actions in the forms above (not the default: it did not measure better). -
duration(seconds)andconcat(a, b)are in the notation's list of functions. -
edgeFadeon scrolling containers and page views. -
Validation: a project component replaces its design system's of the same type (it was reported as a duplicate).
-
The compact notation, first version (
docs/design/13-compact-notation.md):parseNotationinlib/src/core/notation/notation.dart(internal, not exported yet) expands one node per line, nested by indentation, to an ordinary document: short type names (Input,Toggle,Button.ghost,Card,Text.title), a main string,key:valueprops,=nametwo-way bindings that declare their variable,->actions,state,if,{name}in text and a{…}JSON tail. What it cannot read is reported by line. -
labeloncheckbox,radioandswitch: text beside the control (SSUI's; Flutter has the*ListTilewidgets for it). Tapping it toggles and it names the control to a screen reader. -
An expression written where a plain value goes is bound, not rejected.
"radius": "${theme.radii.panel}","visible": "${step > 0}", a non-text prop:applyOpsmoves it into the node'sbindunder the field's path and reportsexpression_bound(a note, with the binding written). A path already bound keeps its binding; text props read expressions as written and are left alone.strictEditCheckpassesValidateOptions.levelthrough. -
Levels of the vocabulary (
docs/design/12-agent-first-flutter.md).lib/src/core/levels.dart(internal, not exported) gives every node type, action, data source, behavior and trigger a level: core, widgets, state, design, full, features.catalogAtLevelcuts a catalog to a level,levelOfandlevelUsesread a document's, andValidateOptions.levelreports anything above the level given (above_level). -
Date and time pickers (Milestone 3, workstream G): the
datePicker,timePickeranddateTimeInputdocs describe the SDK's own pickers (SSUI's field, a calendar or hour/minute columns in a popover or bottom sheet; an empty value shows its hint), no longer Material's dialogs;docs/design/11-no-widgets.mdmarks workstream G built. -
Design 11: the text field as built (WS-A, section 3.2): field frame, editor and what is left (handles, toolbar).
-
Milestone 3, kit follow-up and workstreams C and I: a control (
WidgetSpec.hugs: buttons, chips,badge,circularProgressIndicator,activityIndicator) with nolayout.width/heighthugs its content instead of being 0 × 0 (zero_sizeno longer reported for it); buttons takeloading(SSUI'sisLoading);TriggerType.deleted(an input chip's delete icon, Flutter'sonDeleted); the chip, badge and spinner docs say what their default (SSUI) look is. -
Milestone 3 design:
docs/design/11-no-widgets.md(the renderer as render objects with noMaterialApp,Navigator,Overlayor widget per control; the control kit; SSUI as the default look; the split of the remaining controls into parallel workstreams). -
Theme roles:
ThemeTokens.resolvedRoles()gives the roles (primary,onPrimary,surface,onSurface,error,success,warning) as colors, a role that names a theme color ("primary": "forest") resolved through any chain of names; such a role never reached controls before (they drew black or white). A role written insidecolorsis a second spelling and is reported,theme_role_in_colors(warning), with the key to move.ThemeTokens.roleNames. The STARTER's theme example declaresprimaryandonPrimaryby color name. -
Buttons (
filledButton,outlinedButton,textButton,elevatedButton,iconButton,floatingActionButton) takeautofocus(Flutter's), and drawWidgetState.selectedthemselves: a boundselectedon a button no longer reportsstate_no_effect.WidgetSpec.states(catalog JSONstates) lists the states a type's own look draws. Their docs say what the default (SSUI) button is.
What ten sites built as data (brief 3) ran into.
- Validation: a list's pagination controller (
props.pagination.name) is a name its page may read (${coastPages.page < coastPages.pageCount}wasunknown_name). gridView.fillGaps: CSSgrid-auto-flow: dense, automatically placed items filling the holes earlier spans left.navigate.tomay be an expression (${item.to}): documented on the action; the SDK now evaluates it.fit_not_allowedin a wrapping row gives the fix (basis, with an example);decoration_ignoredon a text says how to make a filled, rounded label (a row around it) or a highlight (style.backgroundColor).- Reference: a page gutter and max-width recipe that keeps every section on one left edge at 390, 834 and 1440, and
hero sizing (layout); submitting a form with no backend and simulated loading and error states (forms); a
tableViewwith bound data (lists); updating one list line at itsindexand UTC offsets instead of IANA time zones (state); counting a number up, and running severalanimateactions together (animation); explicit grid placement under a filter,scrollTo's offset under a fixed header and scrolling to a heading on another page (layout); declaring a variable font once (theme);step_skippedandpage_not_written(render).
Valid but blank, explained. Of 34 recorded SSUI generations, several final frames showed an empty card or a card missing its content. Causes in this package, and what a model is now told:
-
A
varsop with one formula that does not parse (or reads an unknown name) is no longer rejected whole: its other variables are declared, and the formula's error stays an error at that op, saying the variable gives nothing until its formula is fixed. Rejecting it left every node that read the op's variables showing nothing (three recorded cards, reservation, checkout and itinerary by claude-sonnet-5-5, went blank once formulas were checked). -
BindValue.colorreads a theme color's name (Color.named): a fill bound to"${= selected ? 'primary' : 'primaryBackground'}"was dropped. -
A
patchop merges a node as its declarations read it (mergeNodePatch):{"height": {"fill": 400}}over{"hug": 480}gave a two-key size and the patch was rejected. -
A
setthat replaces the root canvas with another type is rejected (wrong_type, with how to set the canvas's body): a recorded retry turned its canvas into a column and the view showed nothing. -
wrong_typefor a${...}expression written as a plain value ("radius": "${theme.radii.panel}","visible": "${step > 0}") names the binding to write,"bind": {"decoration.radius": "${theme.radii.panel}"}. Five recorded base turns lost their whole card to one such rejected container. -
The design system section shows its spacing, radii and sizes as the binding to write ("bound, not written: ...") instead of the bare
${theme.radii.panel}models wrote as a value. -
New codes for what a rendered UI shows wrong, reported by the SDK's
UiSession.shownDiagnostics:empty_viewandlist_empty(errors),empty_label,expression_not_evaluated,text_no_color,component_empty(warnings). -
dead_controllint: a core button, or a component named...Buttonwith anonPressedevent, with no reaction, not disabled and not inside a tappable node (a recorded plan card was a static mock-up whose Start and Pause did nothing). -
A computed variable's
formulais checked like a node's expressions (it was not checked at all): it must parse and read only declared names, itsparametersincluded. The edit layer checks the formulas of the variables avarsop declares (EditCheckInput.variables, read bystrictEditCheck; the diagnostic's message names the variable). -
An unknown name that is a field of a list variable's records (
filter(invoices, status == 'Paid'), computed once outside the list and matching no item: a recorded data table showed "No results" over twelve defined invoices) gets a message that says so and the lambda to write (filter(invoices, r => r.status == x)), withr => r.statusas its suggestion. -
unresolvedReferences(withchangedVariables): once a stream has ended, the references accepted as warnings while it ran ("it must exist when the stream ends") that are still unresolved, as errors.streamReferenceCodesnames the codes. -
Reference: lists "Filter, sort and page a list" (search, a status filter, sortable headers and pages from chained computed variables, with a validated example; the pitfalls: a condition without its item, "All" and an empty search,
sortBy's'asc'/'desc', resetting the page), a pitfall line, a line in the base and a row in the task table.{{example-as-written:path}}puts an example in a page as its file is laid out (one node per line). -
strictEditCheckpasses its options'themeon to the validator (it dropped it): a session with a design system checks each op against the design system's tokens, so a theme color or text style name (primaryBackground,sectionTitle) is no longer rejected asunknown_theme_name. -
TrustProfile.withComponents(library): the profile with a component library's types allowed. A session given a design system checks ops with it (the SDK'sUiSession(designSystem:)):TrustProfile.agentlists the core's node types only, so every call to a design system component wascapability_not_allowed. -
A top-level
componentEvent(in a document that is not a component: a generated UI's own events to its agent) is no longerunknown_eventin document and site validation; it is an event to the document's host and needs only an"event"name. The strict edit check no longer filters the code out for this case.
30.1.0 #
No special cases left: the last 21 one-look fields are general mechanisms. Documents stay "schema": 3.
Each removed field is migrated by a one-way step at the end of migrate2to3 (steps_special.dart); in a
schema-3 document each is an unknown_prop whose message names the form to write, and a setValue path into one
is rewritten where it has a place (props.displayFormat, props.highlightStart/End) or reported. No document in
the corpus or either repository used one. Name conformance (docs/design/name-conformance.md, regenerated): 853
fields, 62% Flutter's name and meaning, 77% of those with a Flutter counterpart, none (d).
| Removed | Instead | Step |
|---|---|---|
text countUp, countUpDuration, countUpCurve, countUpOnShow |
a transition of props.text with the timing, and (with countUpOnShow, the default) an animation countUp with a track on props.text from 0 |
text.countUp |
slider rulerTicks, rulerMajorEvery, rulerTickColor, rulerMinorTickColor |
customPaint.painter ops: a baseline line and a repeat of tick lines (a ruler track's default 20 ticks too) |
slider.paint |
slider markerValue, markerColor, markerWidth, markerHeight |
a rect op at the value along slider.trackRect |
slider.paint |
slider activeTrackStartOpacity |
an rrect op over the active track: the inactive color fading out |
slider.paint |
slider thumbGripColor |
a rect op in foregroundPainter at slider.thumbCenter |
slider.paint |
slider deriveOverlayColorFromThumb |
nothing (no renderer read it) | slider.paint |
text field highlightStart, highlightEnd, highlightStyle |
runs (new on the text field: styled ranges of the typed text, as a text's; Flutter's TextEditingController.buildTextSpan) |
textField.runs |
table selectedRowEdgeColor, selectedRowEdgeWidth |
the cell template's selected state style (a left stroke), selected bound to the cell being first in the selected row |
tableView.rowEdge |
date/time input displayFormat |
format |
dateTimeInput.format |
- A number in a text counts.
AnimationTrack.lerpValue(a, b, t, text: true)(andvalueAt(..., text:),sequenceAt): a text that holds a number goes froma's number to its own, written as the end writes it (the characters around it, decimals, thousands separators; a value a clock computes a hair under a half rounds as the half).NumberInText(parse,format). A transition or track on a text prop such asprops.textcounts. - A slider's custom paint draws between its parts and reads
slider(value,min,max,trackRect,thumbCenter):SliderTrackShape.rulerdraws its strip and fill only; the ticks are ops. TextFieldProps.runs.specialCasePropsandmovedSpecialPath(legacy_paths.dart): what each removed prop is now, for validation andmovedPathHint.- Validation: a layout value written as it decodes is not an unknown key.
"widthFactor": 0(anywidthFactor/heightFactor) was reported asunknown_layout_key, with a message listingwidthFactoramong the valid keys:readsKeytook a value that encodes back unchanged for one kept verbatim in an extra map. It now probes the key with a value no reader takes. - Name conformance (
tool/name_conformance.dart): the 21 (d) verdicts go;textField.runs(b), the grid placement fields (c) anditemSnapping(b) are classified. docs/design/10-audit-verdict.md section 6 re-measured; docs/design/schema-3-migration-report.md's note after 30.1.0 regenerated over the corpus.
A site looks like itself: theme mode, declared fonts, local images. Additions only; documents stay
Design systems as data; controls that are not Material-shaped. Additions and default changes; documents stay
"schema": 3.
DesignSystem(design_system.json:DesignSystemManifest): DESIGN.md (principles), the tokens (a theme), PATTERNS.md and component definitions by reference, plusfonts,examplesandreplaces(the base controls its components stand in for).DesignSystem.load(read)reads one from a folder or a publish;fromJson/toJsonis one bundle.themeUnder(site),libraryUnder(site),catalogOver(base),list(each component's purpose and minimal call).site.json'sdesignSystemnames one (a folder relative to the manifest, or a publish id): its tokens are the site's base theme, its components callable by type.- Named theme scales:
spacing,radii,sizes,shadows(withdarkshadows),durations,curves, read as${theme.<scale>.<name>};ThemeTokens.mergedWith.validateThemechecks them; a binding naming a step the theme does not have isunknown_theme_name. - The prompt:
runtimeStarter(designSystem:)adds a section generated from it (principles and patterns in brief, tokens by name, each component with parameters, slots, events and a call) and drops the base controls it replaces;docsTopic(designSystem:)answersdesign,patterns,tokensand a component's name. A design-systems page joins the reference. - Colors that follow the theme:
tabBar(indicatorColor,labelColor,unselectedLabelColor,dividerColor),pagination(textColor,activeColor,activeTextColor,borderColor), the gauges', charts', barcode's and signature pad's palettes are now optional, unset meaning the theme's role (documented per prop): values and linesprimary, tracks and gridsoutlineVariant, ticks and axesoutline, labelsonSurfaceVariant, needles, cursors and tooltipsonSurface. dropdown.underlinenow means the field's border (the theme's outline), never Material's underline.
Earlier in this release: a site looks like itself: theme mode, declared fonts, local images. Additions only; documents stay
"schema": 3.
-
Theme mode (Flutter's
ThemeMode):ThemeTokens.mode("mode": "system" | "light" | "dark"in a theme, defaultsystem) is the mode a site starts in, and thesetThemeModeaction ({"type": "setThemeMode", "mode": "${= theme.isDark ? 'light' : 'dark'}"};modeis an expression,persistdefaults to true) changes it.ThemeMode.isDark(platformDark:)andThemeMode.tryParse. Validation reports a bad mode, or amodeinsidedarkor a media patch (invalid_theme). -
Site fonts:
SiteManifest.fonts, a list ofFontFamily(family,fonts:FontAssetwithasset,weight,style) in the shape of a pubspec'sfonts:section, the files besidesite.json.PublishFont.ofFamiliespublishes them one per file withurlthe path relative to the site (PublishFont.isSiteFile; idsFamily/weight/italic,PublishFont.idOf).validateSiteFontsreports a bad shape (invalid_fonts) and a file that is not.ttf,.otfor.woff(font_format; WOFF2 is not read). -
Site files:
isRelativeAssetPath, andPublishSource.assetPath(publish/{slug}/files/{path}), where a published site's fonts and images named by a relative path are served. -
Reference: theme mode, declared fonts and local images in the base (
STARTER.md); theme.md's dark mode and fonts sections rewritten; decoration.md's images section (local files,BoxFit/Alignment) and a new illustration section, with three validated examples (a photo card with a gradient scrim, an SVG illustration and apathmark, acustomPaintscene); render.md's--themeandfont_missing. -
Node ids are per document; only canvas ids are site-wide.
duplicate_idnow reports a canvas id two documents of a project share (navigateandopenModalname screens by it, so a link reaches one of them), and no longer every node id two pages share: a page's actions and conditions name its own nodes, a component's ids are its own. The base says so. -
Did you mean, by meaning.
nearest(thesuggestionofunknown_action_key,invalid_enumand the other name checks) falls back to the name an author usually means when none is spelled close:target→node,content/value→text,append/push→add,if/predicate→condition,screen→to. Anifwhoseconditionis a formula string is told the predicate to write ({"left": "${= ...}", "op": "isTrue"}). -
Reference: a complete multi-page site (components, "A complete multi-page site";
tool/reference/examples/site/, validated as one project by the reference test): the manifest first with every page listed, a header and a footer shared by reference, route parameters with a default, storage restored on load, a list kept per route under a key built from${route.id}, and a modal opened from a component. The base says to list every page insite.jsonbefore writing pages that link to them. -
Reference: the names authors guessed wrong, in short examples where they look:
scrollTo.node(layout),downloadFile.fileNameandtext(media),copyToClipboard.text(interaction), theifpredicate (state),setStorageops (addappends,insertat anindex) and keys per route (data). New patterns: scroll progress (layout), entrances on scroll withanimations[].visibleFractionversus therevealbehavior, which scrolls (animation), pinningnow()with the render command's--now(animation), spacing and radius scales (theme: there are no such tokens; a project variable map). The render page covers--drag,--navigatewith a query string,--now,--compare-map, what a run keeps, and full-page captures of sticky nodes, modals and navigation. -
A stroke path's draw-on animation migrates to the general pieces.
strokePath.drawMs(withdrawDelayMs,drawCurve) was kept aslegacy.strokePath.drawand no longer drawn;paint.strokePathnow writes an animationstrokePathDrawwhose track draws the line op'strimEndfrom 0 to its own value (the fill's paint from transparent), played when the node appears, and a transition of thattrimEndwith the same timing; a bound progress becomes a binding ofcustomPaint.<painter>.strokePath.trimEnd. Frame for frame the old painter's drawing (codelessly_sdk'sstroke_draw_on_test.dart), except a progress that changes while the line is still drawing on. A literaldrawKeyis dropped (it never changed).legacy.strokePath.drawis no longer written. -
BindPaths.declaredDefault(node, path): the declared default at a binding path (opacity,props.*,layout.*,decoration.*, a custom paint op's field), the node's value there when its JSON omits the field. An animation track with nofromortouses it (codelessly_sdk), so a track can end at an op's defaulttrimEnd1. -
Name conformance, re-measured (
tool/name_conformance.dart; docs/design/10-audit-verdict.md, section 6, and docs/design/name-conformance.md): 61% of the 863 declared fields of the Flutter-mirroring node types and shared groups are Flutter's name and meaning, 78% of those with a Flutter counterpart; 21 special-case fields are listed with a recommendation. -
A time picker's
use24hisalwaysUse24HourFormat(Flutter'sMediaQueryData.alwaysUse24HourFormat, which the picker reads). Stepprops.renamed(inmigrate2to3's one-way steps) renames the prop, its binding, state and media patches andsetValue/condition paths in a schema-2 document; in a schema-3 documentuse24his refused (unknown_prop) naming the new spelling, andmovedPathHint('props.use24h')gives it. No document in the corpus or either repository used it. -
State patches that targeted
selfor@<key>now run. A state patch names the node it patches by id; generated schema-2 documents also wroteselfand@<key>(the node's key), which matched no node, so those hover, press and selection styles never applied (1131 patches in 9 corpus documents, all naming the node their states are on).migrate2to3's first step,states.target, rewrites them to the id they mean and reports a behavior change. In a schema-3 document validation refuses them (unknown_target_node) with the id to write as the suggestion.
Forms, grid placement and scroll control, in Flutter's shape (and CSS's where the responsive model follows the web); documents written for 30.1.0 load unchanged.
- Forms.
textField.validatoris Flutter'sTextFormField.validator: an expression that reads the typed text asvalueand gives the error to show (""when valid), checked by validation withvalueas a name. The object form older documents saved ({"type": "required"},{"type": "email"}, never applied) reads as the expression it named.AutovalidateModegains Flutter'sonUserInteractionIfError. formbehavior (Flutter'sForm, withautovalidateMode): the fields inside validate together; its nodes read${form.valid}and${form.errors}({field, label, message}, top to bottom).formis a runtime scope.validateaction (FormState.validate()): every field of the form (node, else the form around the reaction's node) shows its error, the first invalid one takes the focus (focusFirstError),${result}is whether all are valid.radioGroupbehavior (Flutter'sRadioGroup): radios inside take its bindablegroupValue; choosing one runs the group'schangedreactions.- Grid placement.
layout.columnSpan,rowSpan(CSSgrid-column: span n) andcolumnStart,rowStart(grid-column-start, 1 the first) are child fields agridViewreads; elsewherelayout_field_ignored. - Scroll control.
itemSnappingon scrolling rows, columns, lists and grids (PageView.pageSnappingfor items; CSSscroll-snap-align: start); thescrollandscrollEndtriggers document${result.index}(the item at the start of the view) and${result.count}. - Validation.
state_no_effect: a boundselectedwith nostates.selectedpatch changes nothing (a chip's selection isprops.selected). - Reference. Worked, validated examples: a complete contact form (per-field errors on blur and send, a summary,
a radio group, a success state), an editorial page at 390/834/1440 (one column, a split with a sticky rail, a
three-column river with a spanning lead), a timetable that is a list on a phone, and a carousel with arrows, dots,
progress and snapping. The base says to use the width at tablet and desktop. Where node-given names are read
(
pageOffsetis a page view's, not a page's scroll), and how runs that cut an expression count, are stated.
Earlier in 30.1.0 #
One spelling for each concept; the schema stays 3. Documents are still "schema": 3 (kSchemaVersion), and
schema-2 documents still load, migrated in memory by migrate2to3, whose last steps now give each concept that
30.0.0 could say two ways one spelling, under Flutter's name. 30.0.0's schema-3 documents keep loading as
schema 3; but a schema-3 document is read as it is, not upgraded, so one written with the earlier spellings below
must be updated once (the migration does it to schema-2 documents; validation reports each earlier spelling in a
schema-3 document as an error naming the one to write). docs/guide/12-migrating-to-schema-3.md ("30.1.0") is the
authors' guide; docs/design/schema-3-migration-report.md the migration over the corpus (106 documents, 0 failures,
3502 rewrites of which 1020 by the new steps; 5 behavior changes by the new steps, all a box path's, in two m05
experiments).
| 30.0.0 (schema 3) | 30.1.0 (schema 3) |
|---|---|
a node's "scale": s |
"motion": {"scale": s × the motion's own} |
"layout": {"rotation": r} |
"motion": {"rotate": r + the motion's own} (an uneven margin's pivot offset as motion.translateX/Y) |
flightKey, flight |
"hero": {"tag": ..., "flies": "inPlace", "flight": {...}} |
"hero": {"flight": "<look>"} |
"hero": {"flightShuttle": "<look>"} |
"strokePath": {...} |
a customPaint path op (points or commands, trimEnd for the progress) |
a box with props.path, strokeJoin, strokeMiterLimit |
a path node, the path as props.data |
a path's subpathColors |
one customPaint path op per color |
a paint's gradientPerSubpath |
one customPaint path op per shape, the gradient as its paint's shader |
binding, transition, track, setValue and condition paths scale, layout.rotation, flightKey, flight.*, hero.flight (a look), strokePath.*, props.path, props.subpathColors |
motion.scale, motion.rotate, hero.tag, hero.flight.*, hero.flightShuttle, the custom paint op's fields, props.data |
- Docs: controls take the theme, never Material's defaults. The reference's base and its theme page say what
controls take from the theme's roles (
primaryfills filled buttons and draws checks, thumbs and text-button labels where it reads onsurface;fontFamilyevery control label;buttonRadiusevery button and chip), that without a theme they are neutral (ink on paper and the greys between), and that nothing comes from Material's defaults or from the host app's theme. No API change: the roles already cover it (outlines and tints are derived fromonSurfaceoversurface, so nooutlinerole is added). - Breaking, Dart: fields removed.
Behaviors.scale,Layout.rotation,BehaviorFields.scale,LayoutFields.rotation,BindPaths.scale,BindPaths.rotation;Behaviors.flightKey,Behaviors.flight,BehaviorFields.flightKey,BehaviorFields.flight(HeroTaggainsflies,HeroFliesandflight; its look isflightShuttle);StrokePath,PathUnit,PathCurve,StrokePathFields,strokePathType,BehaviorFields.strokePath,Behaviors.strokePath;BoxProps.path,BoxProps.strokeJoin,BoxProps.strokeMiterLimit;PathProps.subpathColors;Paint.gradientPerSubpath,PaintFields.gradientPerSubpath; thedeprecated_keydiagnostic. The catalog's declared fields go from 2121 to 2099 for the paint fields alone. - Added: a
customPaintpath op'scommands(Flutter'sPathcallsmoveTo,lineTo,quadraticBezierTo,cubicTo,close, each number a literal or a formula, each call with an optionalwhen;PathCommand,PathOpFields.commands);PathProps.strokeMiterLimit;migrateDocument,migrateNode(any schema to 3) andmigrateJson;MigrationScope.document(a node step reads the document it is in);movedPathHintandolderSchemaPathHint(what to write for a moved path set at run time). - The migration's new steps (
steps_spellings.dart,steps_transform.dart,steps_hero.dart,steps_paint.dart), after schema 2's:transform.fold(scale multiplied intomotion.scale, rotation added tomotion.rotate, the pivot kept, bindings, transitions, tracks and keyframes moved),hero.flight,paths.moved(setValueand condition paths), the paint steps (paint.patches,paint.strokePath,paint.boxPath,paint.perShape; what has no exact form is kept aslegacy.<name>and reported, e.g. the draw-on animation aslegacy.strokePath.draw), thenpatches.moved(state and media patches). Rendered before and after, every affected corpus node draws the same pixels except a box path's filled edge (at most 4/255) and a box path reaching outside its box, now filled there too (reported). - Validation: an earlier spelling in a schema-3 document is an error naming the one spelling
(
unknown_node_key,unknown_layout_key,unknown_prop,unknown_field,unknown_bind_pathfor a binding, transition, track,setValueor condition path,wrong_typefor a look written ashero.flight). A custom paint's ops may readsize, and itsviewBoxmay be[width, height](as the decoder reads and writes it). Alegacy.<name>islegacy_value(a warning), held inNode.extra, never drawn. - The plot chart's Cartesian props stay: they are the chart's general features (docs/design/01-paint-node.md, "30.1.0").
- Reference: regenerated; one spelling for each concept throughout.
The reference for authors is one base plus links. docs/reference/STARTER.md is the base an agent reads in
full (the document and the flat node map; layout, decoration, text with a theme; the base node types and which
types take children or slots; variables, bindings, reactions; media rules; the rules that are easy to get wrong;
an index); every other feature area is a page with the same six sections (When to use, Minimal example,
Reference, Patterns, Pitfalls, See also); index.md maps needs and every declared name to their section. Each
node type, behavior, trigger, action, model, enum, value type and formula function is on exactly one page
(tool/reference/src/areas.dart; a test checks it, and that every link and anchor resolves).
- One base, two forms.
baseDocument({form, catalog, profile, kind, docsTool})assembles the base from the generated segments oftool/reference/templates/base.md:BaseForm.filesisSTARTER.md(with checking your work and sites as files),BaseForm.runtimeisruntimeStarter()andRUNTIME_STARTER.md(with the answering rules, the ops and two examples). The runtime base is about three times the earlier one (≈ 43k characters against 15k): it now carries the theme, layout patterns, the children table and the index. ui_docsserves the pages.docsTopicanswers a page (When to use, minimal example, pitfalls, its sections), any section by its anchor, or any node type, action, trigger or behavior by name;docsIndexis the index the base ends with;docPages,docTasksare the generated data;toRuntimeLinksturns the files' links intoui_docstopics. Earlier topic names (responsive,reactions,gestures,scripts...) still answer.starterProps,behaviorAreasandguideTopicsare gone (baseProps,docPages).- Machine forms.
catalog.jsonnames each node type's, action's, behavior's and trigger's page and anchor (docs);index.jsonlists every topic with its file, anchor, summary and size. - Retired.
nodes.md,behaviors.md,triggers.md,actions.md,bindings.md,formulas.mdandvariables-conditions-scripts.mdare stubs that keep their anchors and say where each item went; the old guide'sindex.md#guide-...anchors land on a table of where each section went;API_REFERENCE.compact.mdis gone (the base's runtime form replaces it);API_REFERENCE.mdis the base, the index and the pages in order. - Docs at the declarations for the props and fields the base shows.
30.0.0 #
Schema 3: the one planned format break. Documents are "schema": 3. Schema 2 documents load and are
migrated in memory; write schema 3. LayoutDocument.fromJson (and PublishModel, PublishBundle,
PublishLayout, PublishComponent, ComponentDefinition, the site manifest and plugin packages, through
the documents they hold) migrates a schema-2 document (or one with no schema) before decoding it; encoders
write "schema": 3. The guide's new chapter, docs/guide/12-migrating-to-schema-3.md, is the authors' migration
guide; docs/design/schema-3-migration-report.md is the migration over the reference apps and experiments.
- The migration:
migrate2to3(Json document, {MigrationReport? report})(pure, total, idempotent),migrateNode2to3,migratePublish2to3,migrateJson2to3(any file that carries documents; a stored payload or a stored published component, whose digest covers what was stored, is migrated when read),schemaOf,kSchemaVersion= 3,kPublishSchemaVersion= 3,schema3Steps(namedMigrationSteps).MigrationReportlists every rewrite, every value with no schema-3 form (kept on the node aslegacy.<name>, unread, with what to write instead) and every behavior change;migrationReportMarkdown. Commands:dart run tool/migrate.dart <file|dir> [--write] [--report out.json],dart run tool/migration_corpus.dart(corpus checks and the aggregated report). - Validation:
validateDocumentreads 2 and 3: a schema-2 document gets theschema_outdatednote (Severity.info) and is validated as migrated;legacy_value(warning) flags a kept value; an expression is accepted where a field takes one inline (ExprCodec: a timer'sintervalMs). - Breaking (Dart): the legacy readers are gone from the model; the migration has them.
Behaviors.migrateBind,Behaviors.legacyKeys,Behaviors.effectiveTransformGesture(usetransformGesture),TransformGesture.zoomable,DragRelease,Spring.legacy,PathFollow.fromLegacy,Track.fromLegacyDrag,Track.readsOnly,DismissibleBehavior.fromLegacyDrag,Pan.fromLegacyDrag,AnimationPresets.fromLoop,fromEffect,fromMotion,fromPulseKey,legacyLoopMode,loopTypes,effectTypes,legacyMotionSpring;SetVariableAction.animateMsandcurve(SetVariableFields.animateMs,curve). Decoders no longer readloops,effectAnimations, motion's temporal keys,opacity,blur,originX/Yand flat path keys,drag,zoomable, a track'sendAngle/endless/jumpOnTap/wheel/keyboard/momentum/friction/write/settleStiffness/path string, a draggable'swhileDragging/feedbackNodeId/feedbackAnchor/dragAnchorStrategy/spring*/physics, flat physics springs, thetransitionsobject and map,gradientUnits,playAnimation,animateVariable,setVariable.animateMs,controlDrag, theclocktrigger: in a schema-3 document they are unknown keys (kept, unread). - Breaking (Dart and JSON): the deprecated one-app fields are removed (the migration keeps a value that
did something as
legacy.<behavior>.<field>and reports what to write instead):Track.defaultValue,doubleTapValues,parkedProgress,fineStep,finePixelsPerRange,fineHold,fineVariable,smooth,gain(andhasFine,isParked,doubleTapTarget,effectiveFinePixelsPerRange,${track.fine});DismissibleBehavior.restX,restY,xVariable,yVariable,flyOutRotate; onDismissibleBehaviorandPan:rotateFactor,originX,originY,shakeWhenDisabled,disabledFollow,shareAs,follow;PathFollow.pacing,focus,pacedByArea,headsLeft,PathPacing,PathOrient.uprightFlip(nowupright);Transition.arc;DropTarget.fullIf,slotWhenRefused(the slot opens for accepted drags only),hoverDelay, and thedropFullanddragHovertriggers;GestureSnap.projectVelocity(a snap always projects the fling);TransformGesture.rotationSnap;OpenModalAction.showCloseButton,fullHeight(never read). Their*Fieldsdeclarations go with them. - Flutter's reading where schema 2 had its own (the migration writes out what schema 2 did, so migrated
documents render the same): a text's
layout.paddingis applied (Padding(child: Text), counted in a hugging size); schema 2 ignored it and the migration drops it from schema-2 texts (steptext.padding, with the bindings and state and media patches that set it). Thelayout_field_ignoredwarning for a text's padding is gone. A text style without aheighttakes the inheriteddefaultTextStyle(new behavior on any node, Flutter'sDefaultTextStyle: the nearest one wins,{}gives Flutter's defaults back), else the font's own line height (Flutter'sheight: null), not 1.33; the migration keeps 1.33 for schema-2 documents with one"defaultTextStyle": {"height": 1.33}per top-level node (steptext.lineHeight; +0.08% bytes over the corpus). Breaking (Dart and JSON):TextStyle.naturalHeight(TextStyleFields.naturalHeight),ThemeTokens.naturalLineHeightandStyleSheet.naturalLineHeightare removed; the migration turns a natural style into its node's"defaultTextStyle": {}, and drops (reporting) a theme's flags, which a document migrated on its own cannot see.migrateJson2to3andmigratePublish2to3drop them from carriers;dropNaturalLineHeightFlags.tool/migration_corpus.dartreports the encoded size before and after. - Paths an action names (
setValue'svalues[].path) are not migrated:schema2PathHint(path)gives the schema-3 path for a schema-2 one, andunknown_bind_pathsays it (motion.originX→motion.alignment,loops[i].<key>→animations.loop<i>.<key>,drag.track.<key>→track.<key>...). - Behavior changes (all reported by the migration, per document): a track with no value is drawn at
its minimum, not at
defaultValue, and a double tap resets nothing; the fine mode,smooth, a dismissible's tilt and fly-off spin, disabled follow and shake,shareAs, area pacing, the upright flip, a transition's arc,fullIf/dropFulland a hover delay no longer act; a refused drag opens no list slot; asetVariableglide that is not a set, add or subtract by one formula sets at once. Over the corpus: cutroom's fine step and safecracker'ssmooth(docs/design/schema-3-migration-report.md).
Streaming generative UI, hardened against real model output
OpStreamDecoderrecovers every well-formed op from tool input that is not valid JSON (eager tool input streaming does not promise it; a recorded live generation closed one brace too many three times): a repaired copy of the text (stray closers dropped, missing ones inferred, trailing commas removed, missing commas inserted), op objects read at any depth outside another op, re-synchronisation when an op begins before the previous one closed. Each repair is onemalformed_inputwarning with the character offset;OpStreamEnd.repairsand.recovered;StreamedOp.recovered. A set op's node fields written beside"node"move into it (misplaced_field). Property tests: any chunking yields the same ops; 2,000 single brace, bracket or comma edits lose no op but the one they land in; the three recorded live generations decode whole (24, 50, 34 ops).- The retry protocol:
EditResult.toModelJson()says what the document holds (ids set, patched, moved, removed; roots, node count, pending) and, when anything is rejected or pending,next(fix by patching, same ids, never start over);fixInstruction;EditResult.withDiagnostics.applyOps(protectRoots: true)answers a batch that would replace the roots or add a canvas withstart_over.explainDiagnosticspells out the fix for the codes models hit (unknown_layout_key hug,children_not_allowedandinvalid_parentwith the types that take children, a button'stext,would_orphan,canvas_as_child);atOpmoves the op path with the index. uiLints:empty_button,low_contrastand, with aGlyphCoverage,missing_glyph(with the icon to use); codesno_sizefor renderers;fontCodepointsreads a font's cmap.- The runtime docs:
runtimeStarteris the base set a chat card or small screen needs (layout, decoration and text essentials; one table of the base node types with what takes children and their key props, the button family and the inputs and lists included; state, bindings, reactions; two examples that apply cleanly), generated from the declarations;docsTopicanswers theui_docstool for any node type, action type, trigger, behavior or feature area (the guide's sections,guide_topics.g.dartwritten by the reference generator);docsIndexis the base's index.uiTools(catalog, compact: true, docs: true): the op envelope strictly plusui_docs;ui_readtakestypes(describeTypes). Generated:docs/reference/RUNTIME_STARTER.md,ui_tools.compact.json. TrustProfile.agentApps:agentplus the document's sandboxed scripts (capabilitiesvariables.read,variables.write,clock;TrustProfile.scriptCapabilities). Thescriptsop sets and removes them by name (ScriptsOp,invalid_script), with an inverse for undo.
Components in published apps, hosted plugins as components (sections and components, phase 2)
PublishModel.components({type: {version, digest, lastUpdated, fonts}},PublishComponentInfo),PublishLayoutInfo.components(the closure a layout calls),PublishComponent(stored atPublishSource.componentPath:publish/{p}/components/{type},{"schema": 2, "id", "version", "digest", "document"}; a document decoded from a store is written back as stored),PublishBundle.componentsandPublishBundle.extra.PublishModel.fontsOfadds the fonts of the components a layout calls.canonicalJson: what a component's digest (sha256, computed by the publisher) is over.- Hosted plugins on the components' path:
PluginWidget.definitionJsonandPluginPackage.definitionsturn a plugin node type into a component definition (its catalog declaration aswidget, its slots asslotnodes, its events declared, its formula functions as the root's variables).PublishBundlePlugins(pluginVersions,withPluginVersions): plugin payloads embedded in a bundle. - Validation:
repeated_subtree, a newSeverity.info: a subtree of three or more nodes written several times over, node for node (ids and names aside), with the copies' ids: "consider a component or a list template". Only exact repeats; a repeat inside a reported one is not reported again. - Docs: DESIGN.md §2.1, §4.2, §4.3, §5.4; docs/design/06 and 05 "Done" / "Not done"; the guide's components
section (published sites, per-instance rules, slots inside lists, plugins as hosted components,
--components-all,repeated_subtree).
Authoring fixes from the third direct-authoring experiment (cycle 3)
- Named colors and text styles. The site manifest declares the project's theme (
SiteManifest.theme: colors, text styles, roles,dark, andThemeTokens.media, rules that patch the theme by screen size); a color field may name one of its colors ("color": "ember", kept through decode and encode asColor.named) and a text style may start from a named one ("style": "title", or{"from": "title", ...}:TextStyle.from, merged asTextStyle.merge).ThemeTokens.color,textStyle(resolved:fromchains, colors by name, aliases),atScreen;ThemeRefs/resolveThemeRefsresolve a node or a document by its declarations (props, decoration, behaviors, media and state patches), leaving the nodes that name nothing the same objects.Color.fromHexreads values only (the oldfromJson). A media or state patch that names another style replaces the style; one that changes fields merges over the named style. New diagnosticsunknown_theme_name(with the nearest name) andinvalid_theme;validateTheme;ValidateOptions.theme(the manifest's by default). Behavior change (documents that validated stay the same): a color string that is neither a hex color nor anything else ("blue") decoded to null and now decodes as an unresolved theme name (transparent); validation reported it before and reports it now. IconProps.size(Flutter'sIcon.size).- A media rule's patch may set
bind(bindings at its sizes only;nulldrops one of the node's) andmotion(a paint-only transform).media_overriddensays how to combine a rule and a binding. layout_clampedpoints to the overlap patterns (motion translate, a stack).- Docs: the guide and the starter lead with the theme; overlapping a neighbor, bleeding past the gutter, a
verified full-width band with capped content and a table from one cell template, form control styling,
foregroundFillsover children, a literal$before an expression, superscripts, arrow keys throughkeyDown, component parameter kinds; the allowed-modes table marks fill withbasisin a wrapping row;bindings.mdlists what each path expects.
Authoring fixes from the second direct-authoring experiment (cycle 2)