feat(parser): alias flex-wrap to wrap and warn on unknown classNames (WIND-5) by anilcancakir · Pull Request #147 · fluttersdk/wind

anilcancakir · 2026-07-07T14:08:55Z

What (WIND-5)

Two developer-experience fixes for silent failures:

flex-wrap -> wrap alias: FlexboxGridParser now maps the Tailwind spelling flex-wrap directly to WindDisplayType.wrap (canParse already accepted flex-*; only the parse() handler was missing). wrap stays the canonical token; flex-wrap prints a one-time kDebugMode hint pointing at it.
Unknown-className warning: WindParser.findAndGroupClasses now emits a one-time kDebugMode debugPrint naming any className no parser recognizes (deduped per unique token per session, via the existing _warnedAliases set). The token is still dropped; release builds print nothing.

An allowlist (_knownUnparsedTokens) exempts valid tokens handled outside the parser map so the warning targets genuine typos, not wind's own vocabulary: the widget-consumed object-* fit family, the inline-* display keywords (emitted by WBadge), and inert compat tokens (transition-colors, antialiased, sr-only, the *-nums family). Verified by an exhaustive sweep of all 20 parsers vs every runtime-emitted className.

Why

flex-wrap from a web codebase silently no-opped; a typo'd className silently no-opped forever. Both now surface a debug hint without changing release behavior.

Changes

lib/src/parser/parsers/flexbox_grid_parser.dart, lib/src/parser/wind_parser.dart (+ tests).
13 example pages switched flex-wrap -> wrap.
5-surface doc sync: skills/wind-ui/SKILL.md (2.8.2 -> 2.9.0), skills/wind-ui/references/tailwind-divergence.md, doc/layout/display.md, CHANGELOG.md.

Verification

dart analyze clean, dart format clean, flutter test green (incl. the flex-wrap alias, one-warning-per-token, and allowlist regression tests).

Note

Shares CHANGELOG.md / SKILL.md / tailwind-divergence.md with the WIND-1/3/4 PRs (they were developed as one plan). Whichever merges first, the others need a trivial rebase on those doc surfaces.

Summary by CodeRabbit

New Features
- Added support for the flex-wrap spelling as an alias for wrap.
- Unknown class tokens now surface a one-time debug hint in development builds instead of failing silently.
Documentation
- Updated layout docs, examples, and guidance to use wrap as the canonical token.
- Clarified when unknown or unsupported tokens are warned about versus dropped quietly.

…t silently (WIND-5)

… (WIND-5)

…faces (WIND-5)

…warning (WIND-5)

… tokens (WIND-5)

coderabbitai · 2026-07-07T14:09:05Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 94b35418-e5d2-41af-9d8d-fd2f0bfbbbe5

📥 Commits

Reviewing files that changed from the base of the PR and between 41b23a3 and 72617d8.

📒 Files selected for processing (21)

CHANGELOG.md
doc/layout/display.md
example/lib/pages/backgrounds/colors.dart
example/lib/pages/layout/flex_intro.dart
example/lib/pages/layout/z_index.dart
example/lib/pages/popover/popover_alignment.dart
example/lib/pages/responsive/card.dart
example/lib/pages/responsive/grid.dart
example/lib/pages/responsive/layout.dart
example/lib/pages/responsive/spacing.dart
example/lib/pages/responsive/typography.dart
example/lib/pages/responsive/visibility.dart
example/lib/pages/sizing/aspectratio.dart
example/lib/pages/typography/colors.dart
example/lib/pages/widgets/wind_animation_wrapper_basic.dart
lib/src/parser/parsers/flexbox_grid_parser.dart
lib/src/parser/wind_parser.dart
skills/wind-ui/SKILL.md
skills/wind-ui/references/tailwind-divergence.md
test/parser/parsers/flexbox_grid_parser_test.dart
test/parser/wind_parser_test.dart

📝 Walkthrough

Walkthrough

This PR aliases the Tailwind flex-wrap token to Wind's canonical wrap display type in FlexboxGridParser, emitting a one-time debug hint. WindParser now warns once per unrecognized className token (excluding an allowlist of intentionally inert/externally-handled tokens). Example pages, tests, and documentation are updated accordingly.

Changes

flex-wrap alias and unknown-token diagnostics

