@peektravel/app-utilities 0.7.2 → 0.7.4

package/dist/ui/odyssey.css

@@ -9,6 +9,36 @@
  * dependency-free.
  */
 
+/* ---- unupgraded-element guard (FOUC) ------------------------------------- */
+/*
+ * Hide each <ody-*> element until its definition upgrades it, so it never
+ * flashes as its raw text content (an un-upgraded `<ody-button>Save</ody-button>`
+ * would otherwise render the bare word "Save"). `visibility` (not `display`)
+ * preserves layout, so there is no reflow when the element upgrades; wrapping
+ * the tags in `:where` keeps specificity at zero so a consumer can override
+ * trivially. If the
+ * registration bundle never loads, elements stay hidden rather than showing raw
+ * text. This selector list is kept in sync with the component registry by the
+ * `defined-guard` drift test — add any new tag here when you register it.
+ */
+:where(
+  ody-accordion, ody-alert, ody-app-page-container, ody-brand-icon, ody-breadcrumb,
+  ody-breadcrumb-item, ody-button, ody-card, ody-check-in-status, ody-checkbox,
+  ody-checkbox-group, ody-collapsible, ody-collapsible-collapsed, ody-collapsible-content,
+  ody-collapsible-section, ody-copy-button, ody-datepicker, ody-divider, ody-dropdown-multi,
+  ody-dropdown-single, ody-empty-state, ody-horizontal-divider, ody-icon, ody-inline-input,
+  ody-inline-list, ody-inline-list-item, ody-input, ody-list-item, ody-loading-bar,
+  ody-loading-spinner, ody-message, ody-modal, ody-money-input, ody-option, ody-page-container,
+  ody-panel, ody-percentage-input, ody-popover, ody-product-indicator, ody-radio-button-group,
+  ody-search-input, ody-section-column-item, ody-section-columns, ody-section-row-item,
+  ody-section-rows, ody-split-button, ody-stat, ody-stat-detail, ody-stat-summary,
+  ody-stat-summary-detail, ody-status-dot, ody-table, ody-table-header, ody-tabs, ody-tag,
+  ody-toast-host, ody-toggle-button, ody-tooltip, ody-two-column, ody-two-column-main,
+  ody-two-column-secondary, ody-two-column-secondary-header
+):not(:defined) {
+  visibility: hidden;
+}
+
 /* ---- base ---------------------------------------------------------------- */
 ody-icon, ody-button, ody-tag, ody-alert, ody-card, ody-divider, ody-horizontal-divider,
 ody-status-dot, ody-message, ody-loading-spinner, ody-loading-bar {

package/docs/ui.md

@@ -40,6 +40,33 @@ CSS can also be linked instead of imported:
 <link rel="stylesheet" href="…/@peektravel/app-utilities/ui/odyssey.css" />
 ```
 
+Registration is **idempotent** — importing the module more than once (or from
+more than one bundle) re-registers nothing and never throws, so lazy or
+duplicated imports are safe.
+
+If you register the bundle **lazily** (e.g. a dynamic `import()` to dodge SSR /
+hydration mismatches), two things stop un-upgraded elements from flashing as
+their raw text content (`<ody-button>Save</ody-button>` briefly showing the bare
+word "Save"):
+
+- `odyssey.css` ships a `:not(:defined) { visibility: hidden }` guard, so every
+  `<ody-*>` stays invisible — layout preserved, no reflow — until it upgrades.
+  Load the CSS **eagerly** so this applies before first paint. It has zero
+  specificity, so you can override it for a deliberate fallback.
+- `whenOdysseyReady()` resolves once every imported element has upgraded, so you
+  can gate your first render on it:
+
+  ```ts
+  import { whenOdysseyReady } from '@peektravel/app-utilities/ui';
+  await whenOdysseyReady();
+  // …now render your <ody-*> tree
+  ```
+
+  A *failed* dynamic import rejects at the `import()` call site — handle load
+  failures there; `whenOdysseyReady()` reflects only the elements that did
+  register. `registeredTags()` returns the registered tag list if you need to
+  introspect it.
+
 Named exports for advanced use:
 
 ```ts

package/docs/webhooks.md

@@ -265,9 +265,10 @@ The **JSON body is the source of the event data**; the fields it shares with the
 token (`installId`, `accountId`, `status`, `displayVersion`, `user`) fall back to
 the **verified token** when the body omits them. The token authenticates the
 whole delivery — only Peek can mint a valid one — so the body is trusted within a
-verified request. Unlike `verifyPeekAuthToken`, `user` is nullable: install
-lifecycle events are often system-initiated (no acting user), so the parser
-tolerates a missing `modified_by`/`user`.
+verified request. `user` is nullable here — as it is on `verifyPeekAuthToken` —
+because install lifecycle events are often system-initiated (no acting user), so
+the parser tolerates a missing `modified_by`/`user`, and every field inside a
+present `user` is itself nullable (a sentinel `""`/`"null"` id becomes `null`).
 
 > **Migrating from `verifyInstallWebhook` / `parseInstallEvent`?**
 > `verifyInstallWebhook(token, secret)` still works but is `@deprecated` — it

package/llms.txt

@@ -169,10 +169,11 @@ stay internal.
   418/429 with no GraphQL `errors` — e.g. 401/404/5xx; carries `.statusCode`,
   `.url`, and raw `.body`; surfaced before JSON parsing so non-JSON error pages
   keep their status), `PiiAccessDisabledError` (a payment/booking-modification op
-  was called without `fullCustomerAccess`), `InvalidPeekTokenError` (a
-  signature-valid `app_registry_v2` token whose `user` block has no `id`;
-  carries `.field`), and the REST-sibling `CngApiError` / `AcmeApiError` — all
-  importable; branch with `instanceof`.
+  was called without `fullCustomerAccess`), and the REST-sibling `CngApiError` /
+  `AcmeApiError` — all importable; branch with `instanceof`. Token claim
+  extraction never throws once the signature verifies: a missing `user` block
+  gives `user: null`, and each user field (including `id`, the person's own id —
+  not an account/partner id) is nullable, with `""`/`"null"` normalized to `null`.
 - Plain `Error` for validation/precondition failures thrown before any request.
 
 ## Webhooks (booking + waiver + install)
@@ -249,6 +250,13 @@ effect; read-only state props (`isOpen`/`isVisible`) ignore the write (drive the
 via a `ref`'s imperative methods). No `only a getter` crash. TS still types them
 read-only — the setters are a runtime safety net.
 
+Registration is idempotent (importing twice never throws). Lazy registration:
+`odyssey.css` ships a `:not(:defined){visibility:hidden}` guard so un-upgraded
+`<ody-*>` never flash as raw text (load the CSS eagerly), and `whenOdysseyReady()`
+(`Promise<void>`) resolves once every imported element has upgraded — gate first
+render on it. `registeredTags()` returns the registered tag list. A failed
+dynamic import rejects at the `import()` call site.
+
 Tags by tier (see `docs/ui.md` for attributes/events/examples per component):
 - display: `ody-button`, `ody-tag`, `ody-alert`, `ody-card`, `ody-horizontal-divider`
   (1px rule with a default `margin-block: var(--gap16)`; `spacing="tight"|"none"`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peektravel/app-utilities",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "GraphQL JS mapping utilities extracted from the Peek Pro Autopilot connector.",
   "license": "MIT",
   "repository": {