@peektravel/app-utilities 0.7.3 → 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/llms.txt

@@ -250,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.3",
+  "version": "0.7.4",
   "description": "GraphQL JS mapping utilities extracted from the Peek Pro Autopilot connector.",
   "license": "MIT",
   "repository": {