@godxjp/ui 18.15.3 → 19.0.0

package/dist/components/ui/toggle.js

@@ -1,9 +1,10 @@
 "use client";
-import { jsx } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import * as TogglePrimitive from "@radix-ui/react-toggle";
 import { cva } from "class-variance-authority";
 import { cn } from "../../lib/utils.js";
+import { useTranslation } from "../../i18n/use-translation.js";
 const toggleVariants = cva("ui-toggle", {
   variants: {
     variant: {
@@ -21,17 +22,71 @@ const toggleVariants = cva("ui-toggle", {
     size: "md"
   }
 });
-const Toggle = React.forwardRef(({ className, variant, size, ...props }, ref) => /* @__PURE__ */ jsx(
-  TogglePrimitive.Root,
-  {
-    ref,
-    "data-slot": "toggle",
-    className: cn(toggleVariants({ variant, size }), className),
+function useCounterPill({
+  count,
+  overflowCount = 99,
+  showZero = true,
+  countLabel,
+  ariaLabel
+}) {
+  const { locale } = useTranslation();
+  const visible = count != null && (count !== 0 || showZero);
+  const formatted = React.useMemo(() => {
+    if (count == null) return "";
+    const format = new Intl.NumberFormat(locale);
+    return count > overflowCount ? `${format.format(overflowCount)}+` : format.format(count);
+  }, [count, locale, overflowCount]);
+  if (!visible) {
+    return { pill: null, resolvedAriaLabel: ariaLabel };
+  }
+  const spoken = countLabel ? `${formatted} ${countLabel}` : formatted;
+  return {
+    pill: /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx("span", { "data-slot": "toggle-count", className: "ui-toggle-count", "aria-hidden": "true", children: formatted }),
+      /* @__PURE__ */ jsx("span", { className: "sr-only", children: `, ${spoken}` })
+    ] }),
+    resolvedAriaLabel: ariaLabel == null ? ariaLabel : `${ariaLabel}, ${spoken}`
+  };
+}
+const Toggle = React.forwardRef(
+  ({
+    className,
+    variant,
+    size,
+    count,
+    overflowCount,
+    showZero,
+    countLabel,
+    children,
+    "aria-label": ariaLabel,
     ...props
+  }, ref) => {
+    const { pill, resolvedAriaLabel } = useCounterPill({
+      count,
+      overflowCount,
+      showZero,
+      countLabel,
+      ariaLabel
+    });
+    return /* @__PURE__ */ jsxs(
+      TogglePrimitive.Root,
+      {
+        ref,
+        "data-slot": "toggle",
+        "aria-label": resolvedAriaLabel,
+        className: cn(toggleVariants({ variant, size }), className),
+        ...props,
+        children: [
+          children,
+          pill
+        ]
+      }
+    );
   }
-));
+);
 Toggle.displayName = TogglePrimitive.Root.displayName;
 export {
   Toggle,
-  toggleVariants
+  toggleVariants,
+  useCounterPill
 };

package/dist/i18n/messages/en.json

@@ -213,6 +213,14 @@
     }
   },
   "dataDisplay": {
+    "avatar": {
+      "presence": {
+        "online": "Online",
+        "away": "Away",
+        "busy": "Busy",
+        "offline": "Offline"
+      }
+    },
     "carousel": {
       "roleDescription": "carousel",
       "ariaLabel": "Carousel",

package/dist/i18n/messages/ja.json

@@ -207,6 +207,14 @@
     }
   },
   "dataDisplay": {
+    "avatar": {
+      "presence": {
+        "online": "オンライン",
+        "away": "離席中",
+        "busy": "取り込み中",
+        "offline": "オフライン"
+      }
+    },
     "carousel": {
       "roleDescription": "カルーセル",
       "ariaLabel": "カルーセル",

package/dist/i18n/messages/vi.json

@@ -207,6 +207,14 @@
     }
   },
   "dataDisplay": {
+    "avatar": {
+      "presence": {
+        "online": "Trực tuyến",
+        "away": "Vắng mặt",
+        "busy": "Bận",
+        "offline": "Ngoại tuyến"
+      }
+    },
     "carousel": {
       "roleDescription": "băng chuyền",
       "ariaLabel": "Băng chuyền",

package/dist/lib/control-styles.d.ts

@@ -1,6 +1,20 @@
 /** Shared control sizing — reads `--control-height`, `--font-size-*` from density / theme. */
 export declare const controlFieldClass = "ui-control w-full rounded-[var(--control-radius)] border border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring/25 disabled:cursor-not-allowed disabled:opacity-50";
 export declare const controlMultilineClass = "ui-control-multiline w-full rounded-[var(--control-radius)] border border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring/25 disabled:cursor-not-allowed disabled:opacity-50";
+/**
+ * Multiline control with its own chrome removed, for a textarea EMBEDDED in a surface that
+ * already draws the box — a chat composer inside a Card, an inline edit cell, a comment box in
+ * a panel. Two nested rounded borders is the tell that this was missing.
+ *
+ * These are utilities, not tokens, ON PURPOSE. `.ui-control-multiline` reads
+ * `--control-border-width` / `--control-shadow` from `@layer components`, but the default class
+ * ALSO carries Tailwind's `border` in `@layer utilities`, which wins whatever the token says —
+ * the same structural inertness gh#260 found on Badge's font size. So the variant cannot be a
+ * token override by a consumer; it has to drop the utilities here.
+ *
+ * The focus ring goes with them: the surface owns focus, via `focus-within` on the wrapper.
+ */
+export declare const controlMultilineGhostClass = "ui-control-multiline w-full min-h-0 border-0 bg-transparent shadow-none placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-0 disabled:cursor-not-allowed disabled:opacity-50";
 /**
  * Open-state ring for popup-style triggers (Select / Cascader / TreeSelect / SearchSelect).
  * Radix moves focus INTO the popup on open, so the trigger loses `:focus-visible` and — without

package/dist/lib/control-styles.js

@@ -1,5 +1,6 @@
 const controlFieldClass = "ui-control w-full rounded-[var(--control-radius)] border border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring/25 disabled:cursor-not-allowed disabled:opacity-50";
 const controlMultilineClass = "ui-control-multiline w-full rounded-[var(--control-radius)] border border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring/25 disabled:cursor-not-allowed disabled:opacity-50";
+const controlMultilineGhostClass = "ui-control-multiline w-full min-h-0 border-0 bg-transparent shadow-none placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-0 disabled:cursor-not-allowed disabled:opacity-50";
 const controlOpenRingClass = "data-[state=open]:border-ring data-[state=open]:ring-ring/50 data-[state=open]:ring-[3px]";
 const controlTriggerClass = "ui-control flex w-full items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] border border-input bg-background shadow-sm transition-[color,box-shadow] focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring/25 data-[state=open]:border-ring data-[state=open]:ring-ring/50 data-[state=open]:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1";
 const controlIconClass = "size-[length:var(--control-height)] shrink-0";
@@ -21,6 +22,7 @@ export {
   controlIconLeadingClass,
   controlIconSmClass,
   controlMultilineClass,
+  controlMultilineGhostClass,
   controlOpenRingClass,
   controlTriggerClass,
   tableCellPaddingClass,

package/dist/props/components/data-display.prop.d.ts

@@ -1,6 +1,6 @@
 /** Data Display component prop types — @see docs/COMPONENTS.md#data-display */
 import type * as React from "react";
-import type { ActionProp, ClassNameProp, DescriptionProp, IconProp, TitleProp, ColumnDefProp, GetRowIdProp, OnRowClickProp, OnSelectChangeProp, OnSortChangeProp, OnTableDensityChangeProp, SelectedIdsProp, SortStateProp, TableDensityProp, TablePresetProp, BreakpointProp, DensityProp, ChildrenProp, ToneProp, AvatarShapeProp, HeadingLevelProp, HandlerProp, SizeProp, LabelProp, IdProp } from "../vocabulary/index.js";
+import type { ActionProp, ClassNameProp, DescriptionProp, IconProp, TitleProp, ColumnDefProp, GetRowIdProp, OnRowClickProp, OnSelectChangeProp, OnSortChangeProp, OnTableDensityChangeProp, SelectedIdsProp, SortStateProp, TableDensityProp, TablePresetProp, BreakpointProp, DensityProp, ChildrenProp, ToneProp, AvatarShapeProp, HeadingLevelProp, HandlerProp, SizeProp, LabelProp, IdProp, DescriptionsLayoutProp } from "../vocabulary/index.js";
 /** @see EmptyState */
 /**
  * Semantic intent of the EmptyState icon medallion — a subset of the shared `ToneProp` vocabulary
@@ -39,10 +39,19 @@ export type EmptyStateProp = {
     titleAs?: "h1" | "h2" | "h3" | "h4" | "p" | "div";
     className?: ClassNameProp;
 };
-/** @see Descriptions */
+/**
+ * @see Descriptions — composed with `Descriptions.Item` CHILDREN, not an `items` array.
+ * This type had drifted from the component (it described a long-gone items-based API and was
+ * missing `layout`/`labelAlign` entirely, which the generated manifest already listed).
+ */
 export type DescriptionsProp = {
-    items: DescriptionsItemProp[];
+    /** `Descriptions.Item` children — one label/value pair each. */
+    children: React.ReactNode;
     columns?: 1 | 2 | 3;
+    /** Label placement within each item. Default `vertical` (label over value). */
+    layout?: DescriptionsLayoutProp;
+    /** Label text alignment inside the label column. Applies only to `layout="horizontal"`. */
+    labelAlign?: "start" | "end";
     className?: ClassNameProp;
 };
 export type DescriptionsItemProp = {
@@ -63,9 +72,45 @@ export type DescriptionsItemProp = {
 export type AvatarProp = React.ComponentPropsWithoutRef<"span"> & {
     shape?: AvatarShapeProp;
     appearance?: AvatarAppearanceProp;
+    /**
+     * Presence — WHO is reachable right now, drawn as an indicator at the block-end/inline-end
+     * corner of the mark with a localized `sr-only` label folded into the avatar's accessible text.
+     * Never colour alone (WCAG 1.4.1): each value also has its own silhouette (filled · half-filled ·
+     * barred · hollow).
+     *
+     * OMIT the prop entirely for an entity that has no presence concept (an organization mark, a
+     * capability medallion) — an absent prop emits no node and no attribute, so the DOM stays
+     * byte-identical to today's. Pass `"offline"` for a person KNOWN to be unreachable; that is a
+     * different statement, exactly as `ListRow`'s omitted vs `false` `unread` is.
+     */
+    presence?: AvatarPresenceProp;
+    /**
+     * Override the localized presence text (`t("dataDisplay.avatar.presence.online")` …) when the
+     * product has a more precise phrasing ("In a meeting until 15:00"). Visually hidden either way —
+     * a presence dot never carries visible text; that is `Badge status`.
+     */
+    presenceLabel?: LabelProp;
     className?: ClassNameProp;
     children?: ChildrenProp;
 };
+/**
+ * Avatar presence status — a person's realtime reachability.
+ *
+ * A DELIBERATELY separate vocabulary from the lifecycle `BadgeStatusProp`: presence is volatile,
+ * per-person and pushed over a socket, while a lifecycle status is a record's state and renders as
+ * a labelled chip. Each value is encoded twice over — a semantic role colour AND a shape — so the
+ * four are told apart in greyscale, by a deuteranope and under forced colors:
+ *
+ * - `"online"` — filled disc (`--success`).
+ * - `"away"` — half-filled disc (`--warning`).
+ * - `"busy"` — filled disc cut by a horizontal bar, the do-not-disturb mark (`--destructive`).
+ * - `"offline"` — hollow ring (`--muted-foreground`).
+ *
+ * Retune every constant with `--avatar-presence-*`.
+ *
+ * @see Avatar
+ */
+export type AvatarPresenceProp = "online" | "away" | "busy" | "offline";
 /**
  * Avatar fill treatment.
  *
@@ -295,3 +340,40 @@ export type PermissionMatrixProp = {
     className?: ClassNameProp;
     id?: IdProp;
 };
+/**
+ * Edge the ScrollArea viewport sticks to as its content grows (gh#311).
+ *
+ * - `none` — the scroll offset is left entirely alone. This is the default and is exactly the
+ *   behaviour a ScrollArea has always had.
+ * - `bottom` — a live stream (chat, log tail, streaming response, activity feed). While the reader
+ *   is within `anchorOffset` of the bottom, arriving content keeps the newest item in view; once
+ *   they scroll away to read history, growth NEVER moves them, and content inserted ABOVE the
+ *   read position is compensated so the item under their eyes stays put.
+ */
+export type ScrollAreaAnchorProp = "none" | "bottom";
+/** @see ScrollArea */
+export type ScrollAreaProp = {
+    /**
+     * Ref to the element that actually SCROLLS — the Radix viewport — not the root. The root is
+     * `overflow: hidden` and never scrolls, so the component's own `ref` cannot serve. Use this to
+     * read `scrollTop`/`scrollHeight`, call `scrollTo()`, restore a saved position, or drive a
+     * "jump to newest" button. It is the typed, supported alternative to querying the Radix-internal
+     * `[data-radix-scroll-area-viewport]` attribute, which is not a public contract and is ambiguous
+     * the moment two ScrollAreas nest.
+     */
+    viewportRef?: React.Ref<HTMLDivElement>;
+    /** Edge the viewport sticks to as content grows. Default `none` (inert). */
+    anchor?: ScrollAreaAnchorProp;
+    /**
+     * Distance in px from the bottom edge inside which the reader still counts as "at the bottom"
+     * for `anchor="bottom"`. Defaults to the `--scroll-area-anchor-offset` token (3rem), read off
+     * the element at mount so a theme — or a `[data-tenant]` scope — moves it globally.
+     */
+    anchorOffset?: number;
+    /**
+     * Fires when the pinned state flips: `false` when the reader scrolls away from the bottom,
+     * `true` when they come back inside `anchorOffset`. Render a focusable "jump to newest" button
+     * from it — anchoring must never be the only route back to new content.
+     */
+    onAnchoredChange?: (anchored: boolean) => void;
+};

package/dist/props/components/data-entry.prop.d.ts

@@ -40,6 +40,14 @@ export type TextareaProp = React.TextareaHTMLAttributes<HTMLTextAreaElement> & {
     allowClear?: boolean;
     /** Called after the field is cleared via the inline ✕. */
     onClear?: () => void;
+    /** `ghost` drops the field's own border/background/ring for a textarea inside a surface that already draws the box. */
+    variant?: "default" | "ghost";
+    /** Grow the box with its content between `minRows` and `maxRows` instead of a fixed `rows` height (default false). */
+    autoGrow?: boolean;
+    /** Floor in text rows while `autoGrow`; never undercuts the `--control-height` tier. */
+    minRows?: number;
+    /** Ceiling in text rows while `autoGrow` — past it the control scrolls internally. `0` = unbounded. */
+    maxRows?: number;
 };
 /**
  * @see NumberInput — localized numeric spinbutton (composes `Input` + step `Button`s).
@@ -529,6 +537,15 @@ export type UploadProp = FieldA11yProps & {
      * @see Button — same size scale
      */
     triggerSize?: "default" | "md" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg";
+    /**
+     * `variant="button"` only — the visual weight of the visible trigger, forwarded to Button.
+     * Defaults to `outline`, which is right for a standalone form field. Pass `ghost` when the
+     * trigger sits in a toolbar row beside other icon buttons — inside a chat composer, say —
+     * where a bordered square reads as the odd one out.
+     *
+     * @see Button — same variant scale
+     */
+    triggerVariant?: "default" | "destructive" | "outline" | "dashed" | "secondary" | "ghost" | "link";
     className?: ClassNameProp;
     children?: React.ReactNode;
 };

package/dist/props/components/general.prop.d.ts

@@ -1,6 +1,6 @@
 /** Foundation component prop types — @see docs/COMPONENTS.md#foundation */
 import type * as React from "react";
-import type { AsChildProp, ButtonSizeProp, ButtonVariantProp, ChildrenProp, ClassNameProp, DisabledProp, FontWeightProp, HeadingLevelProp, OnClickProp, PendingProp, RevealDelayProp, ShapeProp, TextAlignProp, TextSizeProp, TextToneProp } from "../vocabulary/index.js";
+import type { ActivityAnnounceProp, ActivityVariantProp, AsChildProp, ButtonSizeProp, ButtonVariantProp, ChildrenProp, ClassNameProp, DisabledProp, FontWeightProp, HeadingLevelProp, LabelProp, OnClickProp, PendingProp, RevealDelayProp, ShapeProp, SizeProp, TextAlignProp, TextSizeProp, TextToneProp } from "../vocabulary/index.js";
 /** @see Text — typographic primitive; replaces hand-rolled `<span className="text-[13px] …">`. */
 export type TextProp = Omit<React.HTMLAttributes<HTMLElement>, "color"> & {
     /** Render element. Default `span`. Covers inline/block text + description-list + code/caption. */
@@ -100,3 +100,54 @@ export type RevealProp = React.HTMLAttributes<HTMLDivElement> & {
     asChild?: AsChildProp;
     className?: ClassNameProp;
 };
+/**
+ * @see Activity — the official AMBIENT-motion primitive (a continuous, unbounded "in progress"),
+ * the LOOP counterpart to `Reveal`'s one-shot entrance. Reads the DS motion tokens
+ * (`--activity-interval`, `--activity-stagger-step`, `--ease-standard`, `--activity-mark-offset`)
+ * so a consumer never hand-rolls a looping `@keyframes`. Under `prefers-reduced-motion` the loop is
+ * dropped and the mark renders in a static, fully-visible resting state — three solid dots, a solid
+ * pulse mark, or a bar segment parked at the reading-start — with no layout shift, the same
+ * guarantee `Reveal` gives.
+ *
+ * NOT `Skeleton` (content is loading — `aria-busy` + an unconditional live region), NOT
+ * `Button loading` (this action is in flight). `Activity` means: something is happening,
+ * indefinitely, elsewhere — someone typing, a sync running, a response streaming, a recording live.
+ *
+ * There is deliberately no `asChild`: unlike `Reveal` (which owns no DOM), `Activity` renders its
+ * own mark structure, so there is no single child to merge onto.
+ */
+export type ActivityProp = Omit<React.HTMLAttributes<HTMLSpanElement>, "color"> & {
+    /**
+     * The mark. Default `dots` — three dots rising in sequence, the ellipsis convention.
+     * `pulse` is a single breathing mark (live / recording); `bar` an indeterminate sweep (syncing).
+     */
+    variant?: ActivityVariantProp;
+    /**
+     * Size step, the standard ladder. Default `sm` — an ambient mark is never the loudest thing on
+     * screen. Scales the mark AND the label together (the mark is `em`-based).
+     */
+    size?: SizeProp;
+    /** Semantic colour intent. Default `muted` — ambient, not an alert. */
+    tone?: TextToneProp;
+    /**
+     * Localized description of WHAT is happening ("Hưng đang nhập…", "同期中…"). Rendered as visible
+     * `Text` beside the mark when `children` are absent; when `children` ARE present it becomes an
+     * `sr-only` description instead, so the indicator is never animation-only. Consumer-owned copy —
+     * the library never invents it, and the plural form of "N people are typing" must come from the
+     * consumer's `Intl.PluralRules`.
+     */
+    label?: LabelProp;
+    /**
+     * Richer visible content in place of `label` (a name in a `<strong>`, a `Badge`, …). The mark
+     * stays `aria-hidden`; pass `label` alongside for the sr-only description.
+     */
+    children?: ChildrenProp;
+    /**
+     * Announce the label to assistive technology. Default `false` — the DELIBERATE default, because
+     * an ambient indicator that fires a live region on every socket event is a screen-reader flood.
+     * With `false` NO live region is emitted at all. `"polite"` wraps ONLY the label in a single
+     * `aria-live="polite" aria-atomic="true"` region; the mark stays outside it and `aria-hidden`.
+     */
+    announce?: ActivityAnnounceProp;
+    className?: ClassNameProp;
+};

package/dist/props/components/layout.prop.d.ts

@@ -1,7 +1,7 @@
 /** Layout component prop types — @see docs/COMPONENTS.md#layout */
 import type * as React from "react";
 import type { ComponentType, ReactNode, SVGProps } from "react";
-import type { BreadcrumbProp, TitleProp, SubtitleProp, StatusProp, ExtraProp, FooterProp, PageDensityProp, PageContainerVariantProp, CenteredShellWidthProp, CenteredShellAlignProp, CenteredShellPresetProp, ErrorSurfaceModeProp, ErrorSurfaceStatusProp, AuthShellPresetProp, BreakpointProp, GapProp, ClassNameProp, ChildrenProp, IdProp, DisabledProp, DescriptionProp, ActionProp, IconProp, HeadingLevelProp } from "../vocabulary/index.js";
+import type { BreadcrumbProp, TitleProp, SubtitleProp, StatusProp, ExtraProp, FooterProp, PageDensityProp, PageContainerVariantProp, CenteredShellWidthProp, CenteredShellAlignProp, CenteredShellPresetProp, ErrorSurfaceModeProp, ErrorSurfaceStatusProp, AuthShellPresetProp, OrientationProp, TextAlignProp, TextToneProp, BreakpointProp, GapProp, ClassNameProp, ChildrenProp, IdProp, DisabledProp, DescriptionProp, ActionProp, IconProp, HeadingLevelProp, ToneProp } from "../vocabulary/index.js";
 import type { EmptyStateToneProp } from "./data-display.prop.js";
 /**
  * Arrangement of the page header's title band and its `extra` slot below the 640px step.
@@ -24,6 +24,22 @@ export type PageContainerPresetProp = "default" | "admin-collection";
  * fluid at the compact gutter.
  */
 export type PageContainerMeasureProp = "default" | "narrow" | "medium";
+/**
+ * What the page's top row IS — the question that decides its type step, not how big you want it.
+ *
+ * `document` (default) — the row is the page's TITLE: a record, a form, a collection, a report.
+ * The `<h1>` takes `--page-title-font-size` and the existing responsive step down at 720px.
+ *
+ * `chrome` — the row is the surface's own furniture: a chat channel name, a mail subject line, an
+ * IDE tab, a conversation header. It names the thing you are already inside rather than announcing
+ * a document, so it takes the body type step (`--page-title-font-size-chrome`) and the header band
+ * stops competing with the content underneath. Orthogonal to `PageContainerVariantProp`: `ghost`
+ * owns the page's chrome WEIGHT (no divider, no header bottom pad), this owns what the title MEANS
+ * — a chat page usually wants both, a quiet document feed wants only `ghost`.
+ *
+ * The `<h1>` stays an `<h1>` either way; only the type step moves, and only via a token.
+ */
+export type PageContainerHeaderScaleProp = "document" | "chrome";
 /** @see PageContainer */
 export type PageContainerProp = {
     title: TitleProp;
@@ -47,6 +63,18 @@ export type PageContainerProp = {
      */
     headerLoading?: boolean;
     extra?: ExtraProp;
+    /**
+     * FIXED chrome band between the page header and the scrolling body — a filter strip, a status
+     * bar, a "channel workflow" rail. It is a first-class page-chrome slot precisely because the
+     * only alternative was hand-laying `position: sticky` at the call site (which the design system
+     * forbids) or putting the strip inside the body, where it scrolls away. Under `fill` the body
+     * IS the scroll viewport, so this band is a plain `flex: none` sibling OUTSIDE it — content can
+     * never travel underneath it the way it does under a sticky box. Shares the page gutters and
+     * the `measure` cap with the header and the body, so the three bands line up on both edges; its
+     * inset and bottom rule are token-owned (`--page-toolbar-pad-block` / `--page-toolbar-divider`).
+     * Omit it and NOTHING is rendered — no wrapper element, no gap.
+     */
+    toolbar?: ReactNode;
     footer?: FooterProp;
     breadcrumb?: BreadcrumbProp;
     /**
@@ -75,6 +103,37 @@ export type PageContainerProp = {
      * `--page-header-extra-measure`. At >=640px both arrangements are identical.
      */
     headerLayout?: PageContainerHeaderLayoutProp;
+    /**
+     * Whether the page's top row is a DOCUMENT TITLE or the surface's own CHROME. Defaults to
+     * `document` — the historical page, byte-identical (no attribute is emitted at all). Pass
+     * `chrome` when the row names the thing the user is already inside rather than announcing a
+     * document: a chat channel, a mail thread, an IDE tab. The `<h1>` then takes the body type step
+     * (`--page-title-font-size-chrome`) at EVERY width — including below 720px, where the
+     * document-scale responsive step would otherwise pull it back UP — so the header band stops
+     * eating the height the conversation needs (measured in a consumer chat page: a 61px band with a
+     * 24px name, against a design that wanted ~40px at the `sm` step).
+     *
+     * The same answer also puts the band ON the frame's edge: the container's block-start padding
+     * becomes `--page-pad-block-start-chrome` (0) instead of `--space-page-active-y`, because a
+     * document title needs air above it and a channel head IS the top edge (measured on a consumer
+     * chat screen as 24px that pushed the head off y=0 and came off the transcript viewport). The
+     * page's bottom edge is untouched, that being `stickyFooter`'s.
+     *
+     * It carries two more consequences of the same fact. The SUBTITLE drops to
+     * `--page-subtitle-font-size-chrome` (`--font-size-2xs`, ≈11px): a caption on chrome, not a
+     * document's standfirst, and at the document step it was rendering at the very same size as the
+     * chrome title, which is not a hierarchy. And the `extra` cluster CENTRES on the bar
+     * (`align-self: center`) wherever the header row is a row (>=640px), because top-packing actions
+     * is a document behaviour — they belong on the first line of a tall `<h1>` — and a bar has no
+     * tall heading to align to. Measured on a consumer chat screen, that was 8.65px: 28px icon
+     * buttons pinned at y=14 inside a 45.3px row whose title block centred at y=22.65.
+     *
+     * The heading stays an `<h1>` throughout, so the screen-reader outline is unchanged. Compose it
+     * with `variant="ghost"` for the full quiet chrome header (ghost drops the divider and the
+     * header's bottom pad); the two are separate props because chrome WEIGHT and what the title
+     * MEANS are separate questions.
+     */
+    headerScale?: PageContainerHeaderScaleProp;
     /**
      * Bounded page measure shared by the header and the body. Defaults to `default` — no cap, the
      * historical fluid page. `narrow` (624px surface) / `medium` (720px surface) cap BOTH bands to
@@ -314,7 +373,52 @@ export type AuthShellProp = {
     density?: "comfortable" | "compact";
     className?: ClassNameProp;
 };
-/** @see AuthDivider */
+/**
+ * @see Separator — the tokenized rule, optionally INTERRUPTED by a localized label.
+ *
+ * With no `label` the DOM, the `data-slot="separator"` and the `.ui-separator` class are exactly
+ * what they have always been: an inert Radix rule, `decorative` by default, nothing announced.
+ * With a `label` the root becomes the three-cell grid `rule · label · rule` and, because
+ * "new messages" is CONTENT rather than decoration, a real `role="separator"` carrying the label
+ * as its accessible name (gh#308). Every constant — rule weight, label gap, label inset, label
+ * type ramp, rule and label colour per tone — is a `--separator-*` component token (rules #44/#45),
+ * so a service retunes a day divider or an unread watermark from its theme and never forks CSS.
+ */
+export type SeparatorProp = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Rule axis. Default `"horizontal"`. */
+    orientation?: OrientationProp;
+    /**
+     * Localized text that INTERRUPTS the rule — a day divider, a "new messages" watermark, an auth
+     * conjunction. The rule splits into two halves around it and the grid keeps the label optically
+     * placed regardless of translation length. `horizontal` only: with `orientation="vertical"` the
+     * label is ignored and dev builds warn. Omit for a plain rule.
+     *
+     * A `string`, not the `LabelProp` ReactNode, because this text IS the separator's accessible
+     * name — a node cannot be announced. The library never invents the copy: the consumer passes a
+     * `t()` string, and a date is formatted with `Intl.DateTimeFormat` on the active locale.
+     */
+    label?: string;
+    /**
+     * Where the label sits on the rule. Default `"center"` (the classic conjunction). `"start"` is
+     * the Slack/Mattermost stream convention — the label hugs the inline-start edge with the long
+     * half of the rule running to the inline-end. Logical, so it flips under `dir="rtl"`.
+     */
+    labelAlign?: TextAlignProp;
+    /**
+     * Semantic emphasis of the label AND the rule together — `"default"` is the quiet chrome (#44);
+     * a semantic role marks an attention rule such as an unread watermark. Never colour-only: the
+     * tone re-points both halves, so the distinction survives forced-colors. Default `"default"`.
+     */
+    tone?: TextToneProp;
+    /**
+     * `true` (the default for an UNLABELLED rule) keeps Radix's decorative behaviour — `role="none"`,
+     * nothing announced. A `label` flips the default to `false`, so the rule becomes a real
+     * `role="separator"` named by the label. Pass it explicitly to override either default.
+     */
+    decorative?: boolean;
+    className?: ClassNameProp;
+};
+/** @see AuthDivider — the auth-scoped preset over `Separator label` (gh#308). */
 export type AuthDividerProp = {
     /** Short localized conjunction rendered between the two separator rules (for example, "or"). */
     label: string;
@@ -528,6 +632,22 @@ export type SidebarProductProp = {
     role?: string;
     color?: string;
 };
+/**
+ * What a nav row's count MEANS — a subset of the shared `ToneProp` vocabulary, not a palette.
+ *
+ * `neutral` (default) — a plain count: unread items, pending rows, queued jobs. The pill keeps the
+ * quiet `--sidebar-badge-background` / `-foreground` pair it always had.
+ *
+ * `destructive` — the count is ADDRESSED TO THE USER and the rail should pull the eye: an
+ * @mention, a direct message, a failing job awaiting them. Reads the
+ * `--sidebar-badge-destructive-*` pair.
+ *
+ * Deliberately TWO values, not the whole `ToneProp` union: a navigation rail answers one question
+ * about a count — "does this need me personally?" — and a five-colour rail is decoration, not
+ * information. Colour ONLY: the pill's geometry is shared, so a mention row and an unread row stay
+ * aligned in the same column.
+ */
+export type SidebarBadgeToneProp = Extract<ToneProp, "neutral" | "destructive">;
 /** @see Sidebar */
 export type SidebarItemProp = {
     id: string;
@@ -540,7 +660,22 @@ export type SidebarItemProp = {
      * `--sidebar-nav-icon-foreground` (see {@link SidebarProp}).
      */
     icon: ComponentType<SVGProps<SVGSVGElement>>;
+    /**
+     * Count/status affix rendered in the row's `.sb-badge` pill. Pass the CONTENT ONLY — a number, a
+     * string, `"9+"`. Never a `<Badge>`: the row already IS a badge, so nesting one produces two
+     * stacked pills (measured: a 37.11×19.14 `.sb-badge` wrapping a 25.11×19.14 `<Badge>` with its
+     * own border). To change what the count MEANS, use {@link SidebarItemProp.badgeTone}.
+     */
     badge?: ReactNode;
+    /**
+     * Emphasis of `badge`. Defaults to `neutral` — the historical pill, byte-identical (no attribute
+     * is emitted at all). Pass `destructive` when the count is addressed to the user rather than
+     * merely unread: an @mention, a direct message, a failure waiting on them. It moves two colour
+     * tokens and nothing else, so mention rows and unread rows still line up.
+     *
+     * Ignored when `badge` is absent, and on the collapsed rail (which hides `.sb-badge` entirely).
+     */
+    badgeTone?: SidebarBadgeToneProp;
     disabled?: boolean;
     /**
      * Destination of the row. It is the SOLE interactive element (no nested `<button>`), so