Skip to content

CONTRACT_INVENTORY.md

Latest commit

 

History

History
304 lines (266 loc) · 19.9 KB

CONTRACT_INVENTORY.md

File metadata and controls

304 lines (266 loc) · 19.9 KB
Raw

Contract Inventory for Flutter Porting

Auto-generated by scripts/__inventory_gen_tmp.mjs. Scans every *.contract.ts under packages/ui/src/components/, extracts the flutter: hint from each Bc<Name>AdapterMapping interface, and cross-references docs/components-progress.md for tier assignments plus packages/ui-flutter/lib/src/components/ for Dart implementation status. The generator script (scripts/generate-flutter-stubs.mjs) defines the canonical 32-component WIDGET_MAP of flutter-hinted contracts.

Summary

  • Total contracts: 130
  • With flutter hints: 32 (P0: 24 hand-written/implemented, P1: 8 generated stubs pending implementation)
  • Without flutter hints: 98 (P0: 18, P1: 47, P2: 30, Special/other: 3)

Detection rules (per task spec):

  • Hand-written P0: Dart file exists and does NOT contain the Auto-generated by generate-flutter-stubs.mjs header. The stub generator protects these files from ever being overwritten.
  • Generated stub: Dart file exists and DOES contain the auto-generated header, with a TODO(<Component>): still present in build(). Needs hand implementation per the flutter hint.
  • Without flutter hint: contract has no flutter: entry in its Bc<Name>AdapterMapping interface. The stub generator skips these (no Dart target). They need a flutter hint added, then a stub, then a hand implementation.

Contracts WITH Flutter Hints (32)

P0 — Hand-written (24) — COMPLETE

These Dart widgets are fully implemented and protected from the stub generator. Each maps to a flutter_platform_widgets (Material + Cupertino) or Material-native primitive per its flutter hint.

Component Flutter Hint File
BcAccordion ExpansionPanelList-contract-parity lib/src/components/bc_accordion.dart
BcAlertDialog AlertDialog-contract-parity lib/src/components/bc_alert_dialog.dart
BcCheckbox Checkbox-onChanged-contract-parity lib/src/components/bc_checkbox.dart
BcCombobox Autocomplete-contract-parity lib/src/components/bc_combobox.dart
BcCommand search-delegate-contract-parity lib/src/components/bc_command.dart
BcContextMenu showMenu-contract-parity lib/src/components/bc_context_menu.dart
BcDataTable DataTable-contract-parity lib/src/components/bc_data_table.dart
BcDateField TextFormField-date-contract-parity lib/src/components/bc_date_field.dart
BcDialog Dialog-contract-parity lib/src/components/bc_dialog.dart
BcDrawer showModalBottomSheet-contract-parity lib/src/components/bc_drawer.dart
BcDropdown PopupMenuButton-contract-parity lib/src/components/bc_dropdown.dart
BcForm Form-GlobalKey-contract-parity lib/src/components/bc_form.dart
BcInput TextField-onChanged-contract-parity lib/src/components/bc_input.dart
BcList ListView.builder-contract-parity lib/src/components/bc_list.dart
BcMultiSelect FilterChip-list-contract-parity lib/src/components/bc_multi_select.dart
BcNumberField TextFormField-number-contract-parity lib/src/components/bc_number_field.dart
BcPopover PopoverRoute-contract-parity lib/src/components/bc_popover.dart
BcSegmented SegmentedButton-contract-parity lib/src/components/bc_segmented.dart
BcSelect DropdownMenu-contract-parity lib/src/components/bc_select.dart
BcSplitter ResizableSplitView-contract-parity lib/src/components/bc_splitter.dart
BcTabs TabBar-TabBarView-contract-parity lib/src/components/bc_tabs.dart
BcTimeField TextFormField-time-contract-parity lib/src/components/bc_time_field.dart
BcToggle Switch-onChanged-contract-parity lib/src/components/bc_toggle.dart
BcTooltip Tooltip-contract-parity lib/src/components/bc_tooltip.dart

P1 — Generated Stubs (8) — NEED IMPLEMENTATION

