@dloizides/ui-nav 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # 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.**
+An optional content-column cap (px), forwarded via `NavShell.topBar.contentMaxWidth`.
+When set, the OUTER `NavBar` container — which carries the bar background + bottom
+border (from `barTheme` / theme surface + any `containerStyle`, e.g. the AML
+radial-glow appbar) — stays FULL WIDTH (full-bleed), while the INNER row (brand +
+links + right) is capped to `contentMaxWidth` and centred. This restores the v1-console
+`.ui-appbar` (full-bleed) + `.ui-appbar-inner { max-width; margin: 0 auto }` shape:
+previously an app had to put the cap on the container's `containerStyle`, which also
+capped the dark background and left light gutters on wide viewports. Omit it and the
+inner spans the full container (unchanged — byte-identical to before). The priority+
+overflow "…" fit measures the capped inner's rendered width, so it keeps working
+against the content column, not the full-bleed container. Purely additive.
+
 ## 1.8.0
 
 The navigation shell becomes the ONE shell for every portal: a first-class

package/README.md

@@ -126,6 +126,7 @@ import { NavShell, type NavItem } from '@dloizides/ui-nav';
     right: <><LanguageSwitcher /><UserChip /></>,
     overflowLabel: FM('menu.more'),
     barTheme: darkChromeTheme,          // optional: dark bar over a light page
