@proounce/shared-common 0.1.0 → 0.1.1

package/README.md

@@ -1,17 +1,27 @@
 # @proounce/shared-common
 
-Reusable, API-free React components for GC360 front-end applications. The
-library extracts and modernizes presentation components from
-`prj241001_fe_shared-base-components` while removing application state, API,
-router, and shared-utility coupling.
+Public npm distribution of the 185 selected, API-free exports from
+`@gc360/shared-base-components`.
+
+The package root is a source-faithful port from legacy commit `83e0238b`.
+Component structure, underlying MUI/native controls, default properties,
+styles, padding, dimensions, colors, states, icons and event behavior are
+retained. The remaining 112 legacy exports are intentionally not published.
 
 ## Requirements
 
 - Node.js 20 or newer
-- React 18 (`^18.2.0`), matching the GC360 single-spa applications
-- Material UI 5 and Emotion 11
-- MUI X Date Pickers 5 and Day.js for date inputs
-- FusionCharts only when using the chart entry point
+- React and React DOM `^18.2.0`
+- Material UI 5, MUI Icons 5, Emotion 11 and MUI X Date Pickers 5
+- Day.js 1.11
+- The peer dependencies used by the selected component being imported
+
+Some faithful legacy components use `@gc360/shared-styleguide` or
+`@gc360/shared-utilities`. They are optional npm peers so installation of this
+public package does not fail when those packages are unavailable. Applications
+using the affected components must provide the same GC360 packages at runtime.
+FusionCharts, AG Grid and Lucide are likewise optional unless their components
+or subpath entry points are used.
 
 ## Installation
 
@@ -19,413 +29,94 @@ router, and shared-utility coupling.
 npm install @proounce/shared-common
 ```
 
-npm reports any peer dependencies that are not already installed by the host
-application.
-
-This is a public npm package and can be downloaded without membership in the
-`proounce` organization. It remains covered by the repository's proprietary
-license; public availability does not grant rights beyond that license.
+This package is publicly downloadable but remains proprietary. Public
+availability does not grant rights beyond [the license](LICENSE).
 
-## Component imports
+## Usage
 
-Import components and TypeScript types from the package root:
+Existing imports can be migrated without changing component names:
 
 ```tsx
 import {
   ActionIcon,
   AdvancedDropDownList,
-  DataTable,
-  SearchInput,
-  SharedButton,
-  type DataTableColumn,
-  type DropDownOption,
-} from "@proounce/shared-common";
-```
-
-The root entry point is safe to import in Node and server-rendered applications.
-
-## Buttons and actions
-
-`ActionIcon` and `ActionIconButton` support the action purposes carried over
-from the legacy shared-base package.
-
-```tsx
-import { ActionIcon, ActionIconButton } from "@proounce/shared-common";
-
-export function RowActions() {
-  return (
-    <>
-      <ActionIcon purpose="edit" title="Edit record" onClick={() => {}} />
-      <ActionIconButton
-        purpose="download"
-        title="Download report"
-        onClick={() => {}}
-      />
-    </>
-  );
-}
-```
-
-All 270 unique purposes from the legacy `action-icon-data` and
-`action-icon-button-data` files are represented in `ActionIconData`.
-
-## Dropdowns
-
-Dropdown options use an `id` for the submitted value and `value` for the
-visible label. Change events retain the legacy `{ target: { name, value } }`
-shape to simplify migration.
-
-```tsx
-import {
-  AdvancedDropDownList,
-  type DropDownOption,
+  CommonTable,
+  LightTooltip,
+  StyledTableCell,
 } from "@proounce/shared-common";