These Dart files were scaffolded by generate-flutter-stubs.mjs. The build() method returns a placeholder SizedBox with a TODO citing the recommended Flutter primitive. Implement each per its flutter hint.

Component Flutter Hint Stub File
BcDisclosure ExpansionTile-contract-parity lib/src/components/bc_disclosure.dart
BcFieldDuration TextFormField-duration-contract-parity lib/src/components/bc_field_duration.dart
BcFieldDynLink Row-dropdown-autocomplete-parity lib/src/components/bc_field_dyn_link.dart
BcFieldMorph Row-dropdown-textfield-parity lib/src/components/bc_field_morph.dart
BcFieldTableSelect DataTable-selectable-parity lib/src/components/bc_field_table_select.dart
BcLookupModal Dialog-DataTable-contract-parity lib/src/components/bc_lookup_modal.dart
BcPortal Overlay-portal-contract-parity lib/src/components/bc_portal.dart
BcViewGantt CustomPainter (ports SVG primitives to Canvas) lib/src/components/bc_view_gantt.dart

Contracts WITHOUT Flutter Hints (98) — NEED HINTS + STUBS + IMPLEMENTATION

P0 Contracts (need flutter hint)

ERP-critical components from the P0 tier that lack a flutter: hint. These should be prioritized for hint authoring since they are foundational to the ERP UI.

Component Tier Contract Path
BcBackdrop P0 src/components/feedback/backdrop/BcBackdrop.contract.ts
BcBox P0 src/components/primitives/box/BcBox.contract.ts
BcCascader P0 src/components/forms/cascader/BcCascader.contract.ts
BcDescriptions P0 src/components/data-display/descriptions/BcDescriptions.contract.ts
BcEmpty P0 src/components/feedback/empty/BcEmpty.contract.ts
BcLoadingOverlay P0 src/components/feedback/loading-overlay/BcLoadingOverlay.contract.ts
BcOtp P0 src/components/forms/otp/BcOtp.contract.ts
BcResult P0 src/components/feedback/result/BcResult.contract.ts
BcSlot P0 src/components/primitives/slot/BcSlot.contract.ts
BcStack P0 src/components/layout/stack/BcStack.contract.ts
BcStatistic P0 src/components/data-display/statistic/BcStatistic.contract.ts
BcSteps P0 src/components/navigation/steps/BcSteps.contract.ts
BcToastQueue P0 src/components/overlays/toast-queue/BcToastQueue.contract.ts
BcTransfer P0 src/components/forms/transfer/BcTransfer.contract.ts
BcTreeSelect P0 src/components/forms/treeselect/BcTreeSelect.contract.ts
BcVisuallyHidden P0 src/components/primitives/visually-hidden/BcVisuallyHidden.contract.ts
BcXStack P0 src/components/primitives/xstack/BcXStack.contract.ts
BcYStack P0 src/components/primitives/ystack/BcYStack.contract.ts

P1 Contracts (need flutter hint)

High-value components from the P1 tier that lack a flutter: hint.

