|
| 1 | +# Components survey — Issue #25 |
| 2 | + |
| 3 | +This document catalogues: |
| 4 | + |
| 5 | +1. The components already in `js/src/web/` that the redesign reuses |
| 6 | + or refactors. |
| 7 | +2. External libraries that we evaluated and either adopted or |
| 8 | + rejected, with the rationale captured for future maintainers. |
| 9 | + |
| 10 | +## 1. Existing components in this repo |
| 11 | + |
| 12 | +| Component | Path | What it does today | Role in the redesign | |
| 13 | +| ------------------------------------------------ | ---------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | |
| 14 | +| `App` | `js/src/web/app.js` | Top-level shell. Hosts `<TopBar>`, single `<nav>`, and the active view. | Replaced by `<AppShell>` that swaps between `<BottomNav>`, `<SideRail>`, and `<Drawer>` per breakpoint. | |
| 15 | +| `navItems` | `js/src/web/nav-items.js` | List of `[id, translationKey]` pairs (14 entries). | Re-grouped: 5 primary entries get pinned to the bottom-nav; the rest move into a "More" sheet/drawer. | |
| 16 | +| `useT` / `LocaleContext` / `t()` | `js/src/web/i18n.js` | Pure-JS i18n with locale detection, key fallback, ICU-lite interpolation. | Reused as-is; we add an "English-leak" guard in the parity test. | |
| 17 | +| `ConnectionGuide`, `LocalServerHelp`, `SettingsConnectFirstCta` | `js/src/web/connection-guide.js` | Help blocks rendered inline inside Settings. | Reused as the body of `ConnectionDetail`; the empty-state copy is moved into translated keys. | |
| 18 | +| `providerCatalogue` | `js/src/web/connection-guides.js` | Registry of all providers + their `apiCredentials.fields`, `archive`, `probeUrlTemplate`. | Extended with a new `setupSteps[]` field (issue R-N8). Every existing provider gets a per-step walkthrough. | |
| 19 | +| `SettingsView` | `js/src/web/settings-view.js` | Single-screen list of all provider cards (form + archive + probe). | Split into `ConnectionsList` (overview) and `ConnectionDetail` (per provider). Settings keeps app prefs. | |
| 20 | +| `TutorialOverlay`, `TutorialButton` | `js/src/web/tutorial.js` | Centred dialog with 5 default steps. Uses `metaSovereignTutorial` localStorage key. | Refactored into `<TutorialSpotlight>` that dims the page around a `data-tutorial-id` target. | |
| 21 | +| `useAsyncValue`, `AsyncFrame` | `js/src/web/views.js` | Async data wrappers used by every list view. | Reused unchanged. They isolate transitions between loading / error / empty / data states. | |
| 22 | +| `globalThis.localStorage` reads/writes | various | Theme + locale + tutorial preferences. | Reused; new `connections.lastVisited` preference added to remember which provider the user last opened. | |
| 23 | + |
| 24 | +## 2. External libraries |
| 25 | + |
| 26 | +### 2.1 Adopted (zero new runtime deps) |
| 27 | + |
| 28 | +The redesign explicitly avoids new runtime dependencies. We adopt |
| 29 | +**design tokens** from Chakra UI and **patterns** from Material 3 / |
| 30 | +HIG / Fluent without taking a hard dep. |
| 31 | + |
| 32 | +| Source | What we lift | |
| 33 | +| -------------- | ---------------------------------------------------------------------------------------------------------------------- | |
| 34 | +| Chakra UI v3 | Token names + scale (`--space-1..16`, `--radii-*`, `--shadow-*`), the `useBreakpointValue` hook _shape_, semantic colour roles. | |
| 35 | +| Material 3 | Window-size-class breakpoints (compact / medium / expanded), bottom-nav anatomy, navigation rail. | |
| 36 | +| Apple HIG | "Liquid Glass" surface treatment, ≤5 primary destinations, in-context onboarding spotlights. | |
| 37 | +| Microsoft Fluent | App-shell composition (top-bar + side rail + content), focus-ring style. | |
| 38 | +| WCAG 2.2 | Tap target ≥ 44 × 44 px (AAA), focus-visible outline, reduced-transparency fallback. | |
| 39 | + |
| 40 | +### 2.2 Evaluated and rejected |
| 41 | + |
| 42 | +| Library | License | Bundle cost (gzip) | Reason rejected | |
| 43 | +| ----------------------- | ------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 44 | +| `@chakra-ui/react@3` | MIT | ~120 KB | 38% bundle bloat over the current 320 KB SPA. The repo's design philosophy is "small, dependency-light, easy to fork." Adopting Chakra _patterns_ achieves the same UX without the cost. | |
| 45 | +| `shepherd.js` | MIT | ~30 KB | Existing `tutorial.js` already has the preference store and step model. The new spotlight primitive is a single function (`computeMaskRects`) — Shepherd would duplicate work. | |
| 46 | +| `driver.js` | MIT | ~5 KB | Smaller than Shepherd but still adds a runtime + CSS conflict. | |
| 47 | +| `reactour` | MIT | ~50 KB | Brings @reach/popover transitively. Too heavy for one component. | |
| 48 | +| `intro.js` | AGPL-3.0 | ~24 KB | License clash with the repo's Unlicense. | |
| 49 | +| `react-i18next` | MIT | ~30 KB | The existing pure-JS `t()` is sufficient and fast. A runtime swap would expand surface area for no UX gain. | |
| 50 | +| `@formatjs/intl` | BSD-3 | ~50 KB | Same reason as react-i18next. | |
| 51 | +| `framer-motion` | MIT | ~45 KB | Tutorial spotlight + drawer animations are simple enough for CSS transitions. Avoiding a JS animation runtime keeps the SPA fast on mid-tier mobile GPUs. | |
| 52 | +| `react-glassmorphism` | MIT | ~3 KB | Hard-codes blur values; breaks dark/light token swap. We codify the glass surface as a CSS utility class instead. | |
| 53 | +| `@radix-ui/react-dialog` | MIT | ~15 KB | The repo already has tiny custom dialog rendering via `el(...)`; introducing Radix would force us to replace 12 places where we render dialogs. | |
| 54 | + |
| 55 | +### 2.3 Optional native enhancements (not in scope for this PR) |
| 56 | + |
| 57 | +- `@capacitor/haptics`: nice-to-have for tap feedback in the mobile |
| 58 | + build but adds a peer dep and a native plugin. Tracked as a |
| 59 | + follow-up. |
| 60 | +- `@capacitor/status-bar`: would let us tint the iOS status-bar to |
| 61 | + match the glass surface. Same follow-up bucket. |
| 62 | + |
| 63 | +## 3. Component dependency graph after the refactor |
| 64 | + |
| 65 | +``` |
| 66 | +js/src/web/ |
| 67 | +├── app.js ← assembles AppShell + active view |
| 68 | +├── shell/ |
| 69 | +│ ├── AppShell.js ← TopBar + (BottomNav | SideRail | Drawer) + content |
| 70 | +│ ├── TopBar.js |
| 71 | +│ ├── BottomNav.js |
| 72 | +│ ├── SideRail.js |
| 73 | +│ ├── Drawer.js |
| 74 | +│ └── useBreakpoint.js ← media-query hook |
| 75 | +├── connections/ |
| 76 | +│ ├── ConnectionsList.js |
| 77 | +│ ├── ConnectionDetail.js |
| 78 | +│ ├── ConnectionStateBadge.js |
| 79 | +│ └── connection-router.js ← mediates list ↔ detail transitions |
| 80 | +├── tutorial.js ← refactored TutorialSpotlight |
| 81 | +├── settings-view.js ← simplified (app prefs only) |
| 82 | +├── connection-guide.js ← reused for setupSteps rendering |
| 83 | +├── connection-guides.js ← provider catalogue + new setupSteps[] |
| 84 | +├── views.js ← unchanged shell-of-views (Chat, Operator, etc.) |
| 85 | +└── locales/ |
| 86 | + ├── en.js ← extended with new keys |
| 87 | + └── ru.js ← parity-mirrored |
| 88 | +``` |
| 89 | + |
| 90 | +This module shape lets the existing tests in `js/tests/` keep |
| 91 | +working with minimal churn — the "shell" and "connections" folders |
| 92 | +are new, but the existing files keep their public exports. |
| 93 | + |
| 94 | +## 4. Public API stability |
| 95 | + |
| 96 | +The redesign does not change any public exports of |
| 97 | +`meta-sovereign` (the `package.json` `exports` map). The Web SPA is |
| 98 | +internal to the repo's build pipeline; only the `nav-items.js` order |
| 99 | +changes externally-visible behaviour for downstream embedders. |
| 100 | + |
| 101 | +The new files added to the public API: |
| 102 | + |
| 103 | +- `js/src/web/shell/index.js` (re-exports the shell components) |
| 104 | +- `js/src/web/connections/index.js` (re-exports the connections |
| 105 | + components) |
| 106 | + |
| 107 | +Both are added to the SPA bundle, not to the npm `exports` map, so |
| 108 | +no semver bump is required for downstream consumers. The `0.17.0` → |
| 109 | +`0.18.0` bump documented in the changeset reflects the user-visible |
| 110 | +UX overhaul. |
0 commit comments