Layer / File(s)	Summary
FlexboxGridParser alias implementation `lib/src/parser/parsers/flexbox_grid_parser.dart`	Adds a `parse()` branch mapping `flex-wrap` to `WindDisplayType.wrap`, plus debug-hint infrastructure (`_warnedFlexWrapAlias`, helper, `resetWarnings()`) and updated doc comments.
FlexboxGridParser alias tests `test/parser/parsers/flexbox_grid_parser_test.dart`	Adds `resetWarnings()` calls in setUp, a parse test, a `canParse` assertion, and a debug-hint-once test group.
WindParser unknown-token diagnostics `lib/src/parser/wind_parser.dart`, `test/parser/wind_parser_test.dart`	Introduces `_knownUnparsedTokens` allowlist and `_warnUnknownToken` to emit a one-time debug warning for unclaimed class tokens in `findAndGroupClasses`, with corresponding tests.
Example pages updated to use wrap `example/lib/pages/backgrounds/colors.dart`, `example/lib/pages/layout/`, `example/lib/pages/popover/popover_alignment.dart`, `example/lib/pages/responsive/`, `example/lib/pages/sizing/aspectratio.dart`, `example/lib/pages/typography/colors.dart`, `example/lib/pages/widgets/wind_animation_wrapper_basic.dart`	Replaces `flex-wrap` with `wrap` in `className` strings across example pages, keeping other layout classes unchanged.
Documentation updates `CHANGELOG.md`, `doc/layout/display.md`, `skills/wind-ui/SKILL.md`, `skills/wind-ui/references/tailwind-divergence.md`	Documents the `flex-wrap`→`wrap` alias, its debug hint, and the new unknown-token debug diagnostic behavior, replacing prior "silent no-op" descriptions.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

fluttersdk/wind#90: Both PRs modify lib/src/parser/wind_parser.dart's debug diagnostics behavior around token handling.
fluttersdk/wind#97: Both PRs modify flex-related parsing logic in lib/src/parser/parsers/flexbox_grid_parser.dart.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/flex-wrap-alias-unknown-token-warning

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

codecov · 2026-07-07T14:13:12Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Copilot

Pull request overview

This PR improves Wind’s developer experience by (1) adding a Tailwind-compat alias for flex-wrap and (2) emitting debug-only warnings for dropped className tokens that no parser recognizes, while keeping release behavior unchanged.

Changes:

Added flex-wrap → wrap alias in FlexboxGridParser, with a one-time kDebugMode hint.
Added a one-time kDebugMode unknown-token warning in WindParser.findAndGroupClasses, plus an allowlist for valid tokens handled outside the parser map.
Updated docs/skill references and migrated example pages from flex-wrap to canonical wrap; added/updated tests for the new diagnostics.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/parser/wind_parser_test.dart	Adds coverage for dropping unknown tokens and for one-time unknown-token debug warnings with allowlist exemptions.
test/parser/parsers/flexbox_grid_parser_test.dart	Adds tests for `flex-wrap` alias behavior and one-time alias-hint logging; resets warning state for determinism.
skills/wind-ui/SKILL.md	Updates the skill text to describe `flex-wrap` alias and the new debug-only unknown-token behavior.
skills/wind-ui/references/tailwind-divergence.md	Updates Tailwind divergence guidance to reflect the alias and the new debug-only unknown-token diagnostics.
lib/src/parser/wind_parser.dart	Implements the unknown-token warning (debug-only, warn-once) and introduces a `_knownUnparsedTokens` allowlist.
lib/src/parser/parsers/flexbox_grid_parser.dart	Implements `flex-wrap` → `wrap` alias and a one-time debug hint (plus test-only reset hook).
example/lib/pages/widgets/wind_animation_wrapper_basic.dart	Replaces `flex-wrap` usage with canonical `wrap` in examples.
example/lib/pages/typography/colors.dart	Replaces `flex-wrap` usage with canonical `wrap` in examples.
example/lib/pages/sizing/aspectratio.dart	Replaces `flex-wrap` usage with canonical `wrap` in examples.
example/lib/pages/responsive/visibility.dart	Replaces `flex-wrap` usage with canonical `wrap` in examples.
example/lib/pages/responsive/typography.dart	Replaces `flex-wrap` usage with canonical `wrap` in examples.
example/lib/pages/responsive/spacing.dart	Replaces `flex-wrap` usage with canonical `wrap` in examples.
example/lib/pages/responsive/layout.dart	Replaces `flex-wrap` usage with canonical `wrap` in examples.
example/lib/pages/responsive/grid.dart	Replaces `flex-wrap` usage with canonical `wrap` in examples.
example/lib/pages/responsive/card.dart	Replaces `flex-wrap` usage with canonical `wrap` in examples.
example/lib/pages/popover/popover_alignment.dart	Replaces `flex-wrap` usage with canonical `wrap` in examples.
example/lib/pages/layout/z_index.dart	Replaces `flex-wrap` usage with canonical `wrap` in examples.
example/lib/pages/layout/flex_intro.dart	Updates explanatory copy to acknowledge the alias and prefer canonical `wrap`.
example/lib/pages/backgrounds/colors.dart	Replaces `flex-wrap` usage with canonical `wrap` in examples.
doc/layout/display.md	Updates display docs to explain `wrap` vs `flex` and note the `flex-wrap` alias + debug hint.
CHANGELOG.md	Records the alias + debug-diagnostic behavior changes and associated doc/example updates under Unreleased.

