@proounce/shared-common 0.0.0-stage → 0.1.0

package/docs/COMPONENT_AUDIT.md

@@ -0,0 +1,158 @@
+# Shared component audit
+
+This audit compares `@proounce/shared-common` with the exports in
+`prj241001_fe_shared-base-components`. The migration boundary is reusable,
+presentation-focused components with no API, Redux, router, authentication, or
+application-service dependency.
+
+## Included component families
+
+| Family | Main exports |
+| --- | --- |
+| Accessibility | `SkipLink`, `LiveRegion`, `VisuallyHidden` |
+| Actions | `ActionIcon`, `ActionIconButton`, `ActionsContainer` |
+| Buttons | `SharedButton`, `SharedIconButton` |
+| Text inputs | `SharedTextField`, `SearchInput`, `TextFieldWithIcon`, `CurrencyInput` |
+| Choice inputs | `SelectInput`, `AdvancedDropDownList`, `DropDownList`, `MultiSelectDropDownList` |
+| Date inputs | `DateInput`, `DateTimeInput` |
+| File inputs | `FileInput`, `CustomDropZone` |
+| Tables | `DataTable`, legacy common/search/pagination/selection wrappers, `TableWrapper`, bordered/sticky/highlighted/info cells, sortable labels, styled rows and skeletons |
+| Forms | Labels, mandatory indicator, checkbox, textarea, read-only values and single/multi option selectors |
+| Feedback | Alerts, spinner, status indicator, empty/error states and information tooltip |
+| Navigation | Tabs, tab panels, back button, breadcrumbs, main selector, scroll indicator, toggles and switches |
+| Layout | `Page`, `PanelWrapper` |
+| Styled surfaces | Theme-aware card, KPI card, accordion, tabs and read-only text field |
+| Dialogs | `Modal`, `ConfirmDialog` |
+| Status dialogs | Accessible processing, success, error and warning dialogs |
+| Display | Date/time, signed currency/percentage, direction indicators, documentation/help cards, summary cards and operations details |
+| Standalone display | Expandable comments, formula/name popovers and status blinkers |
+| Error states | Access feedback and router-independent 401/403/404/500 pages |
+| Generic request primitives | Header/body text, content wrapper, percentage and labeled text inputs |
+| Charts | Raw `FusionChart`, `CommonChart`, selectable chart types, accessible data fallback, bar/column/doughnut/line/area/pie presets and legacy generic/default aliases |
+| AG Grid | Optional `CustomGridTable`/`AgGridTable`, accessible info/formula header, wrapper and public AG Grid types |
+| Icons | Curated MUI action registry and curated Lucide action set |
+
+The complete set of 270 unique legacy action purposes is represented.
+
+## Final public-export reconciliation
+
+The final audit parsed every active `export { default as Name }` declaration in
+the legacy public barrel and compared it with the root, FusionCharts and AG Grid
+entry points in this package:
+
+| Result | Count |
+| --- | ---: |
+| Unique legacy named default re-exports | 297 |
+| Exact public-name matches in this package | 185 |
+| Intentionally not copied | 112 |
+
+The 112 unmatched names are not overlooked standalone primitives. They are
+application/auth/reporting/review workflows; Redux, API and routing hooks;
+heavy editors, viewers, calendars and geography bundles; obsolete alternate
+table/grid implementations already covered by the typed common-table or AG Grid
+entries; or raw third-party pass-throughs such as date adapters, `dayjs`,
+Mammoth and JSZip. Named exports from raw MUI and Redux libraries were also
+reviewed but are deliberately not duplicated by this package.
+
+The final pass added the reusable gaps that remained: choice selectors,
+`CustomDropZone`, `MainSelector`, `TeslaStyleScrollIndicator`, documentation
+cards, KPI cards, `SelectWithTable`, request-form helpers, legacy currency and
+styled-cell aliases, label/help icons, summary cards, and `OperationsInfo`.
+
+## Legacy manifest review
+
+The legacy manifest was reviewed dependency by dependency. The new package
+keeps only dependencies required by API-free components:
+
+| Legacy dependency area | Decision |
+| --- | --- |
+| React 18.2+, MUI 5, Emotion 11, MUI icons 5 | Required peers aligned with the shared-base package and consuming applications |
+| MUI date pickers 5 and Day.js 1.11 | Required peers because date inputs are in the root entry |
+| FusionCharts | Optional peer isolated to `charts/fusion` |
+| AG Grid Community 34 | Optional peer isolated to `grids/ag-grid` |
+| Lucide 0.561 | Optional peer isolated to `icons/lucide` |
+| Redux, router and single-spa | Excluded; application architecture, not presentation primitives |
+| MUI Lab, legacy `@mui/styles`, MUI Data Grid | Excluded; no retained component requires them |
+| Editors, viewers, HLS, calendar and drag/drop | Excluded from base; see optional-package guidance below |
+| Currency/number-format wrappers | Replaced with typed MUI/`Intl` primitives where equivalent |
+
+Raw MUI controls, date adapters, `dayjs`, and utility libraries are not
+re-exported. Consumers import them from their owning packages, avoiding a
+second public API surface that this package cannot safely version.
+
+## Intentionally excluded
+
+These are not missing base primitives; they are outside this package boundary.
+
+| Legacy area | Reason |
+| --- | --- |
+| User app bar, authorization wrappers and permission screens | Application/authentication behavior |
+| Redux store, selectors and data-fetching hooks | State and API coupling |
+| Reporting, reviews, spend-plan and BOB screens | Domain workflows rather than reusable primitives |
+| Notification center and application menus | Application data, routing and business rules |
+| Request actions and status rails | Workflow-specific state transitions |
+| Audit, organization and LOV workflow modals | Shared-utility and domain-model coupling |
+| `useTimeZone` and other data hooks | Direct service/API calls |
+| Ticket creation and application-menu workflows | Application navigation, state and service behavior |
+
+## Separate optional packages recommended
+
+The following components are reusable in principle, but should not be placed in
+the base entry point because they have large runtimes, browser workers, licensing,
+or specialized security/update requirements:
+
+- CKEditor and SunEditor
+- PDF, Word, Excel and ZIP viewers
+- HLS video player
+- Calendar scheduler
+- Rich dropzone/dialog workflows
+- USA state and congressional map bundles (publish as a geography-specific chart subpath)
+
+If required, publish these as optional subpath entries or separate packages so
+ordinary consumers do not install and evaluate them.
+
+## Compatibility caveats
+
+- Legacy aliases are provided only where the behavior is genuinely equivalent.
+- `FileInput` replaces the basic file-selection use case. It is not falsely
+  exported as a drag-and-drop dialog.
+- `Modal` is not exported as `DraggableModal`; a draggable implementation must
+  also provide a non-drag interaction to satisfy WCAG 2.2 dragging guidance.
+- Domain-specific tables should compose `DataTable` instead of being copied into
+  the base package.
+
+## Accessibility status
+
+The primitives provide WCAG 2.2-oriented semantics and interaction foundations:
+
+- visible labels and linked error/help text;
+- readable `backupName` fallbacks when legacy callers omit label/name/id,
+  without exposing generated DOM IDs as accessible names;
+- keyboard-operable actions, tables, comboboxes, tabs and dialogs;
+- visible MUI focus indicators;
+- minimum 40px shared button targets;
+- dialog names, close paths and MUI focus management;
+- live-region, skip-link and visually-hidden helpers;
+- text equivalents for status, trend and error information;
+- automated axe-core checks for representative components.
+
+This does not certify a consuming application as WCAG conformant. Applications
+must still verify content, color contrast under their theme, zoom/reflow,
+heading order, focus order, validation behavior, chart alternatives, responsive
+layouts, and complete user journeys with keyboard and assistive technology.
+
+## React and package-quality review
+
+- Rendering remains pure; FusionCharts registration and licensing happen in
+  effects, and the optional entry is not evaluated by root imports.
+- State updates caused by user actions occur in event handlers. Chart type
+  selection no longer mirrors props through a synchronization effect.
+- List keys use domain identifiers wherever one exists. Table consumers should
+  provide `getRowKey`, and AG Grid consumers should provide `getRowId`, whenever
+  records can move or update.
+- Components receive data and callbacks through props and do not fetch data,
+  read Redux state, or navigate directly.
+- Memoization is reserved for the expensive AG Grid boundary rather than added
+  indiscriminately to every primitive.
+- The package publishes ESM, CommonJS, declarations and source maps with an
+  explicit exports map; optional runtimes remain behind subpath exports.

