@dloizides/ui-nav 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 1.10.0
+
+- **Fix (`layout` was not authoritative — `layout="side"` rendered a top bar anyway).**
+  `wantsTopBar` carried an extra `(layout === 'side' && hasTopBar)` clause, so passing a
+  `topBar` **config** with `layout="side"` mounted the bar regardless — making `'side'` and
+  `'both'` render **pixel-identically** and `layout` unobservable. `layout` now decides which
+  REGIONS exist; `topBar` is only the CONTENT of the top region. A `'side'` app that also wants
+  a bar asks for `layout="both"`, which is what that combination always meant.
+  - Found by `apps/ui-showcase`, which renders every orientation side by side — a product app
+    picks ONE orientation and never sees the other, which is why this survived to 1.9.0.
+  - **Not breaking in this fleet:** no app passed `layout="side"` + `topBar`. The four `'side'`
+    portals (erevna, katalogos, zygos, agora) pass a `header` NODE, not a `topBar` config.
+  - The `hasHeader` clause is **deliberately kept**: `header` is the documented escape hatch by
+    which a `'side'` app supplies its own ready-made header (the structured `Topbar` with
+    language / notification / user slots). It is an explicit "render THIS node", not a config
+    whose presence is silently read as an orientation change.
+- **a11y: `AccountState.accountHint`** — the account-name button's `accessibilityHint` was
+  hardcoded to `displayName`, byte-identical to its `accessibilityLabel`, so a screen reader
+  announced the name twice and never said what pressing it does — and the consumer had no way
+  to correct it. The sibling `upgrade?: TopbarAction` on the same interface has always carried
+  a `hint`; this closes that inconsistency. Falls back to `displayName`, so existing callers
+  are unaffected.
+- **a11y: `AccountState.accountTestID`** — the account-name button's testID was hardcoded, with
+  no override, unlike `TopbarAction.testID?` / `NavItem.testID?` elsewhere in the package.
+- **a11y: `Topbar.language.testID`** — the inline `language` prop type declared no `testID`, so
+  the repo's testID+label+hint standard was **structurally unsatisfiable** for that one button
+  while every other Topbar action (all `TopbarAction`) accepted one.
+
+> Note for consumers: this react-native-web build does **not** forward `accessibilityHint` to
+> the DOM at all — rendered buttons carry `aria-label` but no hint attribute. The hint is a
+> NATIVE-only guarantee today. That is pre-existing and unchanged here, but it means DOM-level
+> tests cannot distinguish a threaded hint from a dropped one; `topbarA11y.test.tsx` therefore
+> pins the prop threading directly.
+
 ## 1.9.0
 
 **`NavBar.contentMaxWidth` — a full-bleed bar with a centred content column.**

package/dist/index.d.mts

