Skip to content
Merged
72 changes: 36 additions & 36 deletions PROJECT.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ it goes here.

## Where to work

`feature/temporal-migration`, in this repository's main checkout (`~/daxir/react-native-components`), is the one
source of truth (owner, 2026-10-07). Branch from it and merge back into it; keep no long-lived
`main`, in this repository's main checkout (`~/daxir/react-native-components`), is the one
source of truth (owner, 2026-10-15: trunk-based development). Branch from it and merge back into it; keep no long-lived
worktree.
The authority is fleet-management `docs/canonical-trunk.md`.

Expand Down Expand Up @@ -43,7 +43,6 @@ change would break a consumer, stop and ask (§9).
```
packages/components/src/
index.js THE public API — the single barrel. Nothing is public unless exported here.
portable.js the web-safe subset of the barrel (C-35), for web hosts — see "Portable entry"
styles.js shared style objects built from MD3LightTheme tokens
tones.js status tones (success/warning/danger/neutral/info) -> theme roles + icons
consts.js shared constants (LAYOUT_MODE, …)
Expand All @@ -65,9 +64,8 @@ Bigger features are folders with an `index.js` and internal sub-components + hoo

1. `packages/components/src/<Name>/<Name>.js`
2. `packages/components/src/<Name>/<Name>.stories.js`
3. Export it from `packages/components/src/index.js` — otherwise it does not exist for consumers. If it
loads on the web without native modules, export it from `portable.js` too (the guard test will tell you
if it does not).
3. Export it from `packages/components/src/index.js` — otherwise it does not exist for consumers. It is the
package's only entry (see "One entry").
4. Add the folder's glob to `.storybook/main.ts` (see "Storybook" below — the web config is a
hand-maintained list, not a glob over `src/**`).
5. Any user-facing string goes into **both** `Translations/en.json` and `es.json` via `localized()`.
Expand Down Expand Up @@ -147,7 +145,7 @@ Since **0.4.0** (C-25):
i18next as a resource bundle, so `react-i18next` readers see it. `%{}` interpolates as everywhere.
- **`currentLocale()`** is exported by both twins; `format.js` reads it. It used to read `i18n-js`
directly, so on the web every date was formatted in `en`.
- `merge` (deep merge of nested catalogues) is exported from the barrel and the portable entry.
- `merge` (deep merge of nested catalogues) is exported from the barrel.

`Localization.web.js` is the web twin, and as of 0.2.0 it really is one: same loader, same `%{}`
placeholder syntax (i18next's default `{{}}` would have shown narration placeholders raw), same
Expand Down Expand Up @@ -180,29 +178,27 @@ the components take the result and paint it.
`file:` until 0.2.0 is published, then `^0.2.0`. `Order/__tests__/d50.test.js` keeps every legacy reference contained inside it and fails
if one appears anywhere else — or if that file stops being the legacy table.

## Portable entry (C-35) and partner components (K-22) — 0.4.0-dev

`src/portable.js` (published as `lib/portable`) is what a **web host** imports: the partner console
(`CustomerApp/admin-web`) and the presentational views it borrows from the app. It re-exports only
modules that load on react-native-web **without stubs**: List, ScreenWrapper, ChipList, Tabs,
SegmentedButtonGroup, ActionGroup, SideNav, TouchableRippleWrapper, TN*, `ButtonWrapper`,
`PhotoGalleryDisplay`, `styles`, `LAYOUT_MODE`, a `Form` subset (PersonInfo, VehicleInfo,
BusinessInfo, DriverInfo, EmailPassword, SecretInputText), `StripeForm.AccountBank`, Localization (`localized`,
`setI18nConfig`, `registerFlatCatalog`, `currentLocale`, `merge`), the formatters, the Order and Partner view
models, the K-22 components and the generic web-host UI (next section). `ImagePicker` is **not** portable (picker, permissions, draggable list): a web host shows
photos with `PhotoGalleryDisplay` and the app injects the picker.

- `packages/components/__tests__/portableEntry.test.js` walks its static import graph the way a web
bundler does (`.web.js` first) and fails if a native-only module becomes reachable (react-native-config,
dotenv, localize, image picker, action sheet, permissions, geolocation, gesture handler, reanimated,
draggable list, mapbox, bottom sheets, centrifuge) — or the package's own name, which drags the barrel in.
## One entry (0.6.0) and partner components (K-22)

The package has **one entry**, `index.js` (the barrel), as React Native and its web toolchains expect (owner,
2026-11-07). `lib/portable`, the web-safe subset served from C-35 (0.4.0) to 0.5.5, was removed in 0.6.0: the web
host it was made for (`admin-web`) is gone, and since B-52 the console mounts the whole app and, with it, the barrel.
How the barrel runs on the web:

- **Web differences live in `.web.js` twins** inside this package (`Config`, `Localization`, `MapboxGLWrapper`,
`OptionPicker/OptionSheet`); a web bundler resolves them first.
- **Native modules a web bundle cannot load are the host's web stubs** (CustomerApp `web-stubs/`:
`react-native-config`, the map wrapper's override, `navigator.geolocation`), applied only on the web.
- **`Config.web.js`**: on the web the host calls `configureComponents({ IMAGEKIT_URL, … })` once before
rendering. Native `Config.js` exports the same function (merge, no behaviour change).
- **Never import this package by its published name from inside it**, and import `../ScreenWrapper`
(the index that attaches `.Section`/`.Container`), not `../ScreenWrapper/ScreenWrapper`.
- `OptionPicker/OptionSheet.js` is the native action sheet; `OptionSheet.web.js` is a Paper modal with the
same `show()`/`hide()` ref, which is what lets `Form.BusinessInfo` load on the web.
- `lib/*` deep imports keep working; there is deliberately no `exports` map yet.
- `lib/*` deep imports keep working; there is deliberately no `exports` map yet. Hosts import the package itself.
- Two of its libraries, the phone input and the places autocomplete, import the package back by name. A host's jest
mock that spreads the real barrel runs again while the barrel loads (CustomerApp `src/testUtils/actualModuleWith.js`
shows the way around it).

K-22 components (APIs frozen in `CustomerApp/admin-web/docs/ARCHITECTURE.md` §5), RN primitives + Paper,
themed through `useTheme()` so a host's theme applies:
Expand All @@ -215,7 +211,7 @@ themed through `useTheme()` so a host's theme applies:
- `Timeline` — `history` and `steps`.
- Document requirements (contract request #117, 0.5.4), fed by a `getMyStatus` checklist item, so no host keeps a
document type of its own:
- `Partner/DocumentRequirementCard` (portable) — a Paper `Card` composed as Paper composes one: the title is
- `Partner/DocumentRequirementCard` — a Paper `Card` composed as Paper composes one: the title is
`requirementTitle(item)` (the rule's name for the market, else the catalogue's), `subtitle` is the host's,
then, in its `Card.Content`, `covers` (the photos taken and not sent, in order, each `{ uri, label }` with the
name a screen reader says), `note` and the rule's explanation, and `actions`
Expand All @@ -225,7 +221,7 @@ themed through `useTheme()` so a host's theme applies:
`aria-live`) that stays mounted, so a screen reader announces each next step. `Card.Actions` gets, through its
`style`, `flexWrap` and a `spacing.x2` row gap (it does not wrap by itself; its alignment and padding stay), and
its buttons are keyed by position, as `Card.Actions` itself tells them apart (a label changes as photos are taken).
- `Partner/DocumentCovers` (portable, not exported) — the card's photos: one is a `Card.Cover`; more are a
- `Partner/DocumentCovers` (not exported) — the card's photos: one is a `Card.Cover`; more are a
Material 3 hero carousel (a horizontal `ScrollView`: `snapToInterval` on the phone, `pagingEnabled`'s CSS scroll
snap on the web; items `spacing.x2` apart, the next peeking `spacing.x14`, Material's 8 dp and 56 dp), or all whole
side by side where the measured width fits them at Material's largest large item (twice the cover's height, which
Expand All @@ -236,12 +232,12 @@ themed through `useTheme()` so a host's theme applies:
the safe-area insets; the internal `SheetHeader` with its `global.close`) on that page, with the document's sides
(the covers' labels) when there are two. testIDs: `<testID>-covers`, `-carousel`, `-cover-<i>`, `-viewer`,
`-viewer-header-close`, `-viewer-document`.
- `Partner/DocumentVersionList` (portable) — `item.versions` as `ListRow`s from `documentVersionRows`; they open
- `Partner/DocumentVersionList` — `item.versions` as `ListRow`s from `documentVersionRows`; they open
nothing, so no chevron. A row's description: when it was sent, the scan's catalogue label while the scan is not
`SCAN_STATUS.CLEAN` (pending, and partner 0.2.54's infected, never spelled here), the details code's label, and
`documentExpiresOn` («Expires Nov 23, 2026»): `expires_at` is a calendar day, formatted by `formatDateTime` in UTC
so no reader's zone moves it. `documentExpires` stays for the app's older list.
- `Partner/DocumentCaptureCard` (barrel only: the picker is native) — the card with the way to send it, as
- `Partner/DocumentCaptureCard` (native: the picker) — the card with the way to send it, as
`item.capture` says (`pages` 1, or 2 = the front then the back). Controlled: `{ item, subtitle?, pages = [],
onPagesChange(pages), onSend(), isSending = false, testID = 'document-requirement' }` — the host owns the pages
(the picker's assets, in order) and clears them only once its send succeeded, so a failed send keeps them; the
Expand Down Expand Up @@ -270,7 +266,7 @@ themed through `useTheme()` so a host's theme applies:
`documentExpiresOn`) live in `Translations/*.json`, in the catalogue's «Agregar»; the stories
(`Partner/DocumentRequirement.stories.js`) use the local circuit's real items, and render the capture card itself
with `pages` for the photo states.
- `Partner/viewModel.js` (barrel/portable: `PartnerViewModel`, because `statusLabel` is the Order one):
- `Partner/viewModel.js` (barrel: `PartnerViewModel`, because `statusLabel` is the Order one):
the key is the package's `statusLabelKey(group, value)` resolved with `localized`; a value outside the
vocabulary, or a key the registered catalogue lacks, renders the raw value. Each kind's group is read
from the package's `LABEL_GROUPS` (never spelled here). `TONE_BY_KIND` and `INTENT_PRESENTATION` stay
Expand All @@ -285,6 +281,11 @@ themed through `useTheme()` so a host's theme applies:
platform words there. A new partner component joins its `SCOPE`.
- Stories register the package catalogue (`registerFlatCatalog({ en: EN, es: ES })`), as a host does.

`Form.BusinessInfo`'s store address (0.5.5, owner 2026-11-07): while the form can be edited it is `AutoCompleteInput`
(Google's suggestions, as the driver's operating address: no GPS button, no «use my location» row), the picked
suggestion's `description` reported as `location` and its server errors listed under it (`FieldErrorText`). The
suggestions have no read-only state, so under `readOnly` or `isDisabled` the address stays the field it was.

Forms (C-25): `Form.PersonInfo`, `Form.VehicleInfo` and `Form.BusinessInfo` take `readOnly` and
`highlightFields: string[]` (the names the form reports to `inputActionHandler`), which outlines the field
in `primary` and adds a «Changed» helper line (colour alone is not a marker; on a disabled input, where Paper
Expand Down Expand Up @@ -320,13 +321,13 @@ does not render are ignored, and the forms' own required messages are unchanged.
makes, models }` (each `Array<{ value, label }>`, labelled by the host) plus `vehicleType`, `makeId`,
`modelId`, `licensePlateRegion` and `vin`, it renders the market schema in canon §9.15's order (type → year →
make → model, color, plate, plate region, optional VIN) with `Form/FormSelectField.js` (an outlined input that
opens a Paper `Menu`, portable). A make or model pick reports its id and its name (`makeId` + `make`); with no
opens a Paper `Menu`, web-safe). A make or model pick reports its id and its name (`makeId` + `make`); with no
`makes`/`models` (no catalogue slice for that type and year) they stay typed text. Without `catalog` the form is
the tree it always was, pinned by `legacyRendering.test.js` (`Form.VehicleInfo (vehicle form)`, captured from
`admin-app` @ 516446e).

`PhotoGalleryDisplay({ photoUrls, title?, emptyLabel?, highlighted?, size?, testID? })`
(`ImagePicker/PhotoGalleryDisplay.js`, barrel and portable): **resolved** URIs, never rewritten; a horizontal
(`ImagePicker/PhotoGalleryDisplay.js`): **resolved** URIs, never rewritten; a horizontal
strip of RN `Image`s, each labelled «Photo i of n» (`global.photoOf`); `global.noPhotos` when empty or all
blank; `title` defaults to `photos` (`null` hides it); `highlighted` adds the «Changed» line. testIDs:
`<testID>` (the strip), `<testID>.photo.<i>`, `<testID>.empty`; `testID` defaults to `photo-gallery`.
Expand Down Expand Up @@ -367,7 +368,7 @@ re-renders the existing consumers' props (CustomerApp's `drawerSideNav` and `Inv
## Generic UI for web hosts — 0.4.0-dev

The partner console's generic UI (`CustomerApp/admin-web/src/ui`) lives here now, for the console and the
AdminApp port alike. Every piece is in the barrel **and** `portable.js`, one folder per component, JS, themed
AdminApp port alike. Every piece is in the barrel, one folder per component, JS, themed
through `useTheme()` (a host theme's roles apply) and built on Paper components **as they are**: no hand-made
copy of a Paper component, even to work around a web accessibility quirk — those are recorded below as Paper
fork items. Labels come by props, with `global.*` defaults of this library's catalogue (never `partner.*`).
Expand Down Expand Up @@ -513,14 +514,13 @@ consumers must have this package inside their Metro/Babel transform path. Conseq
`@jmstechnologiesinc/react-native-paper`, `@react-navigation/elements`, `@jmstechnologiesinc/order`,
`@jmstechnologiesinc/order-narration` and `@jmstechnologiesinc/partner` — the last pinned **exactly**
(canon R4; also a devDependency), because the view model and its tests read its vocabulary, and
both the barrel and the portable entry import `Partner/viewModel`. The harness links the main checkout's
the barrel imports `Partner/viewModel`. The harness links the main checkout's
root `node_modules`, which does not carry it; in a worktree it is unpacked into
`packages/components/node_modules` (`npm pack @jmstechnologiesinc/partner@<the pin>` + extract), where Jest
resolves it with no `moduleNameMapper`. The barrel additionally expects the host to provide what the app
already has (`centrifuge`, `react-native-gesture-handler`, `react-native-reanimated`,
`react-native-vector-icons`, …); the portable entry needs only `react-native-safe-area-context`,
`react-native-vector-icons`, `color`, `@jmstechnologiesinc/commons`/`vendor`/`react-native-size-matters` and, on
the web, `i18next`, `i18next-browser-languagedetector` and `react-i18next`. All of them are now declared
`react-native-vector-icons`, …) and, on the web, `i18next`, `i18next-browser-languagedetector` and
`react-i18next`. All of them are now declared
as peers (C-35, 2026-10-03): every package `lib/` imports, at the range CustomerApp declares (so the main
host never conflicts). The commented-out `expo-blur` and `showcase-template` are not. `partner` is a peer
at **^0.2.33** (0.4.3, owner 2026-10-04: an exact pin refused every contract patch the app installs, B-8) and a
Expand Down
3 changes: 2 additions & 1 deletion packages/components/__tests__/components.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@ describe('el barril de componentes', () => {
});

it('sirve los nombres que sus consumidores importan', () => {
for (const name of ['List', 'Form', 'VendorList', 'CartList', 'styles']) {
// `ZOOM` and `useModalFocus`: the console's, which only `portable.js` served until 0.5.5.
for (const name of ['List', 'Form', 'VendorList', 'CartList', 'styles', 'ZOOM', 'useModalFocus']) {
expect(`${name}:${name in components}`).toBe(`${name}:true`);
}
});
Expand Down
Loading
Loading