@tangle-network/ui 11.34.0 → 11.36.0

package/src/primitives/heading.tsx

@@ -38,6 +38,7 @@ export interface HeadingProps
   extends Omit<React.HTMLAttributes<HTMLElement>, "role"> {
   /** Visual treatment, independent of the rendered element. Defaults to section. */
   variant?: HeadingVariant;
+  presentation?: "operational" | "expressive";
   /** Semantic element; changing it does not change the visual variant. */
   as?: React.ElementType;
   /**
@@ -53,7 +54,7 @@ export interface HeadingProps
  * display/page h1 per page; choose `as` according to the document hierarchy.
  */
 const Heading = React.forwardRef<HTMLElement, HeadingProps>(
-  ({ variant, role, as, className, ...props }, ref) => {
+  ({ variant, role, as, className, presentation, ...props }, ref) => {
     const legacyVariant =
       role && Object.prototype.hasOwnProperty.call(VARIANT_CLASS, role)
         ? (role as HeadingVariant)
@@ -64,7 +65,8 @@ const Heading = React.forwardRef<HTMLElement, HeadingProps>(
     return (
       <Tag
         ref={ref}
-        className={cn("[overflow-wrap:anywhere]", VARIANT_CLASS[visualVariant], className)}
+        className={cn("[overflow-wrap:anywhere]", presentation ? (presentation === "expressive" ? "tangle-display" : "tangle-heading") : VARIANT_CLASS[visualVariant], className)}
+        data-variant={presentation ? visualVariant : undefined}
         role={legacyVariant ? undefined : role}
         {...props}
       />

package/src/primitives/help-text.tsx

@@ -1,3 +1,4 @@
+import { helpPresentation } from "../presentation";
 import * as React from "react";
 import { cn } from "../lib/utils";
 
@@ -17,8 +18,8 @@ const HelpText = React.forwardRef<HTMLParagraphElement, HelpTextProps>(
       ref={ref}
       data-tone={tone}
       className={cn(
-        "text-[length:var(--font-size-help,0.75rem)] leading-4",
-        tone === "error" ? "font-medium text-[var(--surface-danger-text)]" : "text-[var(--text-dim)]",
+        helpPresentation.root,
+        helpPresentation[tone],
         className,
       )}
       {...props}

package/src/primitives/input.tsx

@@ -1,45 +1,17 @@
 "use client";
 
 import * as React from "react";
-import { controlRadius, controlSizes, controlText, fieldPresentation, fieldSizes, fieldTouchText } from "../lib/control-presentation";
+import { controlRadius, controlSizes, controlText, fieldPresentation, fieldTouchText } from "../lib/control-presentation";
 import { focusFieldInvalid } from "../lib/focus";
 import { cn } from "../lib/utils";
 import { HelpText } from "./help-text";
 import { Label } from "./label";
 
-import { cva, type VariantProps } from "class-variance-authority";
+import { inputVariants } from "../presentation";
+import { type VariantProps } from "class-variance-authority";
 
 // Sizes follow the shared control scale (control-presentation.ts), so an Input
 // and a Button at the same size share a height, text size and corner.
-const inputVariants = cva(
-  cn(
-    "flex w-full border py-1 placeholder:text-[var(--text-dim)] disabled:cursor-not-allowed disabled:opacity-50 file:border-0 file:bg-transparent file:font-medium",
-    fieldPresentation,
-    fieldTouchText,
-  ),
-  {
-    variants: {
-      // `default` and `sandbox` render the same field; both names stay valid.
-      variant: {
-        default: "",
-        sandbox: "",
-        error: focusFieldInvalid,
-      },
-      size: {
-        default: fieldSizes.md,
-        md: fieldSizes.md,
-        sm: fieldSizes.sm,
-        lg: fieldSizes.lg,
-        compact: cn(fieldSizes.md, controlSizes.compact),
-        touch: cn(fieldSizes.md, controlSizes.touch),
-      }
-    },
-    defaultVariants: {
-      variant: "default",
-      size: "default",
-    },
-  }
-);
 
 // Only rendered descriptions are added; caller IDs and their order are retained.
 function descriptionIds(...ids: Array<string | undefined>) {

package/src/primitives/label.tsx

@@ -1,14 +1,12 @@
 "use client";
 
 import * as LabelPrimitive from "@radix-ui/react-label";
-import { cva, type VariantProps } from "class-variance-authority";
+import { labelVariants } from "../presentation";
 import * as React from "react";
 import { cn } from "../lib/utils";
 
 // One label size (`--font-size-label`, 14px) for every field size.
-const labelVariants = cva(
-  "font-medium text-[length:var(--font-size-label,0.875rem)] leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70",
-);
+
 
 const Label = React.forwardRef<
   React.ElementRef<typeof LabelPrimitive.Root>,

package/src/primitives/metric-strip.tsx

@@ -1,17 +1,8 @@
+import { metricPresentation, metricLayouts } from "../presentation";
 import * as React from "react";
 import { cn } from "../lib/utils";
 import { StatusPill, type StatusTone } from "./status-pill";
 
-// Each finite preset owns its grid AND its row-start rules. Keep the strings
-// literal so host Tailwind consumers scanning the published source emit them.
-// Ranges do not overlap: no drawn border is subsequently suppressed.
-const layouts = {
-  3: "grid-cols-2 sm:grid-cols-3 max-sm:[&>div:not(:nth-child(2n+1))]:border-l sm:[&>div:not(:nth-child(3n+1))]:border-l",
-  4: "grid-cols-2 sm:grid-cols-4 max-sm:[&>div:not(:nth-child(2n+1))]:border-l sm:[&>div:not(:nth-child(4n+1))]:border-l",
-  5: "grid-cols-2 sm:grid-cols-3 lg:grid-cols-5 max-sm:[&>div:not(:nth-child(2n+1))]:border-l sm:max-lg:[&>div:not(:nth-child(3n+1))]:border-l lg:[&>div:not(:nth-child(5n+1))]:border-l",
-  6: "grid-cols-2 sm:grid-cols-3 lg:grid-cols-6 max-sm:[&>div:not(:nth-child(2n+1))]:border-l sm:max-lg:[&>div:not(:nth-child(3n+1))]:border-l lg:[&>div:not(:nth-child(6n+1))]:border-l",
-} as const;
-
 /** Headline readings on one plane, with native definition-list semantics. */
 export interface MetricStripProps
   extends React.HTMLAttributes<HTMLDListElement> {
@@ -26,8 +17,8 @@ const MetricStrip = React.forwardRef<HTMLDListElement, MetricStripProps>(
     <dl
       ref={ref}
       className={cn(
-        "grid min-w-0 rounded-[var(--radius-lg)] border border-border bg-card shadow-[var(--shadow-card)]",
-        layouts[columns],
+        metricPresentation.strip,
+        metricLayouts[columns],
         className,
       )}
       {...props}
@@ -55,10 +46,10 @@ const Metric = React.forwardRef<HTMLDivElement, MetricProps>(
   ({ className, label, value, hint, attention, icon, ...props }, ref) => (
     <div
       ref={ref}
-      className={cn("min-w-0 border-border p-4 sm:p-5", className)}
+      className={cn(metricPresentation.item, className)}
       {...props}
     >
-      <dt className="flex min-w-0 flex-wrap items-center gap-2 text-muted-foreground text-sm">
+      <dt className={metricPresentation.label}>
         {icon != null && icon !== false && (
           <span
             aria-hidden="true"
@@ -67,7 +58,7 @@ const Metric = React.forwardRef<HTMLDivElement, MetricProps>(
             {icon}
           </span>
         )}
-        <span className="min-w-0 whitespace-normal [overflow-wrap:anywhere]">{label}</span>
+        <span className={metricPresentation.labelText}>{label}</span>
         {attention && (
           <StatusPill tone={attention.tone}>{attention.label}</StatusPill>
         )}
@@ -76,7 +67,7 @@ const Metric = React.forwardRef<HTMLDivElement, MetricProps>(
           title. Wrap even unbroken values without making the grid wider. */}
       <dd
         className={cn(
-          "mt-1 whitespace-normal [overflow-wrap:anywhere] font-semibold text-xl tabular-nums tracking-tight lg:text-2xl",
+          metricPresentation.value,
           attention?.tone === "danger" && "text-[var(--surface-danger-text)]",
         )}
         title={typeof value === "string" ? value : undefined}
@@ -85,7 +76,7 @@ const Metric = React.forwardRef<HTMLDivElement, MetricProps>(
       </dd>
       {hint !== undefined && hint !== null && hint !== false && hint !== "" && (
         <dd
-          className="mt-0.5 whitespace-normal [overflow-wrap:anywhere] text-[var(--text-dim)] text-xs"
+          className={metricPresentation.hint}
           title={typeof hint === "string" ? hint : undefined}
         >
           {hint}

package/src/primitives/page-header.tsx

@@ -10,6 +10,7 @@ import { Heading } from "./heading";
 export interface PageHeaderProps
   extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
   title: React.ReactNode;
+  presentation?: "operational" | "expressive";
   description?: React.ReactNode;
   /** Canonical action slot. If supplied (even null), takes precedence over action. */
   actions?: React.ReactNode;
@@ -31,6 +32,7 @@ const PageHeader = React.forwardRef<HTMLElement, PageHeaderProps>(
   (
     {
       className,
+      presentation,
       title,
       description,
       actions,
@@ -46,28 +48,29 @@ const PageHeader = React.forwardRef<HTMLElement, PageHeaderProps>(
   ) => {
     const resolvedActions = actions === undefined ? action : actions;
     return (
-      <header ref={ref} className={cn("mb-6 min-w-0", className)} {...props}>
-        <div className="flex min-w-0 flex-wrap items-start justify-between gap-x-6 gap-y-3">
+      <header ref={ref} className={cn(presentation === "expressive" ? "tangle-intro" : presentation === "operational" ? "tangle-page-header" : "mb-6 min-w-0", className)} {...props}>
+        <div className={presentation ? "tangle-page-header-main" : "flex min-w-0 flex-wrap items-start justify-between gap-x-6 gap-y-3"}>
           <div className="min-w-0 flex-[1_1_16rem]">
             {hasContent(eyebrow) && (
               <Heading variant="eyebrow" className="mb-1.5">{eyebrow}</Heading>
             )}
             <Heading
               id={titleId}
-              variant={level === 1 ? "page" : "section"}
+              variant={presentation === "expressive" ? "display" : level === 1 ? "page" : "section"}
+              presentation={presentation}
               as={titleAs ?? (level === 1 ? "h1" : "h2")}
               className="text-balance"
             >
               {title}
             </Heading>
             {hasContent(description) && (
-              <p className="mt-1 max-w-prose text-muted-foreground text-sm [overflow-wrap:anywhere]">
+              <p className={presentation === "expressive" ? "tangle-intro-description" : presentation ? "tangle-page-description" : "mt-1 max-w-prose text-muted-foreground text-sm [overflow-wrap:anywhere]"}>
                 {description}
               </p>
             )}
           </div>
           {hasContent(resolvedActions) && (
-            <div className="flex min-w-0 max-w-full flex-wrap items-center gap-2 [overflow-wrap:anywhere] [&>*]:min-w-0 [&>*]:max-w-full">
+            <div className={presentation === "expressive" ? "tangle-intro-actions" : "flex min-w-0 max-w-full flex-wrap items-center gap-2 [overflow-wrap:anywhere] [&>*]:min-w-0 [&>*]:max-w-full"}>
               {resolvedActions}
             </div>
           )}

package/src/primitives/page-shell.tsx

@@ -2,7 +2,13 @@ import type { ReactNode } from "react";
 import { cn } from "../lib/utils";
 
 export interface PageShellProps {
-  children: ReactNode;
+  children?: ReactNode;
+  /** Optional reading layout. Content, routing and navigation interaction stay caller-owned. */
+  navigation?: ReactNode;
+  article?: ReactNode;
+  outline?: ReactNode;
+  navigationLabel?: string;
+  outlineLabel?: string;
   className?: string;
 }
 
@@ -12,7 +18,12 @@ export interface PageShellProps {
  * The caller owns landmarks, routing, auth, navigation and data state. Use
  * className to override the bound/gutters, or omit it for a workbench layout.
  */
-export function PageShell({ children, className }: PageShellProps) {
+export function PageShell({ children, className, navigation, article, outline, navigationLabel = "Sections", outlineLabel = "On this page" }: PageShellProps) {
+  if (navigation || article || outline) return <div className={cn("tangle-reading-shell",className)}>
+    {navigation && <nav aria-label={navigationLabel} className="tangle-reading-nav">{navigation}</nav>}
+    <article className="tangle-reading-article">{article ?? children}</article>
+    {outline && <aside aria-label={outlineLabel} className="tangle-reading-outline">{outline}</aside>}
+  </div>;
   return (
     <div
       className={cn(

package/src/primitives/segmented-control.stories.tsx

@@ -0,0 +1,89 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import * as React from "react"
+import { SegmentedControl, type SegmentedControlOption } from "./segmented-control"
+
+const meta: Meta = {
+  title: "Primitives/SegmentedControl",
+  parameters: { layout: "fullscreen" },
+}
+
+export default meta
+type Story = StoryObj
+
+const workTabs: SegmentedControlOption[] = [
+  { value: "today", label: "Today" },
+  { value: "messages", label: "Messages" },
+  { value: "tasks", label: "Tasks" },
+  { value: "operations", label: "Operations" },
+  { value: "payments", label: "Payments" },
+  { value: "approvals", label: "Approvals" },
+  { value: "activity", label: "Activity" },
+  { value: "people", label: "People" },
+]
+
+const fileSources: SegmentedControlOption[] = [
+  { value: "knowledge", label: "Knowledge" },
+  { value: "attachments", label: "Attachments" },
+  { value: "apps", label: "Apps & chats" },
+]
+
+function Controlled({
+  initial,
+  render,
+}: {
+  initial: string
+  render: (value: string, setValue: (value: string) => void) => React.ReactNode
+}) {
+  const [value, setValue] = React.useState(initial)
+  return <>{render(value, setValue)}</>
+}
+
+/**
+ * Eight section tabs on a 390 px phone, as a workspace header renders them:
+ * full width with the page's 16 px inline padding on the strip itself. Most
+ * tabs sit past the right edge, the selected one starts off screen, and the
+ * cut lands in the gap between two tabs, so only a chevron shows that the strip
+ * scrolls.
+ */
+export const OverflowingTabs: Story = {
+  render: () => (
+    <div className="w-full max-w-[390px] py-4">
+      <Controlled
+        initial="approvals"
+        render={(value, setValue) => (
+          <SegmentedControl
+            data-testid="overflow-tabs"
+            aria-label="Work"
+            variant="tabs"
+            value={value}
+            onValueChange={setValue}
+            options={workTabs}
+            className="w-full px-4"
+          />
+        )}
+      />
+    </div>
+  ),
+}
+
+/** A row control a host made scroll instead of wrap, beside a page title. */
+export const OverflowingRow: Story = {
+  render: () => (
+    <div className="flex w-full max-w-[390px] items-center gap-3 px-4 py-4">
+      <h2 className="shrink-0 text-lg font-semibold">Files</h2>
+      <Controlled
+        initial="knowledge"
+        render={(value, setValue) => (
+          <SegmentedControl
+            data-testid="overflow-row"
+            aria-label="File source"
+            value={value}
+            onValueChange={setValue}
+            options={fileSources}
+            className="min-w-0 flex-nowrap overflow-x-auto"
+          />
+        )}
+      />
+    </div>
+  ),
+}

package/src/primitives/segmented-control.test.tsx

@@ -361,13 +361,14 @@ describe("SegmentedControl tabs on a narrow strip", () => {
     Object.defineProperty(proto, key, { configurable: true, ...descriptor })
   }
   const isStrip = (el: Element) => el.getAttribute("role") === "radiogroup"
-  const index = (el: Element) => Array.from(el.parentElement?.children ?? []).indexOf(el)
+  // Options sit side by side; the edge chevrons take no room in the row.
+  const index = (el: Element) => Array.from(el.parentElement?.querySelectorAll(':scope > [role="radio"]') ?? []).indexOf(el)
 
   beforeEach(() => {
     define(HTMLElement.prototype, "offsetLeft", { get(this: HTMLElement) { return isStrip(this) ? 0 : index(this) * TAB } })
     define(HTMLElement.prototype, "offsetWidth", { get(this: HTMLElement) { return isStrip(this) ? STRIP : TAB } })
     define(Element.prototype, "clientWidth", { get(this: Element) { return isStrip(this) ? STRIP : TAB } })
-    define(Element.prototype, "scrollWidth", { get(this: Element) { return isStrip(this) ? this.children.length * TAB : TAB } })
+    define(Element.prototype, "scrollWidth", { get(this: Element) { return isStrip(this) ? this.querySelectorAll(':scope > [role="radio"]').length * TAB : TAB } })
     define(Element.prototype, "scrollLeft", {
       get(this: Element) { return scroll.get(this) ?? 0 },
       set(this: Element, v: number) { scroll.set(this, v) },
@@ -390,32 +391,44 @@ describe("SegmentedControl tabs on a narrow strip", () => {
       <SegmentedControl aria-label="Work" variant="tabs" value="payments" onValueChange={vi.fn()} options={work} />,
     )
     const strip = screen.getByRole("radiogroup")
-    // Payments spans 400-500px: its right edge plus the 24px fade fits the 250px view.
-    expect(strip.scrollLeft).toBe(500 - STRIP + 24)
+    // Payments spans 400-500px: its right edge clears the 32px chevron, plus a 4px gap, in the 250px view.
+    expect(strip.scrollLeft).toBe(500 - STRIP + 32 + 4)
 
     rerender(<SegmentedControl aria-label="Work" variant="tabs" value="today" onValueChange={vi.fn()} options={work} />)
     expect(strip.scrollLeft).toBe(0)
   })
 
-  it("fades the edge that has more tabs past it", () => {
+  it("shows a chevron at the edge that has more tabs past it", () => {
     const { rerender } = render(
       <SegmentedControl aria-label="Work" variant="tabs" value="today" onValueChange={vi.fn()} options={work} />,
     )
     const strip = screen.getByRole("radiogroup")
     expect(strip).toHaveAttribute("data-overflow-end", "true")
     expect(strip).not.toHaveAttribute("data-overflow-start")
-    expect(strip.className).toContain("data-[overflow-end]:[mask-image:linear-gradient(to_right,#000_calc(100%-24px),transparent)]")
+    expect(strip.querySelector('[data-scroll-cue="end"]')).not.toBeNull()
+    expect(strip.querySelector('[data-scroll-cue="start"]')).toBeNull()
 
     rerender(<SegmentedControl aria-label="Work" variant="tabs" value="people" onValueChange={vi.fn()} options={work} />)
     expect(strip).toHaveAttribute("data-overflow-start", "true")
     expect(strip).not.toHaveAttribute("data-overflow-end")
+    expect(strip.querySelector('[data-scroll-cue="start"]')).not.toBeNull()
+    expect(strip.querySelector('[data-scroll-cue="end"]')).toBeNull()
   })
 
-  it("leaves a strip that fits unmasked", () => {
+  it("keeps the chevrons out of the radio group and the tab order", () => {
+    render(<SegmentedControl aria-label="Work" variant="tabs" value="today" onValueChange={vi.fn()} options={work} />)
+    expect(screen.getAllByRole("radio")).toHaveLength(work.length)
+    const cue = screen.getByRole("radiogroup").querySelector('[data-scroll-cue="end"]')
+    expect(cue).toHaveAttribute("aria-hidden", "true")
+    expect(cue).toHaveAttribute("tabindex", "-1")
+  })
+
+  it("leaves a strip that fits without chevrons", () => {
     render(<SegmentedControl aria-label="Work" variant="tabs" value="all" onValueChange={vi.fn()} options={options.slice(0, 2)} />)
     const strip = screen.getByRole("radiogroup")
     expect(strip).not.toHaveAttribute("data-overflow-start")
     expect(strip).not.toHaveAttribute("data-overflow-end")
+    expect(strip.querySelector("[data-scroll-cue]")).toBeNull()
   })
 })
 

package/src/primitives/segmented-control.tsx

@@ -2,6 +2,7 @@
 
 declare const process: { env: { NODE_ENV?: string } } | undefined
 
+import { ChevronLeft, ChevronRight } from "lucide-react"
 import * as React from "react"
 import { touchTarget } from "../lib/control-presentation"
 import { focusRing, focusRingInset } from "../lib/focus"
@@ -32,9 +33,12 @@ import { cn } from "../lib/utils"
  *   - Every label keeps one weight. Selection is colour plus surface or
  *     underline, so changing the value never reflows the row.
  *
- * The tabs variant scrolls sideways when its options outgrow the row: the
- * selected tab is kept in view, and a faded edge shows that more tabs sit
- * past it.
+ * When the options outgrow the row they scroll sideways (the tabs variant
+ * always can; the row variant can when a host gives it `flex-nowrap
+ * overflow-x-auto`). A chevron button pinned to each edge with options past it
+ * shows that the strip scrolls and pages it on click or tap; touch and
+ * trackpad scroll it natively, and arrow keys move the selection, which is
+ * kept fully in view clear of the chevrons.
  */
 export interface SegmentedControlOption<T extends string = string> {
   value: T
@@ -61,14 +65,47 @@ export interface SegmentedControlProps<T extends string = string>
   "data-testid"?: string
 }
 
-/** Width of the faded edge that marks more tabs past the strip, in px. */
-const TAB_EDGE_FADE = 24
-// Fade whichever edge has tabs past it; the two-attribute rule wins on specificity.
-const tabEdgeFade = [
-  "data-[overflow-start]:[mask-image:linear-gradient(to_right,transparent,#000_24px)]",
-  "data-[overflow-end]:[mask-image:linear-gradient(to_right,#000_calc(100%-24px),transparent)]",
-  "data-[overflow-start]:data-[overflow-end]:[mask-image:linear-gradient(to_right,transparent,#000_24px,#000_calc(100%-24px),transparent)]",
-]
+/** Size of the edge chevron, in px. The selected option is kept this far
+ *  (plus the strip's own padding) from an edge so the chevron never covers it. */
+const SCROLL_CUE_SIZE = 32
+/** The strip's flex gap (`gap-1`). A cue's negative margin cancels its width
+ *  and this gap, so showing it never shifts the options: a shift is not a
+ *  resize, so nothing would re-reveal the selected option afterwards. */
+const STRIP_GAP = 4
+
+/**
+ * A chevron pinned to one edge of the scrolling strip. It is a sticky flex
+ * item with a negative margin equal to its width plus the gap, so it takes no room in the
+ * row (showing it never reflows the options) and stays at the visible edge
+ * while the strip scrolls. A solid surface keeps it legible on any plane,
+ * which an edge fade is not: a fade over the gap between two options, or over
+ * a host's inline padding, shows nothing.
+ */
+function ScrollCue({ side, onPage }: { side: "start" | "end"; onPage: () => void }) {
+  const Icon = side === "start" ? ChevronLeft : ChevronRight
+  return (
+    <button
+      type="button"
+      // Pointer and touch affordance only: keyboard users move the selection
+      // with the arrow keys, and the strip keeps it in view.
+      tabIndex={-1}
+      aria-hidden="true"
+      data-scroll-cue={side}
+      onClick={onPage}
+      className={cn(
+        "sticky z-[1] flex shrink-0 items-center justify-center self-center rounded-full border border-border bg-card text-muted-foreground shadow-sm transition-colors hover:text-foreground",
+        side === "start" ? "left-0" : "right-0",
+      )}
+      style={{
+        width: SCROLL_CUE_SIZE,
+        height: SCROLL_CUE_SIZE,
+        [side === "start" ? "marginRight" : "marginLeft"]: -(SCROLL_CUE_SIZE + STRIP_GAP),
+      }}
+    >
+      <Icon className="h-4 w-4" aria-hidden="true" />
+    </button>
+  )
+}
 
 export function SegmentedControl<T extends string = string>({
   value,
@@ -92,7 +129,9 @@ export function SegmentedControl<T extends string = string>({
   const optionRefs = React.useRef<Map<string, HTMLButtonElement>>(new Map())
   const stripRef = React.useRef<HTMLDivElement>(null)
   const [overflow, setOverflow] = React.useState({ start: false, end: false })
-  const tabs = variant === "tabs"
+  // Re-observe when the option set changes, not on every render of a host
+  // that builds its options array inline.
+  const optionKey = options.map((o) => o.value).join("\u0000")
 
   const measureOverflow = React.useCallback(() => {
     const strip = stripRef.current
@@ -102,32 +141,52 @@ export function SegmentedControl<T extends string = string>({
     setOverflow((prev) => (prev.start === start && prev.end === end ? prev : { start, end }))
   }, [])
 
-  // Keep the selected tab inside the strip. Only the strip scrolls: the page
-  // never moves, which scrollIntoView cannot promise.
-  React.useLayoutEffect(() => {
-    if (!tabs) return
+  // Keep the selected option inside the strip and clear of the chevrons.
+  // Only the strip scrolls: the page never moves, which scrollIntoView cannot
+  // promise. A strip that does not overflow ignores the assignment.
+  const valueRef = React.useRef(value)
+  valueRef.current = value
+  const revealSelected = React.useCallback(() => {
     const strip = stripRef.current
-    const option = optionRefs.current.get(value)
-    if (strip && option) {
+    const option = optionRefs.current.get(valueRef.current)
+    if (strip && option && strip.scrollWidth > strip.clientWidth) {
+      const style = getComputedStyle(strip)
+      // offsetLeft/offsetWidth round to whole pixels while the tab is fractional (a 101.42 px tab overlapped the
+      // chevron by 0.66 px at 390 px), so keep a small gap beside each cue rather than touching its edge.
+      const gap = 4
+      const reserveStart = SCROLL_CUE_SIZE + gap + (Number.parseFloat(style.paddingLeft) || 0)
+      const reserveEnd = SCROLL_CUE_SIZE + gap + (Number.parseFloat(style.paddingRight) || 0)
       const start = option.offsetLeft
       const end = start + option.offsetWidth
-      if (start < strip.scrollLeft + TAB_EDGE_FADE) {
-        strip.scrollLeft = Math.max(0, start - TAB_EDGE_FADE)
-      } else if (end > strip.scrollLeft + strip.clientWidth - TAB_EDGE_FADE) {
-        strip.scrollLeft = end - strip.clientWidth + TAB_EDGE_FADE
+      if (start - reserveStart < strip.scrollLeft) {
+        strip.scrollLeft = Math.max(0, start - reserveStart)
+      } else if (end + reserveEnd > strip.scrollLeft + strip.clientWidth) {
+        strip.scrollLeft = end + reserveEnd - strip.clientWidth
       }
     }
     measureOverflow()
-  }, [tabs, value, options.length, measureOverflow])
+  }, [measureOverflow])
 
+  React.useLayoutEffect(revealSelected, [value, options.length, revealSelected])
+
+  // The strip's own size and its options' sizes (late web fonts, a changed
+  // label or adornment) move both the selected option and the overflow edges.
   React.useEffect(() => {
-    if (!tabs || typeof ResizeObserver === "undefined") return
+    if (typeof ResizeObserver === "undefined") return
     const strip = stripRef.current
     if (!strip) return
-    const observer = new ResizeObserver(measureOverflow)
+    const observer = new ResizeObserver(revealSelected)
     observer.observe(strip)
+    for (const option of optionRefs.current.values()) observer.observe(option)
     return () => observer.disconnect()
-  }, [tabs, measureOverflow])
+  }, [optionKey, revealSelected])
+
+  const page = (direction: 1 | -1) => {
+    const strip = stripRef.current
+    if (!strip) return
+    const reduce = typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
+    strip.scrollBy({ left: direction * strip.clientWidth * 0.75, behavior: reduce ? "auto" : "smooth" })
+  }
 
   const hasMatch = options.some((o) => o.value === value)
 
@@ -161,16 +220,17 @@ export function SegmentedControl<T extends string = string>({
       data-overflow-end={overflow.end || undefined}
       ref={stripRef}
       onKeyDown={handleKeyDown}
-      onScroll={tabs ? measureOverflow : undefined}
+      onScroll={measureOverflow}
       className={cn(
-        "flex gap-1",
+        "relative flex gap-1",
         variant === "row" &&
           "flex-wrap items-center rounded-lg border border-[var(--field-border)] bg-[var(--well)] p-1",
         variant === "tabs" &&
-          ["relative flex-nowrap items-end border-b border-border pb-0 overflow-x-auto", tabEdgeFade],
+          "flex-nowrap items-end border-b border-border pb-0 overflow-x-auto",
         className,
       )}
     >
+      {overflow.start && <ScrollCue side="start" onPage={() => page(-1)} />}
       {options.map((option, i) => {
         const active = option.value === value
         const focusable = active || (!hasMatch && i === 0)
@@ -214,6 +274,7 @@ export function SegmentedControl<T extends string = string>({
           </button>
         )
       })}
+      {overflow.end && <ScrollCue side="end" onPage={() => page(1)} />}
     </div>
   )
 }