@hybridcore/ui 1.6.1 → 1.6.3

package/CATALOG.md

@@ -0,0 +1,179 @@
+# @hybridcore/ui — Component Catalog
+
+**Catalog for version:** 1.6.1 (matches `package.json` at the time this file was last updated)
+
+This file lists every public component exported by `@hybridcore/ui`. Consumers can read it directly (`cat node_modules/@hybridcore/ui/CATALOG.md`) or use a `/find-component` slash command to search semantically. Keeping it in sync is required — see [`docs/COMPONENT_GUIDE.md`](./docs/COMPONENT_GUIDE.md) § "Catalog maintenance."
+
+All components are imported from the package root:
+
+```ts
+import { ComponentName } from '@hybridcore/ui';
+```
+
+---
+
+## Components
+
+### Layout & containers
+
+| Component          | Theme key          | Purpose                                                                 | Tags                            |
+| ------------------ | ------------------ | ----------------------------------------------------------------------- | ------------------------------- |
+| Card               | HCCard             | Portrait/landscape card with media, title, avatar, stats, and actions   | card, layout, media             |
+| CardAlternate      | HCCardAlternate    | Compact card with header row, avatar, title/subtitle, and menu          | card, layout                    |
+| CollapsibleCard    | HCCollapsibleCard  | Accordion-style card with expandable content                            | card, accordion, collapsible    |
+| Container          | HCContainer        | Themed card wrapper with `CardHeader` + `CardContent` slots             | container, card                 |
+| Widget             | HCWidget           | Generic widget shell (Root/Header/Content/Footer slots)                 | widget, container, layout       |
+| FlexCol            | —                  | Styled flex column primitive                                            | layout, flex                    |
+| FlexRow            | —                  | Styled flex row primitive                                               | layout, flex                    |
+| ConditionalWrapper | —                  | Pure JSX helper — renders `children` through a `wrapper` if `condition` | utility, wrapper                |
+| ScrollDrag         | HCScrollDrag       | Drag-to-scroll horizontal container for overflow content                | layout, scroll, drag            |
+| Placeholder        | HCPlaceholder      | Skeleton placeholder for loading/empty states                           | placeholder, loading, skeleton  |
+
+### Forms & inputs
+
+| Component                  | Theme key                  | Purpose                                                                  | Tags                                    |
+| -------------------------- | -------------------------- | ------------------------------------------------------------------------ | --------------------------------------- |
+| Button                     | HCButton                   | Themed MUI button with `onNavigate` / `onNavigateBack` callback props    | input, button                           |
+| IconButton                 | HCIconButton               | Three-variant icon button (default, vertical label, mini text+icon)      | input, button, icon                     |
+| ToggleViewButton           | HCToggleViewButton         | Grid/list/map view toggle group                                          | input, button, toggle, view             |
+| SearchInput                | HCSearchInput              | Themed search input with adornments (outlined/filled/standard variants)  | input, search                           |
+| PhoneInput                 | HCPhoneInput               | International phone-number input with country code                       | input, phone                            |
+| ColorPicker                | HCColorPicker              | Color picker built on `react-color`                                      | input, color                            |
+| DateTimePicker             | HCDateTimePicker           | Combined date + time picker with menu of preset times                    | input, date, time                       |
+| DateRangePicker            | HCDateRangePicker          | Calendar range picker (start/end date)                                   | input, date, range                      |
+| DatePickerWithCustomRange  | HCDatePickerWithCustomRange| Toggle between relative presets (last N days) and custom date range      | input, date, range, preset, filter      |
+| DurationSelect             | HCDurationSelect           | Duration picker (e.g. 5 minutes, 1 hour)                                 | input, duration, time                   |
+| TreeSelect                 | HCTreeSelect               | Hierarchical tree-style multi-select with dialog                         | input, select, tree, hierarchy          |
+| TreeViewFilter             | HCTreeViewFilter           | Filterable tree-view with checkboxes (used inside `TreeSelect`)          | filter, tree, hierarchy, checkbox       |
+| RangeSelector              | HCRangeSelector            | Polymorphic range input — number, date, geometry, string, composite-list | input, range, filter                    |
+| Uploader                   | HCUploader                 | Drag-drop file uploader with image thumbnails + preview dialog           | input, upload, file, image              |
+| VisuallyHiddenInput        | HCVisuallyHiddenInput      | Accessible hidden `<input>` for screen readers and file pickers          | input, accessibility, hidden            |
+| GeometryPicker             | HCGeometryPicker           | Picker for geographic geometries (coordinate, draw, KML, WKT, edit)      | input, geometry, map, geo, wkt          |
+| GeometryDraw               | HCGeometryPicker (geometry)| Geometry drawing surface (sub-component of `GeometryPicker`)             | input, geometry, draw, map              |
+| GeometryParser             | HCGeometryPicker (parser)  | WKT/coordinate parser (sub-component of `GeometryPicker`)                | input, geometry, wkt, parser            |
+
+### Data display & tables
+
+| Component                  | Theme key                    | Purpose                                                                  | Tags                                |
+| -------------------------- | ---------------------------- | ------------------------------------------------------------------------ | ----------------------------------- |
+| DataGrid                   | HCDataGrid                   | Themed wrapper over MUI X DataGrid with default styling                  | data-table, grid                    |
+| InstanceTable              | HCInstanceTable              | Domain table for ontology instances (templated rows + per-row actions)   | data-table, ontology, domain        |
+| InstanceHierarchyTable     | HCInstanceHierarchyTable     | Accordion table showing template hierarchy with counts                   | data-table, hierarchy, accordion    |
+| SimplePivotTable           | HCSimplePivotTable           | Pivot table with row/column dimensions + aggregations (sum/avg/min/max)  | data-table, pivot, aggregation      |
+| PaginatedList              | HCPaginatedList              | Paginated list with selection mode and snapshot export                   | data-list, pagination, selection    |
+| SortableList               | HCSortableList               | Drag-and-drop sortable list                                              | data-list, sortable, drag           |
+| InstanceVariableList       | HCInstanceVariableList       | Renders typed instance variables with per-type widgets                   | data-list, ontology, variable, domain |
+
+### Charts
+
+| Component                  | Theme key                  | Purpose                                                                | Tags                                  |
+| -------------------------- | -------------------------- | ---------------------------------------------------------------------- | ------------------------------------- |
+| ChartWrapper               | HCChartWrapper             | Switches between 14 chart types from a single config                   | chart, wrapper                        |
+| CandlestickChart           | HCCandlestickChart         | Financial OHLC candlestick chart                                       | chart, financial, ohlc                |
+| ColumnLineMix              | HCColumnLineMix            | Mixed column + line chart for combined metrics                         | chart, column, line                   |
+| DrillDownTreemap           | HCDrillDownTreemap         | Treemap with click-to-drill-down hierarchy                             | chart, treemap, hierarchy             |
+| DrillDownVoronoiTreemap    | HCDrillDownVoronoiTreemap  | Voronoi-tessellation treemap with drill-down                           | chart, treemap, voronoi               |
+| Heatmap                    | HCHeatmap                  | Categorical heatmap (X/Y axes, color-coded values)                     | chart, heatmap                        |
+| HighlightLineChart         | HCHighlightLineChart       | Line chart with hover highlighting                                     | chart, line, hover                    |
+| LineChart                  | HCLineChart                | Multi-series line chart                                                | chart, line                           |
+| LogaritmicScale            | HCLogaritmicScale          | Chart with logarithmic Y-axis                                          | chart, log, scale                     |
+| MultipleValueAxes          | HCMultipleValueAxes        | Chart with multiple Y-axes for different value ranges                  | chart, axis                           |
+| NestedPie                  | HCNestedPie                | Nested (concentric) pie chart                                          | chart, pie, nested                    |
+| PackedCircles              | HCPackedCircles            | Circle-packing visualization                                           | chart, circle, packing                |
+| PieChart                   | HCPieChart                 | Simple pie chart                                                       | chart, pie                            |
+| StackedAreaRadar           | HCStackedAreaRadar         | Radar chart with stacked area fills                                    | chart, radar, stacked                 |
+| StackedColumnChart         | HCStackedColumnChart       | Stacked column chart                                                   | chart, column, stacked                |
+| XYChart                    | HCXYChart                  | Generic X-Y series chart                                               | chart, xy                             |
+
+### Maps
+
+| Component         | Theme key         | Purpose                                                                | Tags                          |
+| ----------------- | ----------------- | ---------------------------------------------------------------------- | ----------------------------- |
+| Map               | —                 | OpenLayers/Mapbox map primitive with imperative handle (`ref.zoom`, etc.) | map, openlayers, mapbox       |
+| DataMap           | HCDataMap         | Geographic data map with feature layer + controls                      | map, data, geo                |
+| HeatMap           | HCHeatMap         | Geographic heat-map with gradient legend                               | map, heatmap, geo             |
+| PrrMap            | HCPrrMap          | PRR-level map with severity icons + legend                             | map, prr, severity, geo       |
+| RasterGridMap     | HCRasterGridMap   | Raster grid overlay on map with color-scale legend                     | map, raster, grid, geo        |
+
+### Filters & selectors
+
+| Component                  | Theme key                   | Purpose                                                                | Tags                                |
+| -------------------------- | --------------------------- | ---------------------------------------------------------------------- | ----------------------------------- |
+| TemplateFilters            | HCTemplateFilters           | Tabbed template filter set                                             | filter, template, tab               |
+| TemplatePropertyFilters    | HCTemplatePropertyFilters   | Accordion of per-property filters (number, date, enum)                 | filter, property, accordion         |
+| PropertyFilterInput        | HCTemplatePropertyFilters   | Single property filter input (sub-component, may be reused standalone) | filter, property                    |
+| DisseminationList          | HCDisseminationList         | Multi-select for security dissemination groups (creatable)             | selector, security, multi-select    |
+| SecurityLevel              | HCSecurityLevel             | Security classification level selector                                 | selector, security                  |
+
+### Navigation, indicators & feedback
+
+| Component         | Theme key                  | Purpose                                                                | Tags                            |
+| ----------------- | -------------------------- | ---------------------------------------------------------------------- | ------------------------------- |
+| Tabs              | HCTabs                     | Tabs with optional badges, Apple-style variant, URL-hash state         | navigation, tabs                |
+| ContextMenu       | HCContextMenu              | Right-click / programmatic context menu at an x/y position             | menu, context                   |
+| Divider           | HCDivider                  | MUI divider with vertical-orientation styling preserved                | layout, divider                 |
+| LinearIndicator   | HCLinearIndicator          | Bidirectional linear progress / value indicator                        | indicator, progress, linear     |
+| Loading           | HCLoading                  | Centered circular spinner with optional overlay                        | loading, spinner                |
+| StatsBox          | HCStatsBox                 | Label + value + icon stat tile                                         | stats, indicator                |
+| MetricCard        | HCMetricCard               | KPI card with value, change, trend, and inline mini-chart              | metric, kpi, card, chart        |
+| TimelineWidget    | HCTimeline                 | Vertical timeline list with dots + load-more                           | timeline, list, history         |
+| TextOverflow      | HCTextOverflow             | Text with ellipsis + native tooltip on overflow                        | text, overflow, ellipsis        |
+| StaticText        | HCStaticText               | Themed renderer for static HTML content (headings, lists, links)       | text, html, static              |
+| ObjectProfileCard | HCObjectProfileCard        | Profile card with avatar upload + variable list                        | card, profile, avatar, domain   |
+| PositionalTooltip | HCPositionalTooltip        | Tooltip anchored to an arbitrary x/y point                             | tooltip, positional             |
+
+### Domain forms
+
+| Component         | Theme key         | Purpose                                                                | Tags                            |
+| ----------------- | ----------------- | ---------------------------------------------------------------------- | ------------------------------- |
+| InstanceForm      | HCInstanceForm    | Full ontology instance form (variables, composite-list/matrix, policy) | form, ontology, domain          |
+| TemplateForm      | HCTemplateForm    | Template-definition form (property list, icon, recognition)            | form, template, domain          |
+
+### Document viewer
+
+| Component         | Theme key         | Purpose                                                                | Tags                              |
+| ----------------- | ----------------- | ---------------------------------------------------------------------- | --------------------------------- |
+| DocumentViewer    | HCDocumentViewer  | App-shell document viewer with toolbar, side panel, multi-format       | document, viewer, pdf, image      |
+
+### Access control
+
+| Component | Theme key | Purpose                                                                | Tags          |
+| --------- | --------- | ---------------------------------------------------------------------- | ------------- |
+| Access    | HCAccess  | Permission gate — renders children if granted, fallback otherwise      | access, gate  |
+
+---
+
+## Utilities & non-component APIs
+
+| Export                         | Kind          | Purpose                                                                  | Tags                          |
+| ------------------------------ | ------------- | ------------------------------------------------------------------------ | ----------------------------- |
+| `HCNotificationProvider`       | Provider      | Mount once at app root; required for `notify()` toasts                   | notification, toast, provider |
+| `notify`                       | Function      | Imperative toast API — `notify.error/warning/info/success(msg)`          | notification, toast           |
+| `removeNotification`           | Function      | Programmatically dismiss a notification by id                            | notification, toast           |
+| `alert(title, description)`    | Function      | Imperative modal alert (returns a promise)                               | modal, alert                  |
+| `confirm(title, description)`  | Function      | Imperative confirmation modal (returns a boolean promise)                | modal, confirm                |
+| `createTheme` / `ThemeProvider`| Re-export     | MUI theme creation + provider (re-exported for convenience)              | theme, mui                    |
+| `LocalizationProvider`         | Re-export     | MUI X date-pickers localization provider                                 | theme, dates, mui             |
+| `AdapterDayjs`                 | Re-export     | dayjs adapter for the MUI X localization provider                        | theme, dates, dayjs           |
+| `AccessUtils.*`                | Namespace     | Helper functions for access checks (`hasUIAccess`, `hasDataAccess`, etc.)| access, utility               |
+| `DEFAULT_VIRIDIS_COOL`         | Constant      | Default 8-color viridis-cool palette for charts                          | chart, palette                |
+| `DEFAULT_RELATIVE_PRESET_LABELS` | Constant    | Default labels for `DatePickerWithCustomRange` relative presets          | date, preset                  |
+
+---
+
+## Versioning
+
+Each catalog row is stable across patch versions. Minor versions may add rows. Major versions may rename or remove components — breaking changes are called out below.
+
+### Breaking changes since previous major
+
+*(empty — `@hybridcore/ui` is on 1.x; populate this section when cutting 2.0)*
+
+---
+
+## How to use this catalog
+
+- **Direct read:** `cat node_modules/@hybridcore/ui/CATALOG.md` in any consumer project.
+- **Slash command:** install `/find-component` in your project's `.claude/commands/` (reference implementation: `SmartNavigator/frontend/.claude/commands/find-component.md`). It reads this file and matches against component name, purpose, and tags.
+
+Theme keys (`HC*`) are the canonical names used in `theme.components.HC*.styleOverrides` and `defaultProps`. See [`docs/COMPONENT_GUIDE.md`](./docs/COMPONENT_GUIDE.md) § "Theme Augmentation" for how to override styling per-deployment.