The hint fires only when no parser's canParse matches the token (unknown family). A recognized family with an unsupported value (text-7xl, claimed by text-*; flex-cow, matching flex-*) still drops silently with no hint. Corrects Core Law 6, the migration table, and the tailwind-divergence unknown-tokens row, which overpromised the hint's reach.

anilcancakir · 2026-07-07T14:28:06Z

@coderabbitai review

coderabbitai · 2026-07-07T14:28:12Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

… suite output quiet

anilcancakir · 2026-07-07T14:52:11Z

@coderabbitai review

coderabbitai · 2026-07-07T14:52:18Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

…s-unknown-token-warning # Conflicts: # CHANGELOG.md

anilcancakir added 6 commits July 7, 2026 17:06

feat(flex): alias flex-wrap to wrap with a one-time debug hint (WIND-5)

5fa7744

feat(parser): warn once on an unknown className instead of dropping i…

3466f82

…t silently (WIND-5)

refactor(examples): use the canonical wrap token instead of flex-wrap…

42a4029

… (WIND-5)

docs: reconcile the flex-wrap alias and unknown-token hint across sur…

bd2da50

…faces (WIND-5)

fix(parser): exempt valid unparsed tokens from the unknown-className …

652a9fd

…warning (WIND-5)

docs: note the unknown-className warning allowlist for valid unparsed…

eaf52dc

… tokens (WIND-5)

Copilot AI review requested due to automatic review settings July 7, 2026 14:08

Copilot started reviewing on behalf of anilcancakir July 7, 2026 14:09 View session

Copilot AI reviewed Jul 7, 2026

View reviewed changes

Comment thread skills/wind-ui/SKILL.md Outdated

Comment thread skills/wind-ui/SKILL.md Outdated

Comment thread skills/wind-ui/references/tailwind-divergence.md

anilcancakir requested a review from Copilot July 7, 2026 14:37

Copilot started reviewing on behalf of anilcancakir July 7, 2026 14:38 View session

Copilot AI reviewed Jul 7, 2026

View reviewed changes

Comment thread test/parser/wind_parser_test.dart

test(parser): silence the unknown-token hint in the drop test to keep…

1ce1dac

… suite output quiet

Merge remote-tracking branch 'origin/master' into feat/flex-wrap-alia…

72617d8

…s-unknown-token-warning # Conflicts: # CHANGELOG.md

anilcancakir merged commit 092cb10 into master Jul 7, 2026
10 of 11 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(parser): alias flex-wrap to wrap and warn on unknown classNames (WIND-5)#147

feat(parser): alias flex-wrap to wrap and warn on unknown classNames (WIND-5)#147
anilcancakir merged 9 commits into
masterfrom
feat/flex-wrap-alias-unknown-token-warning

anilcancakir commented Jul 7, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

Uh oh!

codecov Bot commented Jul 7, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

anilcancakir commented Jul 7, 2026

Uh oh!

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

anilcancakir commented Jul 7, 2026

Uh oh!

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

anilcancakir commented Jul 7, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What (WIND-5)

Why

Changes

Verification

Note

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Uh oh!

codecov Bot commented Jul 7, 2026

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

anilcancakir commented Jul 7, 2026

Uh oh!

coderabbitai Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

anilcancakir commented Jul 7, 2026

Uh oh!

coderabbitai Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

anilcancakir commented Jul 7, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading