npm.io
4.0.11 • Published yesterday

@bcplatforms/bcui

Licence
MIT
Version
4.0.11
Deps
27
Size
2.8 MB
Vulns
3
Weekly
0
SummaryDependencyVersions

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/react-router-dom@5.3.0 — 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/bcui-cohort@4.0.8 is a drop-in replacement for the deprecated @bcplatforms/bcui@4.1.8 — 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
react-beautiful-dnd@13.1.1 Unmaintained since 2020 Replace with @dnd-kit (already installed); BCBasicTable/control/column_selector.tsx already shows the pattern MEDIUM
react-sortable-hoc@2.0.0 Abandoned Migrate BCViewConfiguration.tsx to @dnd-kit, remove package MEDIUM
react-vtree@3.0.0-beta.0 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
react-helmet-async@1.3.0 Latest is v3.0.0; BCPageTitle also wrongly nests <HelmetProvider> inside the component Upgrade + move HelmetProvider to app root LOW
crossfilter2 + dc@4.2.7 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
echarts@5.6.0 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.