-
-const options: DropDownOption<number>[] = [
-  { id: 1, value: "First option" },
-  { id: 2, value: "Second option" },
-];
-
-export function Example() {
-  return (
-    <AdvancedDropDownList
-      id="selection"
-      label="Selection"
-      value={1}
-      options={options}
-      onChange={(event) => console.log(event.target.value)}
-    />
-  );
-}
-```
-
-Supported dropdown exports include:
-
-- `AdvancedDropDownList` and `MuiAdvancedDropDownList`
-- `StyledAdvanceDropDownList`
-- `GenericAdvanceDropDownList` and `GenericAdvancedSelect`
-- `DropDownList` and `DropDownWithMessage`
-- `MultiSelectDropDownList`
-- `GroupedMultiSelectDropDown` and `MuiGroupedMultiSelectDropDown`
-- `FloatingAdvanceDropDownList` and `FloatingMultiSelectDropDownList`
-- `DropDownListWithImage` for options with a visual identifier
-- `EmailSuggestionInput`, `EmailSuggestionMuiTextBox`, and
-  `EmailSuggestionTextBox` for free-form recipient chips
-
-## Tables
-
-`DataTable` provides stable client-side sorting, pagination, loading skeletons,
-custom cell rendering, row actions, and typed columns.
-
-```tsx
-import { DataTable, type DataTableColumn } from "@proounce/shared-common";
-
-interface Person {
-  id: number;
-  name: string;
-  status: string;
-}
-
-const columns: DataTableColumn<Person>[] = [
-  { field: "name", header: "Name" },
-  { field: "status", header: "Status", sortable: false },
-];
-
-export function PeopleTable({ rows }: { rows: Person[] }) {
-  return <DataTable rows={rows} columns={columns} getRowKey={(row) => row.id} />;
-}
-```
-
-Legacy columns using `title` instead of `header` are also accepted. Styled
-table cells, rows, and skeleton table bodies are exported separately. This
-includes `StyledTableCell`, `StyledBorderedTableCell`,
-`StyledLinesBorderedTableCell`, `StickyTableCell`, `StickyFooterTableCell`,
-`HighlightedTableCell`, `TableCellWithInfo`, `StyledTableSortLabel`, and their
-documented legacy aliases.
-
-Legacy common-table contracts are available as real typed wrappers rather than
-name-only aliases:
-
-- `CommonTable` and `CustomTable`
-- `CommonSearchTable`
-- `PaginationTable` for controlled/server pagination
-- `CommonSelectionTable`
-- `CommonSelectionValidateTable`
-- `CommonSelectionStickyTable` and `CustomStickyTable`
-- `GenericCustomTable` for the shared generic selection/action modes
-
-These wrappers accept the legacy `data`, `columns`, `title`, `sorting`,
-`render(row)`, `primaryColId`, `selected`, and `setSelected` properties while
-remaining API-free. New code can use `DataTable` directly.
-
-The former generic table's nested columns are flattened to accessible leaf
-headers. Its highly specialized column-configuration dialog and calculated
-business totals are not silently emulated; applications should compose those
-features through table actions and column renderers.
-
-## Styled surfaces
-
-Reusable styled surfaces include `StyledCard`, `StyledKpiCard`,
-`CustomAccordion`, `CustomAccordionSummary`, `CustomAccordionDetails`,
-`StyledTabs`, `StyledTab`, `StyledReadOnlyTextField`, and the styled table
-primitives. All styling is theme-aware and applications can override it with
-MUI theme configuration or `sx` properties.
-
-## Standalone feedback and form components
-
-The root entry point also includes standalone components missed by the first
-migration pass:
-
-- `StatusDialog`, `ProcessingModal`, `SuccessModal`, `ErrorModal`, and
-  `WarningModal`
-- `ErrorPage` plus router-independent 401, 403, 404, menu-not-found, and 500
-  presets
-- `AccessError`, `AccessLoader`, `ExpandableComment`/`CommentExpand`, and status
-  blinkers
-- `FormulaIcon`, `FormulaInfoIcon`/`FormulaInfoWithIcon`, and
-  `NameDescriptionPopover`/`NameDescPopover`
-- `BlueHeaderText`, `BoldText`, `ContentWrapper`, `QuestionTextWrapper`,
-  `PercentageInput`, `TextInput`, `TextInputWithLabel`,
-  `TextInputWithLabelIcon`, and `CurrencyInputWithLabelIcon`
-- `OptionSelectorWithLabel`, `OptionMultiSelectorWithLabel`,
-  `MandatoryIndicatorWithText`, and `RequestModalGridItem`
-- `CustomDropZone`, `MainSelector`, `TeslaStyleScrollIndicator`, and
-  `SelectWithTable`
-- `DocumentationCard`, `AppHelp`, `CardComponent`,
-  `CardComponentWithActions`, and `OperationsInfo`
-- `CustomTransition`, `DialogAction`, and `useDisplayOrder`
-
-These are modern replacements rather than byte-for-byte copies. They use MUI
-theme tokens and semantic controls instead of Tailwind classes, clickable
-`div` elements, or unmanaged portals.
-
-## Charts
-
-FusionCharts is isolated in a browser-only entry point so importing the main
-package does not evaluate browser globals during server rendering.
-
-```tsx
-import {
-  CommonChart,
-  ColumnChart,
-  DoughnutChart,
-  FusionChart,
-  LineChart,
-} from "@proounce/shared-common/charts/fusion";
-
-<ColumnChart
-  height={320}
-  dataSource={{
-    chart: { caption: "Requests" },
-    data: [{ label: "Open", value: "12" }],
-  }}
-/>;
 ```
 
-For the legacy common-chart contract, pass display metadata and chart items
-directly. Consumers do not need to construct the full FusionCharts data source:
-
-```tsx
-<CommonChart
-  type="column2d"
-  title="Requests by status"
-  xAxisName="Status"
-  yAxisName="Requests"
-  items={[
-    { label: "Open", value: 12 },
-    { label: "Closed", value: 28 },
-  ]}
-  showTypeSelector
-  showDataTable
-/>
-```
-
-The chart entry point exports:
-
-- `FusionChart` for raw FusionCharts `dataSource` configuration
-- `CommonChart` for the shared `title`, axes and `items` contract
-- `BarChart`, `ColumnChart`/`ChartColumn2D`, and `DoughnutChart`, accepting
-  either the legacy common contract or a raw `dataSource`
-- `LineChart`, `AreaChart`, and `PieChart`
-- `GenericChart`, `GenericChartCDMS`, `FusionDefaultCharts`,
-  `FusionDefaultChartsPF`, and `FusionDefaultChartsPH` compatibility exports
-
-`CommonChart` can expose a native HTML data table as the chart alternative and
-can provide an accessible chart-type selector. Map and congressional-map
-packages are not loaded by this common entry point because their FusionCharts
-map definitions are large and geography-specific.
+The exact list and original source file for every supported name is recorded in
+[the compatibility matrix](docs/COMPATIBILITY_MATRIX.md). Internal helper files
+needed by those exports are bundled but are not added to the public API.
 
-Chart data and the optional FusionCharts license key are supplied by the host
-application. The component never requests them from an API.
-
-## Icons
-
-Icons use dedicated entry points:
+## Optional entry points
 
 ```tsx
