@apliteni/apliteni-ui 0.125.1 → 0.126.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.125.1",
+  "version": "0.126.0",
   "workspaces": [
     "react"
   ],

package/react/README.md

@@ -910,3 +910,63 @@ instead of 32, with the same line drawn in the middle of it.
     { label: 'Closing', kind: 'total' },
   ]} />
 ```
+
+## NavTabs and Breadcrumbs
+
+`NavTabs` renders route links with the kit’s underline or pill presentation. Pass
+unique item IDs and set `active` to the current route’s ID. The current link has
+`aria-current="page"`; disabled items are text outside the Tab order. Optional
+badges accept text, numbers (including zero), or `{ text, tone }`.
+
+```tsx
+<NavTabs aria-label="Finance views" active="payouts" items={[
+  { id: 'summary', label: 'Summary', href: '/finance' },
+  { id: 'payouts', label: 'Payouts', href: '/payouts', badge: 3 },
+  { id: 'exports', label: 'Exports', disabled: true },
+]} />
+<Breadcrumbs items={[
+  { label: 'Finance', href: '/finance' },
+  { label: 'Payouts', href: '/payouts' },
+  { label: 'PY-4821' },
+]} />
+```
+
+Use `Tabs` for panels within a page. `NavTabs` keeps normal link keyboard behavior.
+An omitted `href` falls back to `#` plus the item ID. `variant="pill"` selects the
+existing pill styles. A badge of `null` renders no badge, so a count that is not in
+yet costs nothing to pass.
+
+Both components take `renderLink`, the prop `AppShell` already uses, so a router
+handles the navigation instead of the browser reloading the document:
+
+```tsx
+<NavTabs active="payouts" items={items}
+  renderLink={(item, { href, children, ...props }) => (
+    <Link {...props} to={href!}>{children}</Link>
+  )} />
+```
+
+Without it both render a plain `<a>`. The kit's class, destination, current state
+and children all arrive in `linkProps`, so pass them through rather than rebuilding
+them.
+
+`Breadcrumbs` renders an ordered trail. Earlier items link only when they have an
+`href`; the final item is always current-page text. Items accept a decorative kit
+`icon` name. Both components accept native navigation attributes and a forwarded
+root ref. Use `aria-label` to distinguish navigation landmarks. Link items accept
+`target`. Script, data, and VBScript destinations fall back to `#`.
+
+Tab rows scroll within their container when the links do not fit; a breadcrumb
+trail wraps instead. A row whose links do fit scrolls nothing and clips nothing, so
+a focus ring in it keeps its complete band. The current route is revealed after
+mounting and route changes. Content and container changes update the fit state
+without revealing the route again, so they preserve the reader's scroll position
+where space permits. Keyboard focus stays put throughout.
+When a link already fits in the row, it keeps its content width. The cap only
+limits one link that is wider than the row.
+
+A row also scrolls to a link that takes focus, far enough that the ring the link
+draws clears the scrolling edge rather than being cut off by it. `NavTabs` does
+that from `onFocus`, and still calls an `onFocus` you pass. A row whose links are
+all disabled holds no Tab stop, so the browser makes the row itself one; it draws
+the kit's inward ring there, never the browser's own outline.

package/react/dist/index.d.ts

@@ -1071,7 +1071,51 @@ declare const AccentPicker: react.ForwardRefExoticComponent<Omit<HTMLAttributes<
     options?: readonly Accent[];
 } & react.RefAttributes<HTMLDivElement>>;
 
+type NavTabBadge = string | number | {
+    text: string | number;
+    tone?: 'neutral' | 'accent' | 'live' | 'danger';
+};
+type NavTabItem = {
+    id: string;
+    label: string;
+    href?: string;
+    target?: string;
+    disabled?: boolean;
+    badge?: NavTabBadge | null;
+};
+type NavTabsProps = Omit<ComponentPropsWithoutRef<'nav'>, 'children'> & {
+    items: readonly NavTabItem[];
+    active?: string;
+    variant?: 'underline' | 'pill';
+    /** Spread linkProps onto the router link, including children. */
+    renderLink?: (item: NavTabItem, linkProps: ComponentPropsWithoutRef<'a'>) => ReactNode;
+};
+declare const NavTabs: react.ForwardRefExoticComponent<Omit<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLElement>, HTMLElement>, "ref">, "children"> & {
+    items: readonly NavTabItem[];
+    active?: string;
+    variant?: "underline" | "pill";
+    /** Spread linkProps onto the router link, including children. */
+    renderLink?: (item: NavTabItem, linkProps: ComponentPropsWithoutRef<"a">) => ReactNode;
+} & react.RefAttributes<HTMLElement>>;
+
+type BreadcrumbItem = {
+    label: string;
+    href?: string;
+    target?: string;
+    icon?: string;
+};
+type BreadcrumbsProps = Omit<ComponentPropsWithoutRef<'nav'>, 'children'> & {
+    items: readonly BreadcrumbItem[];
+    /** Spread linkProps onto the router link, including children. */
+    renderLink?: (item: BreadcrumbItem, linkProps: ComponentPropsWithoutRef<'a'>) => ReactNode;
+};
+declare const Breadcrumbs: react.ForwardRefExoticComponent<Omit<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLElement>, HTMLElement>, "ref">, "children"> & {
+    items: readonly BreadcrumbItem[];
+    /** Spread linkProps onto the router link, including children. */
+    renderLink?: (item: BreadcrumbItem, linkProps: ComponentPropsWithoutRef<"a">) => ReactNode;
+} & react.RefAttributes<HTMLElement>>;
+
 declare const PAGE_SIZES: readonly number[];
 declare const DEFAULT_PAGE_SIZE: number;
 
-export { type Accent, AccentPicker, type AccentPickerProps, type AddFilter, AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonLinkProps, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, Chart, type ChartBridgeStep, type ChartBridgeTones, type ChartPeriod, type ChartProps, type ChartSeries, type ChartTone, CheckList, type CheckListProps, Checkbox, type CheckboxProps, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DatePicker, type DatePickerMode, type DatePickerPreset, type DatePickerProps, type DatePickerRange, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, Field, type FieldControlProps, type FieldProps, FileDrop, type FileDropFile, type FileDropProps, type FileDropStatus, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, type NativeButtonProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, Pill, type PillProps, RowIdentity, type RowIdentityProps, SearchField, type SearchFieldProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, SidebarNav, type SidebarNavBadge, type SidebarNavItem, type SidebarNavLeaf, type SidebarNavProps, type SidebarNavSection, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, StatusDot, type StatusDotProps, Success, SuccessCheck, type SuccessCheckProps, type SuccessCountdown, SuccessPanel, type SuccessPanelProps, type SuccessProps, Switch, type SwitchProps, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineEventKind, type TimelineProps, Toast, type ToastNotice, type ToastProps, Tooltip, type TooltipProps, sortTableRows, useToast };
+export { type Accent, AccentPicker, type AccentPickerProps, type AddFilter, AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, type BreadcrumbItem, Breadcrumbs, type BreadcrumbsProps, BusyRegion, type BusyRegionProps, Button, type ButtonLinkProps, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, Chart, type ChartBridgeStep, type ChartBridgeTones, type ChartPeriod, type ChartProps, type ChartSeries, type ChartTone, CheckList, type CheckListProps, Checkbox, type CheckboxProps, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DatePicker, type DatePickerMode, type DatePickerPreset, type DatePickerProps, type DatePickerRange, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, Field, type FieldControlProps, type FieldProps, FileDrop, type FileDropFile, type FileDropProps, type FileDropStatus, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, type NativeButtonProps, type NavTabBadge, type NavTabItem, NavTabs, type NavTabsProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, Pill, type PillProps, RowIdentity, type RowIdentityProps, SearchField, type SearchFieldProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, SidebarNav, type SidebarNavBadge, type SidebarNavItem, type SidebarNavLeaf, type SidebarNavProps, type SidebarNavSection, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, StatusDot, type StatusDotProps, Success, SuccessCheck, type SuccessCheckProps, type SuccessCountdown, SuccessPanel, type SuccessPanelProps, type SuccessProps, Switch, type SwitchProps, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineEventKind, type TimelineProps, Toast, type ToastNotice, type ToastProps, Tooltip, type TooltipProps, sortTableRows, useToast };

package/react/dist/index.js

@@ -94,7 +94,7 @@ var cx = (...a) => a.filter(Boolean).join(" ");
 var Button = forwardRef3(function Button2({
   variant = "secondary",
   size = "md",
-  icon: icon6,
+  icon: icon7,
   leading,
   iconRight,
   iconOnly,
@@ -158,7 +158,7 @@ var Button = forwardRef3(function Button2({
     className
   );
   const labelled = rest["aria-label"] != null || rest["aria-labelledby"] != null;
-  const fallback = typeof children === "string" && children.trim() ? children.trim() : icon6;
+  const fallback = typeof children === "string" && children.trim() ? children.trim() : icon7;
   const named = iconOnly && !labelled && fallback ? { "aria-label": fallback, title: rest.title ?? fallback } : {};
   const Root = href === void 0 ? "button" : "a";
   return /* @__PURE__ */ jsxs3(
@@ -203,7 +203,7 @@ var Button = forwardRef3(function Button2({
         if (!blockKey(event)) onKeyUp?.(event);
       },
       children: [
-        leading != null ? /* @__PURE__ */ jsx4("span", { "aria-hidden": "true", style: { display: "inline-flex" }, children: leading }) : icon6 && /* @__PURE__ */ jsx4(Icon, { name: icon6 }),
+        leading != null ? /* @__PURE__ */ jsx4("span", { "aria-hidden": "true", style: { display: "inline-flex" }, children: leading }) : icon7 && /* @__PURE__ */ jsx4(Icon, { name: icon7 }),
         !iconOnly && renderedChildren != null && /* @__PURE__ */ jsx4("span", { className: "ui-btn__label-slot", children: /* @__PURE__ */ jsx4("span", { className: "ui-btn__label", ref: labelRef, children: renderedChildren }) }),
         iconRight && /* @__PURE__ */ jsx4(Icon, { name: iconRight }),
         busy && /* @__PURE__ */ jsxs3("span", { className: "ui-btn__dots", "aria-hidden": "true", children: [
@@ -273,9 +273,9 @@ function Card({ title, sub, level = 2, className, children }) {
 // src/primitives/Callout.tsx
 import { calloutIcons, icon as kitIcon } from "@apliteni/apliteni-ui";
 import { jsx as jsx9, jsxs as jsxs5 } from "react/jsx-runtime";
-function Callout({ variant, icon: icon6 = calloutIcons[variant ?? "neutral"], children, actions }) {
+function Callout({ variant, icon: icon7 = calloutIcons[variant ?? "neutral"], children, actions }) {
   return /* @__PURE__ */ jsxs5("div", { className: `ui-callout${variant && variant !== "neutral" ? ` ui-callout--${variant}` : ""}`, role: variant === "danger" ? "alert" : void 0, children: [
-    /* @__PURE__ */ jsx9("span", { className: "ui-callout__icon", dangerouslySetInnerHTML: { __html: kitIcon(icon6) } }),
+    /* @__PURE__ */ jsx9("span", { className: "ui-callout__icon", dangerouslySetInnerHTML: { __html: kitIcon(icon7) } }),
     /* @__PURE__ */ jsxs5("div", { className: "ui-callout__body", children: [
       children,
       actions != null && /* @__PURE__ */ jsx9("div", { className: "ui-toolbar ui-callout__actions", children: actions })
@@ -1581,12 +1581,12 @@ function Denied({
   title = "You don\u2019t have access",
   sub,
   need,
-  icon: icon6 = "lock",
+  icon: icon7 = "lock",
   className,
   children
 }) {
   return /* @__PURE__ */ jsxs14("div", { className: cx4("ui-denied", className), children: [
-    /* @__PURE__ */ jsx18("div", { className: "ui-denied__seal", children: /* @__PURE__ */ jsx18(Icon, { name: icon6 }) }),
+    /* @__PURE__ */ jsx18("div", { className: "ui-denied__seal", children: /* @__PURE__ */ jsx18(Icon, { name: icon7 }) }),
     /* @__PURE__ */ jsx18("div", { className: "ui-denied__title", children: title }),
     sub && /* @__PURE__ */ jsx18("div", { className: "ui-denied__sub", children: sub }),
     need && /* @__PURE__ */ jsxs14("div", { className: "ui-denied__need", children: [
@@ -3903,11 +3903,11 @@ var cases = {
   "not-found": { title: "We can't find that page", sub: "Check the address or return to the home page.", icon: "folder" },
   "not-yet-built": { title: "This ships later", sub: "This screen is not available yet. Check back later.", icon: "clock" }
 };
-function EmptyState({ variant = "first-run", title, sub, icon: icon6, art, actions }) {
+function EmptyState({ variant = "first-run", title, sub, icon: icon7, art, actions }) {
   const preset = cases[variant];
   const heading = title ?? preset.title;
   const guidance = sub ?? preset.sub;
-  const glyph = icon6 ?? preset.icon;
+  const glyph = icon7 ?? preset.icon;
   return /* @__PURE__ */ jsxs31("div", { className: "ui-empty", children: [
     art ? typeof art === "string" ? /* @__PURE__ */ jsx36("div", { className: "ui-empty__art", dangerouslySetInnerHTML: { __html: /<svg/.test(art) ? art : illo(art) } }) : /* @__PURE__ */ jsx36("div", { className: "ui-empty__art", "aria-hidden": "true", children: art }) : glyph ? /* @__PURE__ */ jsx36("div", { className: "ui-empty__icon", dangerouslySetInnerHTML: { __html: kitIcon2(glyph) } }) : null,
     heading && /* @__PURE__ */ jsx36("div", { className: "ui-empty__title", children: heading }),
@@ -4760,6 +4760,97 @@ var AccentPicker = forwardRef10(function AccentPicker2({
   );
 });
 
+// src/NavTabs.tsx
+import { Fragment as Fragment14, forwardRef as forwardRef11, useEffect as useEffect17, useRef as useRef21, useImperativeHandle as useImperativeHandle2 } from "react";
+import { safeUrl, observeNavFit, revealCurrentNav, revealFocusedNav } from "@apliteni/apliteni-ui";
+import { Fragment as Fragment15, jsx as jsx40, jsxs as jsxs34 } from "react/jsx-runtime";
+var NavTabs = forwardRef11(function NavTabs2({
+  items,
+  active,
+  variant = "underline",
+  renderLink,
+  className,
+  onFocus,
+  "aria-label": ariaLabel = "Tabs",
+  ...rest
+}, ref) {
+  const navRef = useRef21(null);
+  useImperativeHandle2(ref, () => navRef.current, []);
+  const signature = items.map((item) => item.id).join("\0");
+  useEffect17(() => observeNavFit(navRef.current), []);
+  useEffect17(() => {
+    if (navRef.current) revealCurrentNav(navRef.current);
+  }, [active, signature]);
+  return /* @__PURE__ */ jsx40(
+    "nav",
+    {
+      ...rest,
+      ref: navRef,
+      className: ["ui-nav", "ui-nav--tabs", `is-${variant}`, className].filter(Boolean).join(" "),
+      "aria-label": ariaLabel,
+      onFocus: (event) => {
+        if (navRef.current) revealFocusedNav(navRef.current, event.target);
+        onFocus?.(event);
+      },
+      children: items.map((item) => {
+        const badge = item.badge != null && typeof item.badge === "object" ? item.badge : { text: item.badge, tone: void 0 };
+        const inner = /* @__PURE__ */ jsxs34(Fragment15, { children: [
+          /* @__PURE__ */ jsx40("span", { className: "ui-nav__tab-label", children: item.label }),
+          badge.text != null && badge.text !== "" && /* @__PURE__ */ jsx40("span", { className: `ui-nav__badge is-${badge.tone || "neutral"}`, children: badge.text })
+        ] });
+        if (item.disabled) return /* @__PURE__ */ jsx40("span", { className: "ui-nav__tab is-disabled", "aria-disabled": "true", children: inner }, item.id);
+        const current = item.id === active;
+        const linkProps = {
+          className: ["ui-nav__tab", current && "is-active"].filter(Boolean).join(" "),
+          href: safeUrl(item.href || `#${item.id}`),
+          target: item.target,
+          "aria-current": current ? "page" : void 0,
+          children: inner
+        };
+        return /* @__PURE__ */ jsx40(Fragment14, { children: renderLink ? renderLink(item, linkProps) : /* @__PURE__ */ jsx40("a", { ...linkProps }) }, item.id);
+      })
+    }
+  );
+});
+
+// src/Breadcrumbs.tsx
+import { forwardRef as forwardRef12 } from "react";
+import { icon as icon6, safeUrl as safeUrl2 } from "@apliteni/apliteni-ui";
+import { Fragment as Fragment16, jsx as jsx41, jsxs as jsxs35 } from "react/jsx-runtime";
+var Breadcrumbs = forwardRef12(function Breadcrumbs2({
+  items,
+  renderLink,
+  className,
+  "aria-label": ariaLabel = "Breadcrumb",
+  ...rest
+}, ref) {
+  return /* @__PURE__ */ jsx41(
+    "nav",
+    {
+      ...rest,
+      ref,
+      className: ["ui-nav", "ui-nav--crumbs", className].filter(Boolean).join(" "),
+      "aria-label": ariaLabel,
+      children: /* @__PURE__ */ jsx41("ol", { className: "ui-nav__crumbs", children: items.map((item, index) => {
+        const current = index === items.length - 1;
+        const inner = /* @__PURE__ */ jsxs35(Fragment16, { children: [
+          item.icon && /* @__PURE__ */ jsx41("span", { className: "ui-nav__ic", dangerouslySetInnerHTML: { __html: icon6(item.icon) } }),
+          /* @__PURE__ */ jsx41("span", { className: "ui-nav__crumb-label", children: item.label })
+        ] });
+        const linkProps = !current && item.href ? { className: "ui-nav__crumb", href: safeUrl2(item.href), target: item.target, children: inner } : null;
+        return /* @__PURE__ */ jsx41("li", { className: "ui-nav__crumb-item", children: linkProps ? renderLink ? renderLink(item, linkProps) : /* @__PURE__ */ jsx41("a", { ...linkProps }) : /* @__PURE__ */ jsx41(
+          "span",
+          {
+            className: ["ui-nav__crumb", current && "is-current"].filter(Boolean).join(" "),
+            "aria-current": current ? "page" : void 0,
+            children: inner
+          }
+        ) }, index);
+      }) })
+    }
+  );
+});
+
 // src/index.ts
 var PAGE_SIZES = KIT_PAGE_SIZES;
 var DEFAULT_PAGE_SIZE3 = KIT_DEFAULT_PAGE_SIZE;
@@ -4768,6 +4859,7 @@ export {
   AppShell,
   BackLink,
   Badge,
+  Breadcrumbs,
   BusyRegion,
   Button,
   Callout,
@@ -4793,6 +4885,7 @@ export {
   Icon,
   KeyValueList,
   Modal,
+  NavTabs,
   NumericValue,
   PAGE_SIZES,
   Pagination,

package/src/components/index.js

@@ -7,7 +7,7 @@ import { icon } from '../assets/icons.js';
 import { illo } from '../assets/illustrations.js';
 import { successCheck } from './success.js';
 import { esc, safeUrl } from '../html.js';
-export { esc } from '../html.js';
+export { esc, safeUrl } from '../html.js';
 const cx = (...a) => a.filter(Boolean).join(' ');
 // ---- Button --------------------------------------------------------------
 // `iconSvg` is a raw leading-icon SVG string (trusted markup, not escaped) for

package/src/components/nav.js

@@ -5,10 +5,11 @@
 //
 // These are NAVIGATION controls, not tab panels — so tabs render as
 // <nav> + <a aria-current="page">, not role="tablist" (that is what segmented()
-// is for). Only the collapsible sidebar groups need JS; wire with wireNav().
+// is for). wireNav() opens sidebar groups and reveals the current route link.
 import { esc, icon } from './index.js';
 import { playEntrance } from '../motion.js';
 import { safeUrl } from '../html.js';
+import { observeNavFit, revealCurrentNav, revealFocusedNav } from '../logic/nav.js';
 const cx = (...a) => a.filter(Boolean).join(' ');
 
 // Unique-per-render ids so a section heading can label its own list. Module
@@ -177,9 +178,9 @@ export function nav({ variant = 'sidebar', ...opts } = {}) {
 }
 
 // ---- Behaviour -----------------------------------------------------------
-// Only the collapsible sidebar groups need JS: toggle a group's `.is-open` +
-// its button's aria-expanded, and show/hide the nested list. Idempotent and
-// event-delegated, so it's safe to call repeatedly (Storybook re-renders).
+// Toggle a sidebar group's `.is-open` and its button's aria-expanded, and
+// show/hide the nested list. Idempotent and event-delegated, so it's safe to
+// call repeatedly (Storybook re-renders).
 let _navGlobalWired = false;
 
 function toggleGroup(btn) {
@@ -194,10 +195,24 @@ function toggleGroup(btn) {
   }
 }
 
+const fitObservers = new Map();
 export function wireNav(root = document) {
+  for (const [nav, stop] of fitObservers) {
+    if (!nav.isConnected) { stop(); fitObservers.delete(nav); }
+  }
+  root.querySelectorAll('.ui-nav--tabs').forEach((nav) => {
+    if (!fitObservers.has(nav)) fitObservers.set(nav, observeNavFit(nav));
+    revealCurrentNav(nav);
+  });
   // Per-collapsed-rail behaviour would go here; groups use one delegated handler.
   if (_navGlobalWired) return;
   _navGlobalWired = true;
+  // A tab row scrolls its own focused link clear of its edge, so the ring the link
+  // draws is not cut off by the scroll box. Delegated, because the links come and go.
+  document.addEventListener('focusin', (e) => {
+    const row = e.target.closest && e.target.closest('.ui-nav--tabs');
+    if (row) revealFocusedNav(row, e.target);
+  });
   document.addEventListener('click', (e) => {
     const btn = e.target.closest && e.target.closest('[data-nav-toggle]');
     if (btn) { e.preventDefault(); toggleGroup(btn); }

package/src/index.d.ts

@@ -1,4 +1,12 @@
+/** Watch tab content and width without changing the current route. Call the result on removal. */
+export declare function observeNavFit(nav: HTMLElement): () => void;
 export declare function esc(value: unknown): string;
+/** The URL boundary every factory and React component sends a destination through. */
+export declare function safeUrl(value: unknown, fallback?: string): string;
+/** Scroll a tab row so its `aria-current` link is inside the viewport. */
+export declare function revealCurrentNav(nav: HTMLElement): void;
+/** Scroll a tab row so the link a focus event landed on clears the row's edge. */
+export declare function revealFocusedNav(nav: HTMLElement, target: EventTarget | null): void;
 export declare function field(opts?: Record<string, unknown>): string;
 export declare function input(opts?: Record<string, unknown>): string;
 export declare function textarea(opts?: Record<string, unknown>): string;

package/src/index.js

@@ -35,4 +35,5 @@ export { PAGE_SIZES, DEFAULT_PAGE_SIZE } from './logic/pagination.js';
 export { calloutIcons } from './logic/callout.js';
 export { formatNumericValue, formatDeltaValue } from './logic/table-values.js';
 export { accentSwatchStyle } from './logic/accents.js';
+export { observeNavFit, revealCurrentNav, revealFocusedNav } from './logic/nav.js';
 export { CHART_FLOOR, chartScale, bridgeWalk, pointTarget } from './logic/chart.js';

package/src/logic/nav.js

@@ -0,0 +1,65 @@
+// A tab row's padding is the room its links' focus rings are painted in, so an item
+// brought to the row's CONTENT edge keeps its whole ring inside the scroll box: the
+// solid band reaches --ring-gap-width + --ring-width = 3px out of a 4px padding.
+// Both readers below want that edge — the current route so its label is not cut off,
+// a link Tab landed on so its ring is not. Neither moves focus or scrolls the page;
+// only the row's own scrollLeft changes.
+function revealNavItem(nav, item) {
+  if (!item || nav.scrollWidth <= nav.clientWidth) return;
+  const bounds = nav.getBoundingClientRect();
+  const box = item.getBoundingClientRect();
+  const style = nav.ownerDocument.defaultView.getComputedStyle(nav);
+  const left = bounds.left + (parseFloat(style.paddingLeft) || 0);
+  const right = bounds.right - (parseFloat(style.paddingRight) || 0);
+  if (box.left < left) nav.scrollLeft += box.left - left;
+  else if (box.right > right) nav.scrollLeft += box.right - right;
+}
+
+// Measure with overflow enabled so visible child paint cannot inflate scrollWidth.
+// One pixel allows fractional columns. Unmeasured rows keep their scroll containment.
+function fitNav(nav) {
+  nav.removeAttribute('data-nav-fit');
+  if (!nav.clientWidth) return;
+  if (nav.scrollWidth - nav.clientWidth <= 1) nav.setAttribute('data-nav-fit', '');
+}
+
+// Watch layout independently from route changes so a resize preserves the reader's scroll.
+export function observeNavFit(nav) {
+  const win = nav.ownerDocument.defaultView;
+  const measure = () => fitNav(nav);
+  const resize = win.ResizeObserver ? new win.ResizeObserver(measure) : null;
+  const observe = () => {
+    resize?.disconnect();
+    resize?.observe(nav);
+    for (const child of nav.children) resize?.observe(child);
+    measure();
+  };
+  const changes = new win.MutationObserver(observe);
+  changes.observe(nav, {
+    childList: true, subtree: true, characterData: true,
+    attributes: true, attributeFilter: ['class', 'style'],
+  });
+  observe();
+  win.addEventListener('resize', measure);
+  return () => {
+    resize?.disconnect();
+    changes.disconnect();
+    win.removeEventListener('resize', measure);
+  };
+}
+
+// Reveal only on an explicit route change or initial wiring.
+export function revealCurrentNav(nav) {
+  fitNav(nav);
+  revealNavItem(nav, nav.querySelector('[aria-current="page"]'));
+}
+
+// Reveal the tab a focus event landed on. Chromium brings a focused child to the
+// scroll box's own edge at best, which is the ring's room rather than the label's,
+// so the solid band is clipped by the pixels the link hangs out: measured at 390px,
+// 3.86px on the underline row and 13.86px on the pill row, with scrollLeft left at
+// 0. Repaying the padding puts the band back inside. #429
+export function revealFocusedNav(nav, target) {
+  const item = target && target.closest ? target.closest('.ui-nav__tab') : null;
+  if (item && nav.contains(item)) revealNavItem(nav, item);
+}

package/src/styles/card.css

@@ -8,6 +8,7 @@
    instead — a 22px penumbra off a 10px offset, the width Artur's reference uses on a
    card. Chosen by him on #490 round t3. why: docs/foundations.md#elevation */
 .ui-card {
+  --ui-card-ground: var(--surface); /* the ground a scrolling row inside covers its edge with; a tint repeats it below */
   background: var(--surface);
   border: 1px solid var(--card-edge);
   box-shadow: var(--elev-rest);
@@ -51,10 +52,12 @@
    works in dark sinks a light card below the page. Each variant edges itself in its own
    colour. why: docs/foundations.md#elevation */
 .ui-card--accent {
+  --ui-card-ground: color-mix(in srgb, var(--accent) var(--card-tint), var(--surface));
   background: color-mix(in srgb, var(--accent) var(--card-tint), var(--surface));
   border-color: color-mix(in srgb, var(--accent) 22%, transparent);
 }
 .ui-card--live {
+  --ui-card-ground: color-mix(in srgb, var(--green) var(--card-tint), var(--surface));
   background: color-mix(in srgb, var(--green) var(--card-tint), var(--surface));
   border-color: color-mix(in srgb, var(--green) 22%, transparent);
 }

package/src/styles/nav.css

@@ -285,14 +285,58 @@
 
 /* -- Horizontal tabs ----------------------------------------------------- */
 .ui-nav--tabs {
+  /* A scroll box clips at its padding edge, so the ring needs padding, not bare
+     paint room. Equal negative margins give the row back its place on the gutter
+     and in the flow, and the rule is painted as a background line one pixel above
+     the padding — a border-bottom would sit below it and lift the active
+     underline off the rule. */
+  --ui-tabs-ring-room: var(--space-1);
+  --ui-tabs-rule: 1px;
+  --ui-tabs-ground: var(--bg);
+  --ui-tabs-edge: color-mix(in srgb, var(--sheen) 12%, transparent);
+  min-width: 0;
+  max-width: calc(100% + 2 * var(--ui-tabs-ring-room));
+  overflow-x: auto;
+  padding: var(--ui-tabs-ring-room);
+  margin: calc(-1 * var(--ui-tabs-ring-room)) calc(-1 * var(--ui-tabs-ring-room))
+    calc(var(--ui-tabs-rule) - var(--ui-tabs-ring-room));
   display: flex;
   align-items: stretch;
   gap: 4px;
-  border-bottom: 1px solid var(--border);
+  /* Local covers hide the table-style shades when their edge is reached.
+     The row rule stays above the covers and keeps its original position. */
+  background-image:
+    linear-gradient(var(--border), var(--border)),
+    linear-gradient(to right, var(--ui-tabs-ground) 50%, transparent),
+    linear-gradient(to left, var(--ui-tabs-ground) 50%, transparent),
+    radial-gradient(farthest-side at 0 50%, var(--ui-tabs-edge), transparent),
+    radial-gradient(farthest-side at 100% 50%, var(--ui-tabs-edge), transparent);
+  background-repeat: no-repeat;
+  background-position:
+    center bottom calc(var(--ui-tabs-ring-room) - var(--ui-tabs-rule)),
+    0 0, 100% 0, 0 0, 100% 0;
+  background-size:
+    calc(100% - 2 * var(--ui-tabs-ring-room)) var(--ui-tabs-rule),
+    var(--space-6) 100%, var(--space-6) 100%, var(--space-3) 100%, var(--space-3) 100%;
+  background-attachment: scroll, local, local, scroll, scroll;
 }
-.ui-nav--tabs.is-pill { border-bottom: 0; gap: 6px; }
+/* Fitting rows keep overflow visible. Measurements retain the same padding and margins,
+   so switching containment does not move the links. Unwired rows keep containment. */
+.ui-nav--tabs[data-nav-fit] { overflow: visible; }
+.ui-nav--tabs.is-pill { --ui-tabs-rule: 0px; gap: 6px; }
+.ui-card .ui-nav--tabs { --ui-tabs-ground: var(--ui-card-ground); }
+:root[data-theme="light"] .ui-nav--tabs {
+  --ui-tabs-edge: color-mix(in srgb, var(--shadow-ink) 13%, transparent);
+}
+/* The row is a keyboard stop of its own only while it scrolls AND holds no focusable
+   link — every tab disabled — and Chromium answers that stop with its black outline. It
+   is a scroll region, so it takes the kit's inward band like the other six: an outset
+   ring would be clipped by the very box that scrolls. #531's reading, on #429's row. */
+.ui-nav--tabs:focus-visible { outline: var(--ring-scroll); outline-offset: var(--ring-scroll-offset); }
 .ui-nav__tab {
+  flex: none;
   position: relative;
+  max-width: 100%;
   display: inline-flex;
   align-items: center;
   gap: 8px;
@@ -307,6 +351,7 @@
 .ui-nav__tab:hover { color: var(--strong); }
 .ui-nav__tab:focus-visible { outline: var(--ring); outline-offset: var(--ring-offset); border-radius: 8px; }
 .ui-nav__tab.is-active { color: var(--strong); }
+.ui-nav__tab-label { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 
 /* underline variant */
 .ui-nav--tabs.is-underline .ui-nav__tab::after {
@@ -324,10 +369,26 @@
 
 /* pill variant */
 .ui-nav--tabs.is-pill .ui-nav__tab { border-radius: var(--radius-pill); padding: 8px 15px; }
-.ui-nav--tabs.is-pill .ui-nav__tab:hover { background: var(--surface); /* code-bg: inherit — control paint; the containing surface is the ground, for a chip and for a band alike. */ }
+.ui-nav--tabs.is-pill .ui-nav__tab:hover { background: var(--surface); /* code-bg: inherit — control paint; its focus indicator uses the containing surface. */ }
+/* The current route keeps its quiet fill and uses accent ink. */
 .ui-nav--tabs.is-pill .ui-nav__tab.is-active {
-  background: var(--glow-purple); /* code-bg: inherit — a wash paints over a ground and behind a chip, so the opaque ground below it is the step. */
   color: var(--accent);
+  background: var(--glow-purple); /* code-bg: inherit — translucent wash retains the opaque containing gap. */
+}
+
+/* Forced colours: the selected-tab marks are in the block below. */
+@media (forced-colors: active) {
+  /* Forced colours drop background images, so the row's rule comes back as a border.
+     The last pixel of the bottom padding pays for it and the row keeps its size. The
+     border image leaves the ring room at both ends bare, so the rule ends on the gutter
+     as the background line does. */
+  .ui-nav--tabs {
+    padding-bottom: calc(var(--ui-tabs-ring-room) - var(--ui-tabs-rule));
+    border-bottom: var(--ui-tabs-rule) solid;
+    border-image: linear-gradient(to right, transparent var(--ui-tabs-ring-room),
+      CanvasText var(--ui-tabs-ring-room) calc(100% - var(--ui-tabs-ring-room)),
+      transparent calc(100% - var(--ui-tabs-ring-room))) 0 0 1 0;
+  }
 }
 
 .ui-nav__tab.is-disabled { /* muted-ink: state — unavailable control */ color: var(--disabled-ink); cursor: default; }