Component Tier Contract Path
BcActionsheet P1 src/components/overlays/actionsheet/BcActionsheet.contract.ts
BcActivity P1 src/components/social/activity/BcActivity.contract.ts
BcAffix P1 src/components/navigation/affix/BcAffix.contract.ts
BcAnchor P1 src/components/navigation/anchor/BcAnchor.contract.ts
BcAspectRatio P1 src/components/primitives/aspectratio/BcAspectRatio.contract.ts
BcBackTop P1 src/components/navigation/backtop/BcBackTop.contract.ts
BcBarcode P1 src/components/forms/barcode/BcBarcode.contract.ts
BcBreadcrumb P1 src/components/navigation/breadcrumb/BcBreadcrumb.contract.ts
BcCarousel P1 src/components/data-display/carousel/BcCarousel.contract.ts
BcChatter P1 src/components/social/chatter/BcChatter.contract.ts
BcCode P1 src/components/forms/code/BcCode.contract.ts
BcColorPicker P1 src/components/forms/colorpicker/BcColorPicker.contract.ts
BcDropZone P1 src/components/forms/dropzone/BcDropZone.contract.ts
BcFile P1 src/components/forms/file/BcFile.contract.ts
BcFlex P1 src/components/layout/flex/BcFlex.contract.ts
BcGeo P1 src/components/forms/geo/BcGeo.contract.ts
BcHoverCard P1 src/components/overlays/hovercard/BcHoverCard.contract.ts
BcInplace P1 src/components/data-display/inplace/BcInplace.contract.ts
BcJson P1 src/components/forms/json/BcJson.contract.ts
BcMegaMenu P1 src/components/navigation/megamenu/BcMegaMenu.contract.ts
BcMentions P1 src/components/forms/mentions/BcMentions.contract.ts
BcMenubar P1 src/components/navigation/menubar/BcMenubar.contract.ts
BcNavigationMenu P1 src/components/navigation/navigationmenu/BcNavigationMenu.contract.ts
BcNotification P1 src/components/feedback/notification/BcNotification.contract.ts
BcOrgChart P1 src/components/data-display/orgchart/BcOrgChart.contract.ts
BcPagination P1 src/components/navigation/pagination/BcPagination.contract.ts
BcPrompt P1 src/components/overlays/prompt/BcPrompt.contract.ts
BcRangeSlider P1 src/components/forms/rangeslider/BcRangeSlider.contract.ts
BcRate P1 src/components/forms/rate/BcRate.contract.ts
BcRichText P1 src/components/forms/richtext/BcRichText.contract.ts
BcSignature P1 src/components/forms/signature/BcSignature.contract.ts
BcSlider P1 src/components/forms/slider/BcSlider.contract.ts
BcSparkline P1 src/components/charts/sparkline/BcSparkline.contract.ts
BcTagGroup P1 src/components/data-display/taggroup/BcTagGroup.contract.ts
BcTagsInput P1 src/components/forms/tagsinput/BcTagsInput.contract.ts
BcTimelineSocial P1 src/components/social/timeline/BcTimelineSocial.contract.ts
BcToggleGroup P1 src/components/forms/togglegroup/BcToggleGroup.contract.ts
BcTour P1 src/components/feedback/tour/BcTour.contract.ts
BcViewerAudio P1 src/components/media/viewer-audio/BcViewerAudio.contract.ts
BcViewerDocument P1 src/components/media/viewer-document/BcViewerDocument.contract.ts
BcViewerImage P1 src/components/media/viewer-image/BcViewerImage.contract.ts
BcViewerInstagram P1 src/components/media/viewer-instagram/BcViewerInstagram.contract.ts
BcViewerPdf P1 src/components/media/viewer-pdf/BcViewerPdf.contract.ts
BcViewerTiktok P1 src/components/media/viewer-tiktok/BcViewerTiktok.contract.ts
BcViewerVideo P1 src/components/media/viewer-video/BcViewerVideo.contract.ts
BcViewerYoutube P1 src/components/media/viewer-youtube/BcViewerYoutube.contract.ts
BcWizard P1 src/components/overlays/wizard/BcWizard.contract.ts

P2 Contracts (need flutter hint)

Polish-tier components that lack a flutter: hint.