-import {
-  AddIcon,
-  EditOutlinedIcon,
-} from "@proounce/shared-common/icons/mui";
-import { Download, Search } from "@proounce/shared-common/icons/lucide";
+import { Add, EditOutlined } from "@proounce/shared-common/icons/mui";
+import { Search, X } from "@proounce/shared-common/icons/lucide";
+import { FusionChart } from "@proounce/shared-common/charts/fusion";
+import { CustomGridTable } from "@proounce/shared-common/grids/ag-grid";
 ```
 
-The MUI entry point exports only the registry required by shared and action
-components, plus selected legacy `*Icon` aliases. The Lucide entry point
-contains a curated UI/action set. Neither entry point wildcard-exports its
-underlying icon library.
+Only the curated icons required by the shared components and action registries
+are exported; the package does not duplicate the complete MUI icon library.
 
-Icons rendered internally by a shared component need no import in the
-consuming application. Import an icon only when the application renders that
-icon itself, using the curated `icons/mui` or `icons/lucide` subpath.
+## Compatibility policy
 
-## AG Grid
+A matching export name is not treated as proof of compatibility. The porting
+source of truth is the original implementation at commit `83e0238b`. The
+materializer preserves its dependency closure and rewrites only:
 
-AG Grid is an optional browser-oriented entry point and is not included when
-applications import the package root:
+- self-package imports to their original concrete modules;
+- extensionless FusionCharts file imports to the same `.js` files required by
+  Node ESM resolution;
+- removal of the unreachable first `pagination` prop in `CustomGridTable`.
+  The later `pagination={enablePagination}` already overrode it in every legacy
+  render, so this removes a build warning without changing runtime behavior.
 
-```sh
-npm install ag-grid-react ag-grid-community
-```
+Accessibility behavior is the behavior present in the source baseline. A
+consumer application must still perform WCAG testing for its theme, content,
+responsive layout, focus order and complete user journeys.
 
-```tsx
-import {
-  CustomGridHeaderCellWithInfo,
-  CustomGridTable,
-  type ColDef,
-} from "@proounce/shared-common/grids/ag-grid";
-
-interface Person {
-  id: string;
-  name: string;
-}
-
-const columns: ColDef<Person>[] = [
-  { field: "name", headerName: "Name" },
-];
-
-<CustomGridTable
-  ariaLabel="People"
-  data={[{ id: "1", name: "Ada" }]}
-  columns={columns}
-  getRowId={({ data }) => data.id}
-  enableSelection
-  onSelect={(rows) => console.log(rows)}
-/>;
-```
-
-The wrapper targets the platform's AG Grid 34 line and supplies community
-modules directly to the grid. It supports pinned totals, loading state,
-optional pagination, typed column definitions and keyboard-accessible multi-row
-selection. `CustomGridHeaderCellWithInfo`
-provides sortable headers with accessible information and formula actions.
-Applications should always provide `getRowId` when rows can be reordered or
-updated.
-
-## Main component groups
-
-- Actions, buttons, and icon buttons
-- Text, search, select, date, textarea, and checkbox inputs
-- Single, multiple, grouped, floating, and searchable dropdowns
-- Data tables and styled table primitives
-- Labels, read-only values, and mandatory indicators
-- Tooltips, alerts, loading spinners, and skeletons
-- Tabs, tab panels, toggle buttons, and switches
-- Confirmation dialogs
-- FusionCharts wrappers and presets
-- File input, empty/error states, skip links and live regions
-- Status dialogs, error-page presets, expandable comments and formula details
-
-## Legacy compatibility
-
-Common legacy names are retained where the new component has an equivalent:
-
-- `Button` and `StyledButton` map to `SharedButton`
-- `IconButton` maps to `SharedIconButton`
-- `TextField` and `StyledTextField` map to `SharedTextField`
-- `DatePicker` and `NormalDatePicker` map to `DateInput`
-- `CommonTable` and `CustomTable` are typed wrappers around the modern table
-  primitives and retain their legacy column contract
-
-Application-bound screens, review/reporting workflows, user app bars, Redux
-hooks, and components importing `@gc360/shared-utilities` are intentionally not
-included.
-
-The package also does not re-export generic MUI components, `dayjs`, adapters,
-or styling functions. Applications should import those from their owning
-packages. This prevents version ambiguity and keeps the public API focused on
-components maintained here.
-
-## Local development
+## Development and verification
 
 ```sh