+    contentMaxWidth: 1180,              // optional: full-bleed bar, inner capped + centred
   }}
   sideRail={{
     items: sectionItems,                // side sections (leaf + expandable)
@@ -169,6 +170,19 @@ are re-passed so labels keep localizing; every colour still flows through the th
 (style-only). Custom appbar backgrounds (e.g. a radial-glow gradient) stay
 expressible via `containerStyle`.
 
+### Full-bleed bar with a centred content column (`NavBar.contentMaxWidth`)
+
+Pass `contentMaxWidth` (px) — via `NavBar.contentMaxWidth` or
+`NavShell.topBar.contentMaxWidth` — to make the bar **full-bleed** while its content
+stays in a centred column. The OUTER container (which carries the bar background +
+bottom border from `barTheme` / theme surface + any `containerStyle`, e.g. AML's
+radial-glow appbar) spans the full viewport width; the INNER row (brand + links +
+right) is capped to `contentMaxWidth` and centred — the v1-console `.ui-appbar`
+(full-bleed) + `.ui-appbar-inner { max-width; margin: 0 auto }` shape. Omit it and
+the inner spans the full container (unchanged). The priority+ overflow "…" fit
+measures the capped inner's rendered width, so it keeps working against the content
+column, not the full-bleed container.
+
 ### Cross-navigation pills (`PillNav`)
 
 A row of fully-rounded pills from a `NavItem[]` — kefi's coral dashboard switcher.

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;
@@ -210,6 +228,16 @@ interface NavBarProps {
     overflowHint?: string;
     /** Extra container style overrides. */
     containerStyle?: ViewStyle | ViewStyle[];
+    /**
+     * Optional content-column cap (px). When set, the OUTER container — which carries
+     * the background + bottom border (`barTheme`/theme surface + any `containerStyle`,
+     * e.g. the AML radial-glow appbar) — stays FULL WIDTH (full-bleed), while the INNER
+     * row (brand + links + right) is capped to this width and centred. Omit for the
+     * default where the inner spans the full container. The priority+ overflow "…" fit
+     * measures the (now capped) inner's rendered width via `onLayout`, so it keeps
+     * working against the capped column, not the full-bleed container.
+     */
+    contentMaxWidth?: number;
     /**
      * Optional CHROME theme override — re-provisions the `@dloizides/ui-feedback`
      * theme for the bar ONLY, so the top bar can be dark while the page below keeps
@@ -508,6 +536,13 @@ interface NavShellTopBar {
      * `ViewStyle`, the AML radial-glow appbar). Style-only.
      */
     containerStyle?: ViewStyle | ViewStyle[];
+    /**
+     * Optional content-column cap (px) for the top bar. When set, the bar's
+     * background + bottom border (from `containerStyle` / `barTheme`) stay FULL WIDTH
+     * (full-bleed) while the inner brand + links + right row is capped to this width
+     * and centred — the AML v1-console appbar shape. Forwarded to `NavBar.contentMaxWidth`.
+     */
+    contentMaxWidth?: number;
     /**
      * Optional CHROME theme override for the top bar only (dark bar over a light
      * page). Forwarded to `NavBar.barTheme`. Style-only — see `NavBar`.
@@ -574,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;
@@ -210,6 +228,16 @@ interface NavBarProps {
     overflowHint?: string;
     /** Extra container style overrides. */
     containerStyle?: ViewStyle | ViewStyle[];
+    /**
+     * Optional content-column cap (px). When set, the OUTER container — which carries
+     * the background + bottom border (`barTheme`/theme surface + any `containerStyle`,
+     * e.g. the AML radial-glow appbar) — stays FULL WIDTH (full-bleed), while the INNER
+     * row (brand + links + right) is capped to this width and centred. Omit for the
+     * default where the inner spans the full container. The priority+ overflow "…" fit
+     * measures the (now capped) inner's rendered width via `onLayout`, so it keeps
+     * working against the capped column, not the full-bleed container.
+     */
+    contentMaxWidth?: number;
     /**
      * Optional CHROME theme override — re-provisions the `@dloizides/ui-feedback`
      * theme for the bar ONLY, so the top bar can be dark while the page below keeps
@@ -508,6 +536,13 @@ interface NavShellTopBar {
      * `ViewStyle`, the AML radial-glow appbar). Style-only.
      */
     containerStyle?: ViewStyle | ViewStyle[];
+    /**
+     * Optional content-column cap (px) for the top bar. When set, the bar's
+     * background + bottom border (from `containerStyle` / `barTheme`) stay FULL WIDTH
+     * (full-bleed) while the inner brand + links + right row is capped to this width
+     * and centred — the AML v1-console appbar shape. Forwarded to `NavBar.contentMaxWidth`.
+     */
+    contentMaxWidth?: number;
     /**
      * Optional CHROME theme override for the top bar only (dark bar over a light
      * page). Forwarded to `NavBar.barTheme`. Style-only — see `NavBar`.
@@ -574,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 })
               }
@@ -806,7 +807,8 @@ var NavBarInner = ({
   collapseBelow = DEFAULT_COLLAPSE_BELOW,
   overflowLabel = "More",
   overflowHint = "",
-  containerStyle
+  containerStyle,
+  contentMaxWidth
 }) => {
   const { theme } = uiFeedback.useUi();
   const colors = theme.colors;
@@ -818,6 +820,10 @@ var NavBarInner = ({
   const { visibleCount, setAvailableWidth, setItemWidth, setMoreWidth } = useNavOverflow(items.length, NAV_LINK_GAP);
   const collapsed = width < collapseBelow;
   const showLinks = !collapsed || open;
+  const innerCapStyle = React5.useMemo(
+    () => contentMaxWidth === void 0 ? null : { maxWidth: contentMaxWidth, width: "100%", alignSelf: "center" },
+    [contentMaxWidth]
+  );
   const toggleMenu = React5.useCallback(() => setOpen((v) => !v), []);
   const handlePress = React5.useCallback(
     (route) => {
@@ -847,7 +853,7 @@ var NavBarInner = ({
         { backgroundColor: colors.surface, borderBottomColor: colors.border },
         containerStyle
       ],
-      children: /* @__PURE__ */ jsxRuntime.jsxs(reactNative.View, { style: [navBarStyles.inner, collapsed ? null : navBarStyles.innerNoWrap], children: [
+      children: /* @__PURE__ */ jsxRuntime.jsxs(reactNative.View, { style: [navBarStyles.inner, collapsed ? null : navBarStyles.innerNoWrap, innerCapStyle], children: [
         brand !== void 0 ? /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { style: navBarStyles.brand, children: brand }) : null,
         collapsed ? /* @__PURE__ */ jsxRuntime.jsx(
           reactNative.Pressable,
@@ -1236,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;
@@ -1256,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,
@@ -1265,6 +1271,7 @@ var NavShell = ({
       brand: topBar.brand,
       collapseBelow: topBar.collapseBelow,
       containerStyle: topBar.containerStyle,
+      contentMaxWidth: topBar.contentMaxWidth,
       items: topBar.items,
       menuHint: topBar.menuHint,
       menuLabel: topBar.menuLabel,