Component Tier Contract Path
BcCenter P2 src/components/primitives/center/BcCenter.contract.ts
BcCircle P2 src/components/primitives/circle/BcCircle.contract.ts
BcColorArea P2 src/components/forms/color-area/BcColorArea.contract.ts
BcColorSlider P2 src/components/forms/color-slider/BcColorSlider.contract.ts
BcColorSwatch P2 src/components/forms/color-swatch/BcColorSwatch.contract.ts
BcColorWheel P2 src/components/forms/color-wheel/BcColorWheel.contract.ts
BcDock P2 src/components/navigation/dock/BcDock.contract.ts
BcExport P2 src/components/print/export/BcExport.contract.ts
BcFavorites P2 src/components/navigation/favorites/BcFavorites.contract.ts
BcGalleria P2 src/components/media/galleria/BcGalleria.contract.ts
BcImage P2 src/components/data-display/image/BcImage.contract.ts
BcKbd P2 src/components/primitives/kbd/BcKbd.contract.ts
BcKnob P2 src/components/forms/knob/BcKnob.contract.ts
BcMeterGroup P2 src/components/feedback/meter-group/BcMeterGroup.contract.ts
BcPanelMenu P2 src/components/navigation/panel-menu/BcPanelMenu.contract.ts
BcPrint P2 src/components/print/print/BcPrint.contract.ts
BcQRCode P2 src/components/data-display/qrcode/BcQRCode.contract.ts
BcReportLink P2 src/components/print/report-link/BcReportLink.contract.ts
BcSearch P2 src/components/navigation/search/BcSearch.contract.ts
BcSidebar P2 src/components/layout/sidebar/BcSidebar.contract.ts
BcSlideMenu P2 src/components/navigation/slide-menu/BcSlideMenu.contract.ts
BcSpeedDial P2 src/components/overlays/speeddial/BcSpeedDial.contract.ts
BcSquare P2 src/components/primitives/square/BcSquare.contract.ts
BcTieredMenu P2 src/components/navigation/tiered-menu/BcTieredMenu.contract.ts
BcViewActivity P2 src/components/views/activity/BcViewActivity.contract.ts
BcViewEditor P2 src/components/views/editor/BcViewEditor.contract.ts
BcViewMap P2 src/components/views/map/BcViewMap.contract.ts
BcViewReport P2 src/components/views/report/BcViewReport.contract.ts
BcVirtualScroller P2 src/components/views/virtual-scroller/BcVirtualScroller.contract.ts
BcWatermark P2 src/components/data-display/watermark/BcWatermark.contract.ts

Special / Un-tiered Contracts (need flutter hint)

Components not assigned to P0/P1/P2 in docs/components-progress.md. These include the unified BcChart (own "Charts" category), BcKanbanBoard (enterprise data view present in the Stencil parity matrix but absent from the tier tables), and the adapt-poc BcPopover Phase-0 proof-of-concept duplicate (the production BcPopover lives at overlays/popover/ and already has a flutter hint + hand-written Dart widget).

Component Tier Contract Path
BcChart Special src/components/charts/chart/BcChart.contract.ts
BcKanbanBoard Special src/components/data/kanban-board/BcKanbanBoard.contract.ts
BcPopover Unknown src/components/adapt-poc/popover/BcPopover.contract.ts Phase 0 PoC duplicate (production BcPopover is at overlays/popover/)

Notes & Caveats

  • Tier source: P0/P1/P2 assignments are read from docs/components-progress.md (P0 — ERP-Critical, P1 — High Value, P2 — Polish tables). BcChart is tracked in a separate "Charts" section; BcKanbanBoard appears in docs/stencil-parity-matrix.md and docs/codebase.md but not in the tier tables, so it is listed under "Special".
  • Duplicate BcPopover: the adapt-poc/popover/BcPopover.contract.ts file is a Phase 0 proof-of-concept with a minimal prop surface and no flutter hint. The production overlays/popover/BcPopover.contract.ts has the flutter hint PopoverRoute-contract-parity and a hand-written Dart widget. The PoC contract is retained for the resolver-spike test fixtures and should not be ported independently.
  • Stub generator: packages/ui/scripts/generate-flutter-stubs.mjs defines a WIDGET_MAP of exactly 32 flutter-hinted components. It skips contracts without a flutter hint and refuses to overwrite hand-written Dart files (detected by the absence of the Auto-generated by generate-flutter-stubs.mjs header).
  • BcAdapt: marked "NEW Tier 3" in the progress doc (a responsive contract primitive). It is grouped under P1 here because the P1 Feedback/Overlays table lists it; its tier status is provisional.
  • BcChart Flutter contract (ADR-015): The BcChart contract is ported to Dart at lib/src/core/chart/ (not via the stub generator). The port mirrors packages/ui/src/contracts/chart-option/ (the extracted TS contract from ADR-015 F1). The Flutter BcChart widget (lib/src/components/bc_chart.dart) uses flutter_echarts to render all 26 chart types via the shared buildChartOption() factory. See doc/chart-migration.md for the migration guide and docs/adr/015-flutter-echarts-chart-strategy.md for the full ADR.