-npm ci
-npm run check
+npm ci --legacy-peer-deps
+npm run audit:legacy-closure
+npm run port:legacy
+npm run typecheck
+npm run build
 npm pack --dry-run
 ```
 
 | Command | Purpose |
 | --- | --- |
-| `npm run typecheck` | Run strict TypeScript validation |
-| `npm run build` | Generate ESM, CommonJS, and declaration files |
-| `npm run check` | Type-check, run accessibility tests, and build |
-| `npm pack --dry-run` | Inspect the npm package contents |
-
-Generated files are written to `dist/` and should not be edited manually.
+| `npm run audit:legacy-closure` | Resolve private helpers and dependencies required by the 185 exports |
+| `npm run port:legacy` | Materialize the faithful source tree from the pinned commit |
+| `npm run audit:compatibility` | Reconcile package names with the legacy public barrel |
+| `npm run typecheck` | Validate TypeScript and declaration inputs |
+| `npm run build` | Generate ESM, CommonJS, declarations and source maps |
+| `npm run check` | Run package validation and the production build |
 
-## Accessibility
+Generated `dist/` files must not be edited manually.
 
-Components are designed as WCAG 2.2-ready foundations: controls have accessible
-names, shared buttons meet a 40px minimum target, MUI widgets retain keyboard
-and focus behavior, form errors are textual, table rows support keyboard
-activation, tabs can be explicitly linked to panels, and dialogs use MUI focus
-management. Representative components are checked with axe-core in `npm test`;
-the current suite covers 15 component and interaction scenarios.
+## Publishing
 
-Form controls also support `backupName` for legacy call sites that do not pass a
-visible label, `name`, or `id`:
-
-```tsx
-<SharedTextField backupName="Budget amount" />
-<AdvancedDropDownList backupName="Funding source" options={options} />
+```sh
+npm login --auth-type=web
+npm whoami
+npm ci --legacy-peer-deps
+npm run check
+npm publish --access public
 ```
 
-Accessible names are resolved in this order: associated visible label,
-explicit `aria-label`, human-readable `name`, human-readable caller-provided
-`id`, then `backupName`. Internal `useId()` values provide unique DOM identity
-but are never exposed as the control's accessible name. A visible label remains
-the preferred choice; backup names protect legacy and dynamically composed
-screens from producing unnamed controls.
-
-Automated checks cannot establish conformance for an application. Consumers
-must test their theme contrast, content, responsive layouts, focus order,
-validation flows, charts, and end-to-end journeys with keyboard and assistive
-technology.
-
-See [the component audit](docs/COMPONENT_AUDIT.md) for migration coverage,
-intentional exclusions, and compatibility decisions.
-
-## Jenkins publishing
-
-The included `Jenkinsfile` performs these stages:
-
-1. Checkout the repository.
-2. Optionally apply a patch, minor, or major version bump.
-3. Install dependencies with `npm ci`.
-4. Type-check, build, and inspect the npm package.
-5. Request manual approval when publishing is enabled.
-6. Publish the public scoped package to npm.
-
-Configure a Jenkins secret-text credential named `npm-token` using a token
-owned by an authorized publisher. That npm user must have permission to publish
-packages in the `proounce` organization. Publishing is disabled by default;
-enable the `PUBLISH_TO_NPM` parameter for a release build.
-The pipeline removes its temporary npm authentication file after completion.
-The package is published with public visibility. Installation does not require
-an npm organization membership or authentication token.
+The Jenkins pipeline installs, validates, requests approval and publishes
+`@proounce/shared-common`. Configure its credentials for the authorized npm
+publishing account and use trusted or staged publishing where available.
 