package/README.md

@@ -28,7 +28,7 @@ yarn dev          # opens the Vite dev server with Storybook
 
 ### Iterate against a real consumer (e.g. Smart Navigator) without publishing
 
-We use [`yalc`](https://github.com/wclr/yalc) to link the lib into consumer projects locally, so changes show up in their dev server without a `yarn version` + `npm publish` round trip. Full rationale, gotchas, and follow-ups in [`docs/plans/local-dev-flow.md`](./docs/plans/local-dev-flow.md); current progress in [`docs/BACKLOG.md`](./docs/BACKLOG.md) § 0.1.
+We use [`yalc`](https://github.com/wclr/yalc) to link the lib into consumer projects locally, so changes show up in their dev server without a `yarn version` + `npm publish` round trip. Full rationale and gotchas in [`docs/plans/local-dev-flow.md`](./docs/plans/local-dev-flow.md).
 
 One-time setup (per machine):
 
@@ -76,5 +76,4 @@ git push --follow-tags
 
 - [`docs/COMPONENT_GUIDE.md`](./docs/COMPONENT_GUIDE.md) — authoring rules (4-file structure, `HC*` prefix, theme augmentation block)
 - [`docs/THEMING.md`](./docs/THEMING.md) — consumer-facing override guide for any project using this lib
-- [`docs/BACKLOG.md`](./docs/BACKLOG.md) — migration backlog (which components conform, which still need refactoring)
 - [`docs/plans/`](./docs/plans/) — cross-cutting initiative plans (e.g. local dev flow, exports standard)