Cross-Tier Infrastructure Parity (ADR-013)

ADR-013 completes the cross-tier infrastructure (AppProvider, Hooks, Animation, Adapt) so components are "truly cross-platform". The Flutter parity surface lives in lib/src/core/ (not via the stub generator — these are infrastructure primitives, not widgets) and is exported from the package barrel lib/bc_ui_flutter.dart.

AppProvider consumption surface (Phase 1 + 5b)

TS symbol Flutter counterpart File
AppConfigSnapshot AppConfigSnapshot lib/src/core/app_config_snapshot.dart
AppConfigStore AppConfigStore lib/src/core/app_config_store.dart
BcAppContext (Mitosis context) BcAppConfig (InheritedWidget) lib/src/core/bc_app_config.dart
useAppContext() / useAppConfigStore() BcAppConfig.of(context) / BcAppConfig.of(context).store lib/src/core/bc_app_config.dart

Hooks P1 parity (Phase 5b)

TS hook Flutter counterpart File Parity
usePrevious / PreviousValue<T> PreviousValue<T> / usePrevious() lib/src/core/hooks/use_previous.dart Full (pure Dart)
createInterval / IntervalController BcIntervalController / createInterval(...) lib/src/core/hooks/use_interval.dart Full (Timer.periodic)
createTimeout / TimeoutController BcTimeoutController / createTimeout(...) lib/src/core/hooks/use_timeout.dart Full (Timer)
createScrollLock / ScrollLock BcScrollLock / createScrollLock() lib/src/core/hooks/use_scroll_lock.dart Adapted (ValueNotifier<bool> → host swaps ScrollPhysics; no document.body)
createLocalStorage / LocalStorageStore<T> BcLocalStorageStore<T> / createLocalStorage(...) lib/src/core/hooks/use_local_storage.dart Adapted (injectable BcStorageBackend; no browser localStorage)
useIntersection — — Web-only: Flutter uses Visibility widget (no DOM observer).
useClickOutside — — Web-only: Flutter uses TapRegion/GestureDetector.
useKeyboard — — Web-only: Flutter uses Focus/KeyboardListener/KeyEvent.

Animation runtime (Phase 5b)

TS symbol Flutter counterpart File
AnimationKind BcAnimationKind (enum) lib/src/core/animation/animation.dart
AnimationEasing BcAnimationEasing (enum) lib/src/core/animation/animation.dart
AnimationProps / ANIMATION_DEFAULT BcAnimationProps / ANIMATION_DEFAULT lib/src/core/animation/animation.dart
resolveAnimation() / ResolvedAnimation resolveAnimation() / BcResolvedAnimation lib/src/core/animation/animation.dart
getAnimationClasses() getAnimationCurves() lib/src/core/animation/animation.dart
prefersReducedMotion() host passes MediaQuery.disableAnimationsOf(context) via BcResolveAnimationOptions.reducedMotion —

Adapt runtime (Phase 5b)

TS symbol Flutter counterpart File
AdaptBreakpoint / AdaptPlatform / AdaptTarget / AdaptCondition BcAdaptBreakpoint / BcAdaptPlatform / BcAdaptTarget / BcAdaptCondition lib/src/core/adapt/adapt.dart
AdaptProps / AdaptContext / ResolvedAdapt BcAdaptProps / BcAdaptContext / BcResolvedAdapt lib/src/core/adapt/adapt.dart
resolveAdapt() resolveAdapt() / BcAdaptResolver lib/src/core/adapt/adapt.dart
BC_BREAKPOINTS bcBreakpointQueries lib/src/core/bc_breakpoints.dart
breakpoint match via window.matchMedia host derives breakpointMatcher from MediaQuery.size —
platform via platform: tag host derives ctx.platform from Platform.isIOS/isAndroid —

See docs/adr/013-cross-tier-infrastructure-completion.md (Phase 5b completion notes + cross-tier parity table) for the authoritative symbol-by-symbol mapping and the web-only justifications.