BCPlatforms Component Library (@bcplatforms/bcui)

A TypeScript/React component library that wraps and extends Elastic UI (EUI). It is published under the @bcplatforms npm scope and compiled from /src to /lib via tsc.

Note: There is a parallel development thread on the cohort_dev branch. That branch contains cohort-specific fixes and features that may not yet be merged into dev or master. See the changelog for which versions were built from which branch.

Changelog

4.0.10

• Package renamed back to @bcplatforms/bcui — this branch (BI-17207-cohort_dev) is now the main development thread, superseding the separate cohort_dev branch
• Dependency cleanup: moved build tools (webpack, sass, sass-loader, style-loader, npm-check, npm-check-updates) from dependencies to devDependencies
• Removed @types/[email protected] — react-router-dom v6 ships its own types; v5 types caused conflicts
• Fixed @types/react version to ^18.2.0 (was pinned to 18.0.9, behind react: ^18.2.0)
• Removed duplicate entries from dependencies: axios-mock-adapter, @types/d3, @types/regression (all already in devDependencies)
• Added branch-status.md — analysis of 27 unmerged remote branches with merge recommendations and Jira links
• Added TODO — Library Updates section to README based on full TypeScript dependency audit
• Added branch-status.pdf and wrap-tables.lua for pandoc PDF generation with column wrapping

4.0.9

• Fix: clean rebuild to remove stale cohort_dev lib/ files (BCWaterfallChart, BCParetoChart, BCTimeSeriesChart) that caused echarts not found error in consumers — 4.0.8 was packed with a contaminated lib directory
• Fix: DatasetUtils.transformDatasetDataToEdit — FILE branch now correctly returns the filename string instead of the original file object
• Tests: added test suites for validation.ts, utils.ts (BCFormRenderer), bc-util.ts, and DatasetUtils.ts (115 new tests, 198 total)

4.0.8

• Makefile: added help as default target, port availability check in start (cancels if port busy), enhanced stop to kill all stray Storybook processes (by PID, port, and process name)
• Makefile: added docs target for generating PDF documentation via pandoc
• BCFormRenderer (BI-17207): fixed autofill keepValue flicker when condition is self-referential
• Storybook: added CVLP pre-screening stories
• Documentation: added PDF versions of README and FORM_JSON_SCHEMA, added open-source form library comparison doc
• cohort_dev tarball: bcplatforms-cohort-dev-bcui-4.0.8.tgz — built from BI-17207-cohort_dev branch (dev merged in, test failures fixed)
• @bcplatforms/[email protected] is a drop-in replacement for the deprecated @bcplatforms/[email protected] — use this version if you were on 4.1.8

4.0.7

• Added Makefile for Storybook lifecycle management (start, stop, restart, status, open)
• Updated README: Storybook instructions, test suite table, BCFormRenderer source map, cohort_dev branch note
• Added BCFormRenderer stories with Storybook controls: pre-screening BNT113-01 form (PreScreeningWithTimestamp), autofill undefined-condition story (PreScreeningForm), merged autofill date stories into single AutofillDate with controls

4.0.6

• Fixed TypeScript compilation errors introduced by updated dependencies (TypeScript 5.x stricter checks):
  • QueryGroupHeader.tsx: replaced deprecated React.JSX.Element with React.ReactElement
  • BCUpload.tsx and BCUnsavedChangesContext.tsx: added required type argument to PropsWithChildren
  • BCFormUtils.ts: removed unreachable ?? fallback after nullish-safe comparison
  • BCTable.tsx: removed dead-code || fallback on always-truthy object literal
• Excluded src/stories from TypeScript compilation (stories are not part of the built library)
• Updated .npmignore to exclude dev directories (.claude/, .idea/, .vscode/, .eslintrc*)

4.0.5

• Fix for form renderer expression evaluation (self-reference + null issue in comparison, BI-17207)
• Built from cohort_dev branch

4.0.4

• BI-17207: Added keepValue option to autofill and auto-detection of self-referential conditions
• BI-17207: Fixed infinite re-render loop in autofill for non-date field types
• BI-17207: Updated dependencies and lock files

Installation

yarn add @bcplatforms/bcui
# or
npm i @bcplatforms/bcui

Prerequisites

• Node 14+
• Add an .npmrc file at the root (next to package.json) with:

//registry.npmjs.org/:_authToken=AUTH_TOKEN

Ask Santhosh, Monis, or another npmjs admin for the AUTH_TOKEN.