@@ -120,16 +120,34 @@ interface AccountState {
     plan?: AccountPlan;
     onLogout: () => void;
     onAccount?: () => void;
+    /**
+     * a11y hint for the account-name button (what pressing it DOES).
+     *
+     * Without this the hint fell back to `displayName` — byte-identical to the
+     * accessibility LABEL, so a screen reader announced the name twice and never
+     * said where the button goes. The sibling `upgrade?: TopbarAction` on this very
+     * interface has always carried a `hint`; this closes that inconsistency. The
+     * `displayName` fallback is retained so existing callers are unaffected.
+     */
+    accountHint?: string;
+    /** testID for the account-name button. Defaults to `NAV_TEST_IDS.accountName`. */
+    accountTestID?: string;
     upgrade?: TopbarAction;
 }
 interface TopbarProps {
     /** Left slot — typically the tenant logo. */
     left?: React.ReactNode;
-    /** Optional language toggle. */
+    /**
+     * Optional language toggle. `testID` is optional but the repo standard wants
+     * one — before 1.10.0 this inline type declared none, so a testID was
+     * structurally unreachable for this button while every other Topbar action
+     * (which use `TopbarAction`) accepted one.
+     */
     language?: {
         label: string;
         hint: string;
         onPress: () => void;
+        testID?: string;
     };
     /** Optional notification slot (e.g. a notification bell). */
     notificationSlot?: React.ReactNode;
@@ -591,8 +609,9 @@ interface NavShellProps extends ForwardedShellProps {
     navigateHint?: (label: string) => string;
     /**
      * Top-bar config → a `NavBar` in the header slot. Required for `'top'` /
-     * `'both'`; ignored for `'side'` unless supplied (a `'side'` app may still pass
-     * a `topBar` with empty `items` for its brand + user header).
+     * `'both'`; **ignored for `'side'`** — `layout` decides which regions exist, so
+     * a `'side'` app that also wants a bar asks for `layout="both"`. A `'side'` app
+     * that wants its OWN header node uses the `header` escape hatch instead.
      */
     topBar?: NavShellTopBar;
     /**

package/dist/index.d.ts

@@ -120,16 +120,34 @@ interface AccountState {
     plan?: AccountPlan;
     onLogout: () => void;
     onAccount?: () => void;
+    /**
+     * a11y hint for the account-name button (what pressing it DOES).
+     *
+     * Without this the hint fell back to `displayName` — byte-identical to the
+     * accessibility LABEL, so a screen reader announced the name twice and never
+     * said where the button goes. The sibling `upgrade?: TopbarAction` on this very
+     * interface has always carried a `hint`; this closes that inconsistency. The
+     * `displayName` fallback is retained so existing callers are unaffected.
+     */
+    accountHint?: string;
+    /** testID for the account-name button. Defaults to `NAV_TEST_IDS.accountName`. */
+    accountTestID?: string;
     upgrade?: TopbarAction;
 }
 interface TopbarProps {
     /** Left slot — typically the tenant logo. */
     left?: React.ReactNode;
-    /** Optional language toggle. */
+    /**
+     * Optional language toggle. `testID` is optional but the repo standard wants
+     * one — before 1.10.0 this inline type declared none, so a testID was
+     * structurally unreachable for this button while every other Topbar action
+     * (which use `TopbarAction`) accepted one.
+     */
     language?: {
         label: string;
         hint: string;
         onPress: () => void;
+        testID?: string;
     };
     /** Optional notification slot (e.g. a notification bell). */
     notificationSlot?: React.ReactNode;
@@ -591,8 +609,9 @@ interface NavShellProps extends ForwardedShellProps {
     navigateHint?: (label: string) => string;
     /**
      * Top-bar config → a `NavBar` in the header slot. Required for `'top'` /
-     * `'both'`; ignored for `'side'` unless supplied (a `'side'` app may still pass
-     * a `topBar` with empty `items` for its brand + user header).
+     * `'both'`; **ignored for `'side'`** — `layout` decides which regions exist, so
+     * a `'side'` app that also wants a bar asks for `layout="both"`. A `'side'` app
+     * that wants its OWN header node uses the `header` escape hatch instead.
      */
     topBar?: NavShellTopBar;
     /**

package/dist/index.js

@@ -540,6 +540,7 @@ var Topbar = ({
               accessibilityLabel: language.label,
               ringColor: primaryColor,
               style: navStyles.topbarRowItem,
+              testID: language.testID,
               onPress: language.onPress,
               children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.Text, { style: [navStyles.topbarLabel, { color: colors.text }], children: language.label })
             }
@@ -553,10 +554,10 @@ var Topbar = ({
             richAccount.onAccount ? /* @__PURE__ */ jsxRuntime.jsx(
               FocusableTouchable,
               {
-                accessibilityHint: richAccount.displayName,
+                accessibilityHint: richAccount.accountHint ?? richAccount.displayName,
                 accessibilityLabel: richAccount.displayName,
                 ringColor: primaryColor,
-                testID: NAV_TEST_IDS.accountName,
+                testID: richAccount.accountTestID ?? NAV_TEST_IDS.accountName,
                 onPress: richAccount.onAccount,
                 children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.Text, { style: [navStyles.userName, { color: colors.text }], children: richAccount.displayName })
               }
@@ -1241,8 +1242,8 @@ var CollapsedRail = ({
     }
   );
 };
-function wantsTopBar(layout, hasHeader, hasTopBar) {
-  return layout === "top" || layout === "both" || hasHeader || layout === "side" && hasTopBar;
+function wantsTopBar(layout, hasHeader) {
+  return layout === "top" || layout === "both" || hasHeader;
 }
 function wantsSideRail(layout, hasSideRail) {
   return (layout === "side" || layout === "both") && hasSideRail;
@@ -1261,7 +1262,7 @@ var NavShell = ({
   collapsedRailRange: collapsedRailRangeProp,
   ...shellProps
 }) => {
-  const showTopBar = wantsTopBar(layout, header !== void 0, topBar !== void 0);
+  const showTopBar = wantsTopBar(layout, header !== void 0);
   const showSideRail = wantsSideRail(layout, sideRail !== void 0);
   const headerNode = header !== void 0 ? header : showTopBar && topBar !== void 0 ? /* @__PURE__ */ jsxRuntime.jsx(
     NavBar,