package/package.json

@@ -1,6 +1,126 @@
 {
   "name": "@proounce/shared-common",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "API-free shared React components for GC360 applications",
+  "author": "Proounce",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "docs",
+    "LICENSE"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": "./dist/index.cjs",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./icons/mui": {
+      "types": "./dist/icons/mui.d.ts",
+      "node": "./dist/icons/mui.cjs",
+      "import": "./dist/icons/mui.js",
+      "require": "./dist/icons/mui.cjs"
+    },
+    "./icons/lucide": {
+      "types": "./dist/icons/lucide.d.ts",
+      "node": "./dist/icons/lucide.cjs",
+      "import": "./dist/icons/lucide.js",
+      "require": "./dist/icons/lucide.cjs"
+    },
+    "./charts/fusion": {
+      "types": "./dist/charts/fusion.d.ts",
+      "node": "./dist/charts/fusion.cjs",
+      "import": "./dist/charts/fusion.js",
+      "require": "./dist/charts/fusion.cjs"
+    },
+    "./grids/ag-grid": {
+      "types": "./dist/grids/ag-grid.d.ts",
+      "node": "./dist/grids/ag-grid.cjs",
+      "import": "./dist/grids/ag-grid.js",
+      "require": "./dist/grids/ag-grid.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm test && npm run build",
+    "prepack": "npm run check"
+  },
+  "peerDependencies": {
+    "@emotion/react": "^11.11.4",
+    "@emotion/styled": "^11.11.5",
+    "@mui/icons-material": "^5.15.18",
+    "@mui/material": "^5.15.18",
+    "@mui/x-date-pickers": "^5.0.20",
+    "ag-grid-community": "^34.2.0",
+    "ag-grid-react": "^34.2.0",
+    "dayjs": "^1.11.7",
+    "fusioncharts": "^3.23.0",
+    "lucide-react": "^0.561.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-fusioncharts": "^4.1.0"
+  },
+  "peerDependenciesMeta": {
+    "fusioncharts": {
+      "optional": true
+    },
+    "lucide-react": {
+      "optional": true
+    },
+    "react-fusioncharts": {
+      "optional": true
+    },
+    "ag-grid-community": {
+      "optional": true
+    },
+    "ag-grid-react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@emotion/react": "^11.11.4",
+    "@emotion/styled": "^11.11.5",
+    "@mui/icons-material": "^5.15.18",
+    "@mui/material": "^5.15.18",
+    "@mui/x-date-pickers": "^5.0.20",
+    "ag-grid-community": "^34.2.0",
+    "ag-grid-react": "^34.2.0",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^15.0.7",
+    "@testing-library/user-event": "^14.6.9",
+    "@types/react": "^18.2.21",
+    "@types/react-dom": "^18.2.25",
+    "axe-core": "^4.14.0",
+    "dayjs": "^1.11.19",
+    "fusioncharts": "^3.23.0",
+    "jsdom": "^31.0.0",
+    "lucide-react": "^0.561.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-fusioncharts": "^4.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^5.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "overrides": {
+    "esbuild": "^0.28.2"
+  }
+}