• Read-only access: read token
• Publishing: publish token

Development

Commands

# Start Storybook dev server (port 6006)
npm run storybook

# Build the library (compiles TypeScript → /lib)
npm run build

# Run all Jest tests
npm test

# Run a single test file
npm test -- src/hooks/__tests__/rolefilter.test.ts

# Lint
npm run lint

# Format
npm run prettier

Note: Storybook requires NODE_OPTIONS=--openssl-legacy-provider on newer Node versions due to webpack 4 compatibility. The npm run storybook script sets this automatically.

Tests

Tests use Jest with ts-jest. Run them with:

npm test                                                        # all suites
npm test -- src/hooks/__tests__/rolefilter.test.ts             # single file

Current test suites (75 tests total):

| Test file | What it covers | |---|---| | src/hooks/__tests__/rolefilter.test.ts | Role-based filtering hook | | src/hooks/__tests__/grouplink.test.ts | Group link hook | | src/hooks/__tests__/treelink.tests.ts | Tree link hook | | src/hooks/__tests__/toplinks.tests.ts | Top-links hook | | src/components/BCFormRenderer/__tests__/isExpressionValid.test.ts | Expression validation in BCFormRenderer | | src/components/BCFormRenderer/__tests__/autofillDate.test.ts | Autofill engine — self-referential conditions, keepValue, now() evaluation |

Most component validation is done through Storybook rather than unit tests. The Jest suite focuses on hooks and the form expression/autofill engine.

Storybook

Storybook is the primary tool for developing and manually testing components. It runs at http://localhost:6006.

A Makefile is included for convenience:

make start     # Start Storybook in the background
make stop      # Stop the background Storybook process
make restart   # Stop and start
make status    # Show whether Storybook is running and its PID
make open      # Open http://localhost:6006 in the default browser

Stories live in src/stories/ and are organised by component:

| Story file | What it covers | |---|---| | form-renderer/BCFormRenderer.stories.tsx | BCFormRenderer — all field types, autofill, validation, lookups, cascading dropdowns | | form-renderer/BCFormGenerator.stories.tsx | BCFormGenerator — schema-driven form generation | | async-grid/BCAysncGrid.stories.tsx | BCAsyncGrid — server-side paginated data grid | | bctable/BCTable.stories.tsx | BCTable — client-side table | | BCUpload.stories.tsx | BCUpload — file upload | | BCDraggable.stories.tsx | BCDraggable — drag-and-drop | | BCStyledTabs.stories.tsx | BCStyledTabs — tabbed layout | | SideNav.stories.tsx | Side navigation |

BCFormRenderer

BCFormRenderer is the main dynamic form engine. It takes a JSON configuration object (formConfig) and renders a fully interactive form with validation, conditional visibility, autofill, and lookup support.

Quick example

import { BCFormRenderer } from '@bcplatforms/bcui'

<BCFormRenderer
  formConfig={myFormConfig}
  formData={savedData}
  onSubmit={(data) => saveToServer(data)}
  onSave={(data) => autoSave(data)}
  uploadUrl="/api/upload"
  downloadUrl="/api/download"
  validationUrl="/api/validate"
  requestObject={axiosInstance}
  isSubmitting={false}
/>

Key source files

| File | Purpose | |---|---| | src/components/BCFormRenderer/FormRenderer.tsx | Root component — wires config, data, and callbacks | | src/components/BCFormRenderer/FormRendererProvider.tsx | Context provider — holds form state (Formik) | | src/components/BCFormRenderer/form.types.ts | All TypeScript types: FormConfig, FormElement, FormElementOptions, etc. | | src/components/BCFormRenderer/useAutofillValues.ts | Autofill engine — evaluates conditionExpression / valueExpression | | src/components/BCFormRenderer/useDynamicContent.ts | Dynamic lookup fetching (cascading dropdowns) | | src/components/BCFormRenderer/useFormValidation.ts | Cross-field expression validation | | src/components/BCFormRenderer/validation.ts | Yup schema builder | | src/components/BCFormRenderer/utils.ts | Expression evaluation helpers | | src/components/BCFormRenderer/FORM_JSON_SCHEMA.md | Full form JSON schema reference — all field types, options, autofill, dependency, validation |

Form JSON schema

Full schema documentation is in src/components/BCFormRenderer/FORM_JSON_SCHEMA.md.

It covers:

• Top-level FormConfig structure and settings
• All FormElement types (TEXT, DATE, DATETIME, INTEGER, FLOAT, CHOICE_DROPDOWN, MULTICHOICE, FILE, HEADING, PARAGRAPH, DYNAMIC_FIELD, …)
• options — required, dependency, autofill, expressionValidations, dynamicContent, isReadOnly, validation, and more

Alternatives and related libraries

For a comparison of open source form libraries that support dynamic schema-driven forms and visual layout editors, see FORM_LIBRARIES_COMPARISON.md.

TODO — Library Updates

Audit done 2026-04-22. Prioritized list of recommended dependency updates.

Must do

| Library | Issue | Action | Effort | |---------|-------|--------|--------| | @elastic/eui pinned at 94.1.0 | 20+ versions behind (latest 114.2.0); 272 imports affected | Review and merge origin/upgrade-99 (v99–100), then continue toward v114 | HIGH | | [email protected] | Unmaintained since 2020 | Replace with @dnd-kit (already installed); BCBasicTable/control/column_selector.tsx already shows the pattern | MEDIUM | | [email protected] | Abandoned | Migrate BCViewConfiguration.tsx to @dnd-kit, remove package | MEDIUM | | [email protected] | Beta in production; stable 3.0.0 released | Bump to ^3.0.0 | LOW |

Should fix

| Item | Issue | Action | Effort | |------|-------|--------|--------| | BCFormRenderer/utils.ts | Uses deprecated validateYupSchema() and yupToFormErrors() (Formik v2.2+) | Replace with direct .validate() calls | LOW | | BCFormRenderer/validation.ts, BCFormBuilder/BCFormUtils.ts | .shape() pattern discouraged in Yup v1 | Convert to yup.object({ field: yup.string() }) syntax | LOW | | tsconfig.json | target: es5 (2009); React 18 requires ES2015 minimum | Change to "es2015" or "es2017" | LOW | | Storybook script | NODE_OPTIONS=--openssl-legacy-provider is a workaround, not a fix | Upgrade Storybook build pipeline and remove the flag | MEDIUM |

Nice to have

| Library | Issue | Action | Effort | |---------|-------|--------|--------| | [email protected] | Latest is v3.0.0; BCPageTitle also wrongly nests <HelmetProvider> inside the component | Upgrade + move HelmetProvider to app root | LOW | | crossfilter2 + [email protected] | Legacy DC.js charts alongside modern echarts V2 path; hand-rolled src/dc.d.ts | Check with team if DC charts still used — remove if not | HIGH if migrating | | [email protected] | v6 available (breaking changes) | Stay on v5.x for now; plan v6 migration next cycle | MEDIUM |

Suggested order

1. Phase 1 (~3 days): react-vtree beta → stable, fix Formik/Yup deprecated APIs, tsconfig ES5 → ES2015
2. Phase 2 (~1 week): Replace react-beautiful-dnd + react-sortable-hoc with @dnd-kit
3. Phase 3 (~2–3 weeks): Merge origin/upgrade-99, continue EUI upgrade toward v114
4. Phase 4 (next cycle): Assess dc.js/crossfilter2 removal, echarts v6, react-helmet-async

Publishing

What goes into the package

The npm package contains only what consuming applications need:

| Included | Purpose | |---|---| | lib/ | Compiled JavaScript + TypeScript declaration files | | src/assets/styles/*.scss | Component-level stylesheets | | themes/bcplatforms/ | BCPlatforms EUI theme overrides | | package.json | Package metadata | | README.md | Always included by npm regardless of .npmignore |

Dev-only files excluded via .npmignore: source TypeScript (src/** except .scss), stories, tests, CI config (.gitlab-ci.yml), build config (.babelrc.json, tsconfig.json), scripts (skaffold*.sh, Dockerfile), the Makefile, .storybook.pid, dist/, coverage/, node_modules/, and all *.tgz files.

Building a release tarball

Versioned tarballs for local/internal use are stored in dist/. The version is read automatically from package.json.

# 1. Bump the patch version in package.json (no git commit/tag)
npm version patch --no-git-tag-version

# 2. Build, test and pack in one step
make tarball

This runs npm test, npm run build, and places the tarball at dist/bcplatforms-bcui-<VERSION>.tgz.

Reference a tarball from dist/ in a consumer's package.json:

"@bcplatforms/bcui": "file:./path/to/dist/bcplatforms-bcui-4.0.7.tgz"

Publishing to npmjs

make publish

This runs npm test, npm run build, and npm publish in sequence.

Requires a publish token in .npmrc. Ask Santhosh or Monis for access.