docs(org-chart): finalize expanded chart accessibility and usage
Document the shared Vanilla/React Auto API, company selection, styling ownership and preserved card design. Preserve P5-2/P5-3 and P5-4 implementation reports and their historical verification boundaries.
This commit is contained in:
shkim4 committed
1 parent
064517ec46
commit
d2b76e7664
5 files changed
+482
-19
No files matched your search
@@ -24,25 +24,61 @@ chart.destroy();
|
||||
|
||||
## Organization links and employee information (P3)
|
||||
|
||||
### Layout boundary (P5-1A)
|
||||
### Layout boundary (P5-2 / P5-3)
|
||||
|
||||
`layoutMode?: 'fixed' | 'auto'` is independent of `displayMode`. The default
|
||||
`'fixed'` keeps the existing Workdesk composition and its display-mode behavior.
|
||||
`'auto'` currently selects the **P5-1A initial preview**, showing the representative
|
||||
and immediate organization groups from the validated hierarchy. Descendants stay
|
||||
in the dataset and statistics but are not placed in this preview. Automatic
|
||||
recursive placement/recalculation/collision prevention belongs to P5-1B;
|
||||
collapse controls and Zoom/Pan remain deferred. No preview readiness state claims
|
||||
those later features are complete.
|
||||
`'auto'` renders the complete validated hierarchy through dabeng 6.0.0.
|
||||
Root and same-parent siblings remain in their real hierarchy; the engine allocates
|
||||
recursive subtree widths. The Auto-only presenter reserves the tallest content
|
||||
height at each depth and observes article resizing so variable staff counts and
|
||||
font loading keep child rows and connectors aligned. Update/reload regenerate the
|
||||
same layout and dispose old observers. Auto has a transformed forest, initial Fit,
|
||||
5–300% configurable Zoom, Ctrl/Command wheel Zoom, pointer Pan and keyboard Pan.
|
||||
Ordinary wheel scrolling remains with the page. Dialogs stay outside the forest.
|
||||
|
||||
Use `companyId` with Auto to select an existing company preset (default `hanmac`).
|
||||
Set optional `Organization.companyId` on company roots; descendants inherit it.
|
||||
Child company changes are rejected instead of mixing independent trees.
|
||||
Legacy roots resolve from a known leader affiliation, then the `companyId` fallback
|
||||
(default `hanmac`). `companyId` is no longer a global recoloring selector.
|
||||
The seven IDs are `hanmac`, `saman`, `jangheon-industry`, `jangheon`, `ptc`, `halla`,
|
||||
and `baron`. Main colors style only Expanded group headers; indexed secondary
|
||||
and `baron`. Main colors style Expanded group headers and card accents; indexed secondary
|
||||
variables come from that same preset. Fixed ignores this option and preserves
|
||||
its organization gradients. Unknown Auto IDs reject construction with `TypeError`.
|
||||
The preview reuses approved Workdesk card presentation, the same data/engine and
|
||||
employee dialog; it has an independent wrapper without Fixed coordinates or scaling.
|
||||
Choose `displayMode: 'readOnly'` for the matching read-only popup name policy.
|
||||
The Auto presenter shares photo/position/name and employee dialog behavior without
|
||||
Fixed SVG cards, coordinates or scaling. Group title DOM carries the organization
|
||||
ID; the full title is a native toggle with aria-expanded and disabled empty groups.
|
||||
Separate link icons preserve page navigation. Child collapse state survives parent
|
||||
collapse and company reselection. Auto uses actual Employee names/positions;
|
||||
three-character Korean names display with spaces; position whitespace is removed
|
||||
only for display, preserving raw data. P5-4 retains the current Expanded cards
|
||||
by user decision; the two external SVG references are no longer required.
|
||||
Auto geometry variables live under
|
||||
`.hm-orgchart-expanded`; there is no new public `layoutConfig` API.
|
||||
The existing employee popup still uses its displayMode policy and receives raw data.
|
||||
|
||||
P5-4 adds group-title Hover feedback and reveals offscreen keyboard-focused cards
|
||||
without changing Zoom. Drag click suppression does not block Enter/Space activation.
|
||||
See [Expanded usage and styling](../../docs/org-chart/expanded-usage.md) for complete
|
||||
Vanilla/React examples, Shadow DOM CSS ownership and verification boundaries.
|
||||
|
||||
`selectedCompanyIds` / `setSelectedCompanies(ids?)` filter the view: undefined
|
||||
means all, [] means empty. Summary raw counts always describe the unmodified source;
|
||||
the Auto selection label reports selected company/employee counts separately.
|
||||
`getSelectedCompanies`, `zoomTo`, `panBy`, `fitToView`, `getViewportState` expose
|
||||
view operations. Selection requires a mounted Auto handle; Fixed rejects it.
|
||||
|
||||
`companyTopNodes` maps company IDs to optional employeeId, title, name, profileImage,
|
||||
organizationName and display (`card`, `titleOnly`, `hidden`). An explicit employee
|
||||
must belong to that company's root; null removes top-card assignment. Overrides
|
||||
affect presentation only, preserving employee IDs, popup data and parentId.
|
||||
|
||||
`employeeConnections` maps organization IDs to top/left/right staff routes (default
|
||||
top). Leaders connect from their title above. SVG paths use actual article/card
|
||||
coordinates; each endpoint shares its direction with the corresponding single-side
|
||||
border accent. Employee preset follows its known affiliation, otherwise its tree.
|
||||
All remaining borders are neutral; an inset accent width variable preserves size.
|
||||
Width/height/padding/radius/photo/font/spacing variables are scoped to Auto.
|
||||
|
||||
```js
|
||||
const chart = createOrgChart({
|
||||
@@ -50,12 +86,43 @@ const chart = createOrgChart({
|
||||
layoutMode: 'auto',
|
||||
displayMode: 'readOnly',
|
||||
companyId: 'hanmac',
|
||||
selectedCompanyIds: ['hanmac', 'saman'],
|
||||
companyTopNodes: { hanmac: { title: '회장', display: 'card' } },
|
||||
employeeConnections: { 'hanmac-office-0': 'left' },
|
||||
});
|
||||
```
|
||||
|
||||
Options are captured at construction: create a new handle to change the layout or
|
||||
company. Standalone Tree/Summary factories keep their existing rendering paths.
|
||||
company/top-node/connection/zoom configuration. Selection uses its own setter.
|
||||
Standalone Tree/Summary factories keep their existing rendering paths.
|
||||
|
||||
`examples/org-chart/data-expanded-{small,medium,large}.json` contain exactly
|
||||
20/100/300 unique virtual employees and 3/5/7 companies. Run
|
||||
`node examples/org-chart/create-expanded-fixtures.mjs` to reproduce them.
|
||||
After build/prepare, open `http://127.0.0.1:4178/expanded.html`.
|
||||
Expanded OrgChart is one of the same four public Stories; it offers fixture and
|
||||
company controls without filtering JSON in the Story. Native Core controls are
|
||||
the explicit framework-independent HTML adapter, not imitations of HM React UI.
|
||||
|
||||
|
||||
### Historical P5-1B verification and local runtime
|
||||
|
||||
Core/React builds and Typechecks pass. Focused browser evidence covers the
|
||||
complete four-depth hierarchy, unequal employee counts, updates/reload, all seven
|
||||
company presets, shared HTML/React cards and popup focus, viewport overflow, and
|
||||
minimal Fixed baseline regression. Evidence is generated under
|
||||
`test-results/org-chart-p5-1b`; the authored runner is
|
||||
`examples/org-chart/verify-p5-1b.mjs`. Its baseline must be copied from a known
|
||||
pre-change build before rebuilding. The runner uses configurable
|
||||
`ORGCHART_STORY_ORIGIN`, `ORGCHART_PLAYWRIGHT_MODULE`, and `ORGCHART_CHROME`.
|
||||
Do not assume another PC's localhost or generated dist exists.
|
||||
|
||||
Use npm with `package-lock.json`; a fresh install uses `npm ci`. The existing
|
||||
package test runner imports Node's `globSync`, so use a runtime providing that API, such as the verified Node 24,
|
||||
for focused unit tests. This PC's Node 20.20.1 built the packages successfully;
|
||||
the installed Codex Node 24.19.0 ran the unit tests without changing the runner.
|
||||
Final reference SVG design, collapse/Zoom/Pan, real screen-reader speech/touch and
|
||||
historical full regression suites are not verified by this phase.
|
||||
|
||||
### P3.2 follow-up: representative badges
|
||||
|
||||
@@ -93,7 +160,7 @@ Omit `onEmployeeClick` to use the default popup. Vanilla options are captured at
|
||||
|
||||
`mount(container)` also accepts the container at mount time. Constructing a handle and importing the ESM facade require no DOM. Mount requires a connected HTMLElement. One handle owns one container, preserving host siblings. Duplicate mount and update/reload before mount or after destroy reject with a usage error. Data/Source failures become structured `error` states and resolve the operation. Destroy is synchronous, idempotent and terminal; use a new handle to mount again. `subscribe(listener)` returns an unsubscribe function; `getState()` returns the immutable current state. Consumer callback errors do not break the Core.
|
||||
|
||||
`update` captures its input immediately and preserves the current Source. `reload(source?)` optionally replaces it. The last started operation wins; earlier requests are aborted, and stale responses cannot commit. Call completion means the operation was applied, superseded, or produced a controlled error, rather than that every image/font finished loading. Regeneration resets expand/scroll state; removed keyboard focus moves to the scroll region.
|
||||
`update` captures its input immediately and preserves the current Source. `reload(source?)` optionally replaces it. The last started operation wins; earlier requests are aborted, and stale responses cannot commit. Call completion means the operation was applied, superseded, or produced a controlled error, rather than that every image/font finished loading. Fixed keeps its prior regeneration policy. Auto preserves valid organization collapse IDs and transform state on toggles; reload/selection fits the new visible forest. Removed toggle focus is restored to the same organization, with viewport fallback.
|
||||
|
||||
## Data contract
|
||||
|
||||
@@ -130,4 +197,4 @@ Open `http://127.0.0.1:4178/index.html` for bundled ESM + external JSON. Open `e
|
||||
|
||||
`npm run test:org-chart-browser` expects Playwright supplied by the verification environment. If not installed locally, set `ORGCHART_PLAYWRIGHT_MODULE` to its absolute `index.mjs`/`index.js` and optionally `ORGCHART_CHROME` to a Chrome executable. Production has no browser-test dependency. Evidence is written under `test-results/org-chart-browser/`.
|
||||
|
||||
The React wrapper owns only ref/effect lifecycle, source/props updates and cleanup, including forwarding the additive P3 lookup options; HTML and React render the same Core. Standalone `createOrgChartTree`, `createPositionSummary`, `createAffiliationSummary` and `createStatusSummary` factories are exported at the package root and return the existing `OrgChartHandle`. The three public OrgChart Stories are Logo · Personnel Summary, Department Colors and Full Composition. Original verification Stories and independent component Stories remain available under the excluded `internal` tag.
|
||||
The React wrapper owns only ref/effect lifecycle, source/props updates and cleanup, including forwarding lookup and Auto view options; HTML and React render the same Core. Standalone `createOrgChartTree`, `createPositionSummary`, `createAffiliationSummary` and `createStatusSummary` factories are exported at the package root and return the existing `OrgChartHandle`. The four public OrgChart Stories are Logo · Personnel Summary, Department Colors, Full Composition and Expanded OrgChart. Original verification Stories and independent component Stories remain available under the excluded `internal` tag.
|
||||
Reference in new issue
Block a user