-## Design boundary
+## Audit documents
 
-This package must remain presentation-focused. Shared components receive data,
-callbacks, loading state, and errors through props. Do not add direct `fetch`,
-Axios, Redux store, router, or application-service dependencies.
+- [Compatibility matrix](docs/COMPATIBILITY_MATRIX.md)
+- [Component audit](docs/COMPONENT_AUDIT.md)
+- [Resolved legacy dependency closure](docs/LEGACY_CLOSURE.json)

package/dist/charts/fusion.cjs

@@ -7,8 +7,9 @@ var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 var MenuItem = require('@mui/material/MenuItem');
 var Stack = require('@mui/material/Stack');
-var TextField = require('@mui/material/TextField');
 var Typography = require('@mui/material/Typography');
+var TextField = require('@mui/material/TextField');
+require('@mui/material/FormControl');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -17,8 +18,8 @@ var charts__default = /*#__PURE__*/_interopDefault(charts);
 var ReactFusioncharts__default = /*#__PURE__*/_interopDefault(ReactFusioncharts);
 var MenuItem__default = /*#__PURE__*/_interopDefault(MenuItem);
 var Stack__default = /*#__PURE__*/_interopDefault(Stack);
-var TextField__default = /*#__PURE__*/_interopDefault(TextField);
 var Typography__default = /*#__PURE__*/_interopDefault(Typography);
+var TextField__default = /*#__PURE__*/_interopDefault(TextField);
 
 // src/charts/FusionChart.tsx
 var fusionRegistered = false;
@@ -84,6 +85,63 @@ var FusionDefaultCharts = FusionChart;
 var GenericChartCDMS = FusionChart;
 var FusionDefaultChartsPF = FusionChart;
 var FusionDefaultChartsPH = FusionChart;
+
+// src/accessibility/controlNames.ts
+function humanizeControlName(value) {
+  const normalized = value?.replace(/[_-]+/g, " ").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/\s+/g, " ").trim();
+  return normalized ? normalized.charAt(0).toUpperCase() + normalized.slice(1) : void 0;
+}
+function resolveControlName({
+  label,
+  ariaLabel,
+  name,
+  id,
+  backupName
+}) {
+  if (typeof label === "string" && label.trim()) return label.trim();
+  if (typeof ariaLabel === "string" && ariaLabel.trim()) return ariaLabel.trim();
+  return humanizeControlName(name) ?? humanizeControlName(id) ?? backupName;
+}
+function SharedTextField({
+  size = "small",
+  variant = "outlined",
+  InputLabelProps,
+  inputProps,
+  id,
+  name,
+  label,
+  backupName = "Text input",
+  ...props
+}) {
+  const generatedId = react.useId().replace(/:/g, "");
+  const controlId = id ?? `shared-text-field-${generatedId}`;
+  const accessibleName = resolveControlName({
+    label,
+    ariaLabel: inputProps?.["aria-label"],
+    name,
+    id,
+    backupName
+  });
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    TextField__default.default,
+    {
+      fullWidth: true,
+      size,
+      variant,
+      id: controlId,
+      name,
+      label,
+      InputLabelProps: { shrink: true, ...InputLabelProps },
+      inputProps: {
+        autoComplete: "off",
+        "data-gramm": "false",
+        ...!label && !inputProps?.["aria-labelledby"] ? { "aria-label": accessibleName } : {},
+        ...inputProps
+      },
+      ...props
+    }
+  );
+}
 var DEFAULT_CHART_TYPES = [
   { value: "column2d", label: "Column" },
   { value: "bar2d", label: "Bar" },
@@ -152,7 +210,7 @@ function CommonChart({
         children: [
           title ? /* @__PURE__ */ jsxRuntime.jsx(Typography__default.default, { component: "h2", variant: "h6", children: title }) : null,
           showTypeSelector ? /* @__PURE__ */ jsxRuntime.jsx(
-            TextField__default.default,
+            SharedTextField,
             {
               select: true,
               size: "small",