codelessly_api 30.0.0
codelessly_api: ^30.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.
Unreleased #
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 behaviour 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>...). - Behaviour 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). Behaviour 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 neighbour, 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)