@caqophony/ui 0.1.0 → 0.2.0

package/README.md

@@ -41,7 +41,9 @@ ships, after Tailwind, in your global CSS:
 @import '@caqophony/ui/styles.css';
 ```
 
-`styles.css` defines the token variables (light and `.dark`), maps them to
+`styles.css` defines the token variables (light, and dark under
+`@media (prefers-color-scheme: dark)`, the same OS setting Tailwind v4's `dark:`
+variant follows), maps them to
 Tailwind v4 colour/radius/z-index/opacity/duration utilities and registers the
 package's built files as a Tailwind `@source`. Override any `--token` after the
 import to re-theme.

package/dist/{chunk-K3SEIIA3.js → chunk-4YA6BZDJ.js}

@@ -36,7 +36,7 @@ function getProseClasses(size, className) {
     // Emphasis/italic
     "prose-em:text-foreground dark:prose-em:text-foreground",
     // Links
-    "prose-a:text-primary dark:prose-a:text-primary prose-a:no-underline hover:prose-a:underline",
+    "prose-a:text-primary-text dark:prose-a:text-primary-text prose-a:no-underline hover:prose-a:underline",
     // Lists
     "prose-li:text-foreground dark:prose-li:text-foreground",
     // Inline code

package/dist/index.d.mts

@@ -6,6 +6,7 @@ import * as SwitchPrimitives from '@radix-ui/react-switch';
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 export { MarkdownRenderer } from './markdown.mjs';
+import * as lucide_react from 'lucide-react';
 import { LucideIcon } from 'lucide-react';
 import { ClassValue } from 'clsx';
 
@@ -286,8 +287,12 @@ interface CollapsibleSidebarProps {
     collapsedWidth?: number;
     /** Custom expanded width (default: 256px) */
     expandedWidth?: number;
+    /** Below `lg`: the menu button's and the drawer's accessible name. */
+    navLabel?: string;
+    /** Below `lg`: the drawer starts open (the style sheet draws it so). */
+    defaultNavOpen?: boolean;
 }
-declare function CollapsibleSidebar({ storageKey, defaultCollapsed, header, collapsedHeader, items, isActive, linkComponent: LinkComponent, footer, collapsedFooter, className, collapsedWidth, expandedWidth, }: CollapsibleSidebarProps): react_jsx_runtime.JSX.Element;
+declare function CollapsibleSidebar({ storageKey, defaultCollapsed, header, collapsedHeader, items, isActive, linkComponent: LinkComponent, footer, collapsedFooter, className, collapsedWidth, expandedWidth, navLabel, defaultNavOpen, }: CollapsibleSidebarProps): react_jsx_runtime.JSX.Element;
 
 interface AccordionSingleProps {
     type?: 'single';
@@ -426,6 +431,84 @@ interface DiceBearAvatarProps extends React.HTMLAttributes<HTMLDivElement>, Vari
 }
 declare const DiceBearAvatar: React.ForwardRefExoticComponent<DiceBearAvatarProps & React.RefAttributes<HTMLDivElement>>;
 
+/** Each icon name and the glyph it draws. */
+declare const ICONS: {
+    readonly 'arrow-left': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'arrow-right': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly bell: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly calendar: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly check: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'chevron-down': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'chevron-left': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'chevron-right': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'chevron-up': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'circle-alert': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'circle-check': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'clipboard-list': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly clock: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly database: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly download: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly ellipsis: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'external-link': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly eye: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'eye-off': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'file-text': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly filter: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly folder: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly heart: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly house: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly inbox: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly info: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'layout-grid': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly link: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly list: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly loader: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly lock: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'log-out': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly mail: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'map-pin': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly menu: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly package: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly pencil: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly phone: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly plus: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'refresh-cw': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly rocket: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly search: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly settings: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly star: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly tag: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly trash: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly 'triangle-alert': React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly upload: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly user: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly users: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly x: React.ForwardRefExoticComponent<Omit<lucide_react.LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+};
+type IconName = keyof typeof ICONS;
+/**
+ * The icon sizes, each a step of the spacing scale (`size-3` is 12px …
+ * `size-8` 32px): the size comes from the tokens, never lucide's 24px
+ * default (the class sets the box; the SVG's own width/height give way).
+ */
+declare const ICON_SIZES: {
+    readonly xs: "size-3";
+    readonly sm: "size-4";
+    readonly md: "size-5";
+    readonly lg: "size-6";
+    readonly xl: "size-8";
+};
+type IconSize = keyof typeof ICON_SIZES;
+interface IconProps {
+    /** One name of the closed set (`ICONS`). */
+    name: IconName;
+    /** One step of the size scale (`ICON_SIZES`). */
+    size: IconSize;
+    className?: string;
+}
+/** A decorative icon from the closed set (hidden from assistive technology). */
+declare function Icon({ name, size, className }: IconProps): React.ReactElement;
+
 interface IntentIconProps {
     intent?: 'success' | 'warning' | 'error' | 'info';
     size?: 'sm' | 'md';
@@ -731,6 +814,14 @@ declare const CommandPalette: React.ForwardRefExoticComponent<CommandPaletteProp
  *   bg-card        -> colors.card         (sidebar bg)
  *   border-border  -> colors.border       (sidebar border)
  *
+ * One-artifact W1 (#5823) — the app frame on a phone: the `sidebar`
+ * variant drew its 240px sidebar beside the content at every width, leaving
+ * a 150px column at 390px. Below `md` the sidebar now lives behind a menu
+ * button in a top bar and opens as a drawer over a scrim (`z-overlay`,
+ * Escape and the scrim close it); from `md` up it is the fixed column.
+ * The drawer is `NavDrawer` (`./nav-drawer`), shared with
+ * `CollapsibleSidebar`: one phone drawer in the library.
+ *
  * Issue #2629 — B-3: Application Shells
  * Authored by Caqophony
  */
@@ -742,6 +833,10 @@ interface AppShellProps extends React.HTMLAttributes<HTMLDivElement> {
     header?: React.ReactNode;
     sidebar?: React.ReactNode;
     detailPanel?: React.ReactNode;
+    /** `sidebar` variant: the menu button's accessible name on a phone. */
+    navLabel?: string;
+    /** `sidebar` variant: the phone drawer starts open (the style sheet draws it so). */
+    defaultNavOpen?: boolean;
 }
 declare const AppShell: React.ForwardRefExoticComponent<AppShellProps & React.RefAttributes<HTMLDivElement>>;
 
@@ -918,7 +1013,8 @@ interface ImageCardProps extends React.HTMLAttributes<HTMLDivElement> {
 declare const ImageCard: React.ForwardRefExoticComponent<ImageCardProps & React.RefAttributes<HTMLDivElement>>;
 interface StatCardExtendedProps extends React.HTMLAttributes<HTMLDivElement> {
     label: string;
-    value: string;
+    /** W1 (#5823): `null` (not measured yet) draws `EmptyValue`, never a blank. */
+    value: string | null;
     trend?: {
         direction: 'up' | 'down' | 'neutral';
         text: string;
@@ -1427,21 +1523,27 @@ declare const StatGroup: React.ForwardRefExoticComponent<StatGroupProps & React.
  *   import { DescriptionList, DescriptionItem } from '@caqophony/ui';
  *   <DescriptionList layout="side-by-side">
  *     <DescriptionItem label="Name" value="Jane Cooper" />
- *     <DescriptionItem label="Email" value="jane@example.com" />
+ *     <DescriptionItem label="Email" value={null} />   → "—"
  *   </DescriptionList>
  *
+ * One-artifact W1 (#5823): the list's `layout` is the ONE writer of every
+ * item's layout (a context; an item had its own `layout` prop that a page
+ * had to repeat on each item). An empty value (`isEmptyValue`) draws
+ * `EmptyValue`, never a blank. A long value wraps instead of running off.
+ *
  * Issue #2635 — B-9
  * Authored by Caqophony
  */
 
+type DescriptionLayout = 'stacked' | 'side-by-side' | 'grid';
 interface DescriptionListProps extends React.HTMLAttributes<HTMLDListElement> {
-    layout?: 'stacked' | 'side-by-side' | 'grid';
+    layout?: DescriptionLayout;
 }
 declare const DescriptionList: React.ForwardRefExoticComponent<DescriptionListProps & React.RefAttributes<HTMLDListElement>>;
 interface DescriptionItemProps extends React.HTMLAttributes<HTMLDivElement> {
     label: string;
+    /** Drawn as `EmptyValue` when empty (`isEmptyValue`). */
     value: React.ReactNode;
-    layout?: 'stacked' | 'side-by-side' | 'grid';
 }
 declare const DescriptionItem: React.ForwardRefExoticComponent<DescriptionItemProps & React.RefAttributes<HTMLDivElement>>;
 
@@ -1510,6 +1612,8 @@ interface AlertProps extends React.HTMLAttributes<HTMLDivElement> {
     dismissible?: boolean;
     onDismiss?: () => void;
 }
+/** The pale-tint intent styles; `IntentBadge` reads the same map (W1 #5823). */
+declare const INTENT_SUBTLE_STYLES: Record<'success' | 'warning' | 'error' | 'info', string>;
 declare const Alert: React.ForwardRefExoticComponent<AlertProps & React.RefAttributes<HTMLDivElement>>;
 
 interface EmptyStateProps {
@@ -1697,6 +1801,215 @@ interface MediaObjectProps extends React.HTMLAttributes<HTMLDivElement> {
 }
 declare const MediaObject: React.ForwardRefExoticComponent<MediaObjectProps & React.RefAttributes<HTMLDivElement>>;
 
+/** The glyph an empty value is drawn as. */
+declare const EMPTY_VALUE_GLYPH = "\u2014";
+/** A value with nothing to draw: `null`, `undefined`, `false`, or a string of only whitespace. */
+declare function isEmptyValue(value: React.ReactNode): boolean;
+interface EmptyValueProps {
+    className?: string;
+}
+declare function EmptyValue({ className }: EmptyValueProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Page patterns — the composites every bake-off tree re-created by hand
+ * (one-artifact W1, #5823). Each one owns its spacing, radius, overflow and
+ * empty states, in the project's tokens, so a page composes them and never
+ * re-decides them:
+ *
+ *   PageGutter        the page column: centred, a content width, the gutter
+ *                     (3 of 3 trees: `max-w-* mx-auto px-4 sm:px-6 py-6 …`)
+ *   PageHeading        the h1, its description, badges, actions (3 of 3)
+ *   SectionCard       a titled card section; `flush` for a list (3 of 3)
+ *   TabbedCard        a card whose top is a tab bar, its labels inset (run 7:
+ *                     the tabs sat flush against the card edge)
+ *   SidePanelLayout   main column + a side panel that stacks under it on a
+ *                     narrow screen and sticks beside it on a wide one (2 of 3)
+ *
+ * Usage:
+ *   <PageGutter>
+ *     <PageHeading title="Senior Designer" description="Acme" actions={…} />
+ *     <SidePanelLayout aside={<SectionCard title="Next action">…</SectionCard>}>
+ *       <TabbedCard tabs={<><TabBarItem active>Overview</TabBarItem>…</>}>…</TabbedCard>
+ *     </SidePanelLayout>
+ *   </PageGutter>
+ *
+ * Authored by Caqophony
+ */
+
+declare const GUTTER_WIDTHS: {
+    /** A single column of reading or a short list. */
+    readonly narrow: "max-w-content-md";
+    /** A detail or list page with a side panel. */
+    readonly default: "max-w-content-xl";
+};
+interface PageGutterProps extends React.HTMLAttributes<HTMLDivElement> {
+    width?: keyof typeof GUTTER_WIDTHS;
+}
+declare const PageGutter: React.ForwardRefExoticComponent<PageGutterProps & React.RefAttributes<HTMLDivElement>>;
+interface PageHeadingProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+    title: React.ReactNode;
+    description?: React.ReactNode;
+    /** Badges under the title (`IntentBadge`s); they wrap. */
+    meta?: React.ReactNode;
+    /** The page's actions: they sit beside the title, and under it on a phone. */
+    actions?: React.ReactNode;
+}
+declare const PageHeading: React.ForwardRefExoticComponent<PageHeadingProps & React.RefAttributes<HTMLElement>>;
+interface SectionCardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    /** Actions at the right of the title row. */
+    actions?: React.ReactNode;
+    /** `compact`: a side panel's card (smaller title, tighter padding). */
+    size?: 'default' | 'compact';
+    /** The body has no padding: a `StackedList` or a table runs edge to edge. */
+    flush?: boolean;
+}
+declare const SectionCard: React.ForwardRefExoticComponent<SectionCardProps & React.RefAttributes<HTMLDivElement>>;
+interface TabbedCardProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** The `TabBarItem`s. */
+    tabs: React.ReactNode;
+    /** The tab bar's accessible name. */
+    tabsLabel: string;
+}
+declare const TabbedCard: React.ForwardRefExoticComponent<TabbedCardProps & React.RefAttributes<HTMLDivElement>>;
+interface SidePanelLayoutProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** The side panel: a stack of compact `SectionCard`s. */
+    aside: React.ReactNode;
+    /** The panel's accessible name. */
+    asideLabel: string;
+}
+declare const SidePanelLayout: React.ForwardRefExoticComponent<SidePanelLayoutProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * IntentBadge — a record's status (stage, priority, method) as a small pill.
+ *
+ * One-artifact W1 (#5823): run 7 drew three of these by hand
+ * (`inline-flex px-3 py-1 rounded-full text-13 bg-primary-10 …`). The badge
+ * owns its shape, size and colours; a page names only the intent. The intent
+ * tints are the ones `Alert` draws (`INTENT_SUBTLE_STYLES`, one writer), so a
+ * badge and an alert of one intent match. A long value is truncated with its
+ * full text in `title`, never run off the row.
+ *
+ * Usage:
+ *   import { IntentBadge } from '@caqophony/ui';
+ *   <IntentBadge intent="success">Offer</IntentBadge>
+ *
+ * Authored by Caqophony
+ */
+
+type IntentBadgeIntent = 'neutral' | 'primary' | 'success' | 'warning' | 'error' | 'info';
+interface IntentBadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
+    intent?: IntentBadgeIntent;
+}
+declare const IntentBadge: React.ForwardRefExoticComponent<IntentBadgeProps & React.RefAttributes<HTMLSpanElement>>;
+
+interface OverflowMenuItem {
+    label: string;
+    onSelect: () => void;
+    icon?: IconName;
+    /** Drawn in the error colour (delete, remove). */
+    destructive?: boolean;
+    disabled?: boolean;
+}
+interface OverflowMenuProps {
+    /** The trigger's accessible name ("More actions"). */
+    label: string;
+    items: readonly OverflowMenuItem[];
+    /** Open on first render (the style sheet draws it open). */
+    defaultOpen?: boolean;
+    className?: string;
+}
+declare function OverflowMenu({ label, items, defaultOpen, className, }: OverflowMenuProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * StageList — where a record stands in its sequence of stages (an
+ * application's pipeline, an order's fulfilment), drawn as a vertical
+ * `Stepper` the page never configures by hand.
+ *
+ * One-artifact W1 (#5823): run 7 passed `activeStep={4}` AND `completed` on
+ * every step (two writers of one fact) and clamped the 9 steps in a scroll
+ * box that cut the line. Here ONE value, `current`, decides every step: the
+ * ones before it are complete, it is current, the rest upcoming. An
+ * `outcome` (a stage off the sequence: rejected, withdrawn) ends the list as
+ * an error step after the sequence. The list is drawn at its full height,
+ * never clamped.
+ *
+ * A `current` that is neither a stage nor an outcome is a contract fault,
+ * thrown with the value and the lists, never drawn as a guess.
+ *
+ * Usage:
+ *   <StageList
+ *     stages={[{ value: 'applied', label: 'Applied' }, …]}
+ *     outcomes={[{ value: 'rejected', label: 'Rejected' }]}
+ *     current={application.stage}
+ *   />
+ *
+ * Authored by Caqophony
+ */
+
+interface Stage {
+    value: string;
+    label: string;
+}
+interface StageListProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** The sequence, in order. */
+    stages: readonly Stage[];
+    /** Stages off the sequence that end it (rejected, withdrawn). */
+    outcomes?: readonly Stage[];
+    /** The record's stage: a `stages` or `outcomes` value. */
+    current: string;
+}
+declare const StageList: React.ForwardRefExoticComponent<StageListProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * ClampedList — a list held to a height that scrolls inside itself.
+ *
+ * One-artifact W1 (#5823): run 7 wrapped a 9-step `Stepper` in
+ * `max-h-[160px] overflow-y-auto`, which cut the stepper's line under the
+ * clip with no sign there was more. This owns the clamp: a height from the
+ * scale, the scroll, the scroll hint (`SCROLL_HINT_Y`: a chevron mark on the
+ * end edge while there is more below), and keyboard access
+ * (a scrolling region is focusable and named, WCAG 2.1.1). A page never
+ * writes `max-h-*` with `overflow-*` around a library component.
+ *
+ * Usage:
+ *   import { ClampedList } from '@caqophony/ui';
+ *   <ClampedList label="Activity" maxHeight="md">…</ClampedList>
+ *
+ * Authored by Caqophony
+ */
+
+declare const MAX_HEIGHTS: {
+    readonly sm: "max-h-48";
+    readonly md: "max-h-72";
+    readonly lg: "max-h-96";
+};
+interface ClampedListProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** The region's accessible name. */
+    label: string;
+    maxHeight?: keyof typeof MAX_HEIGHTS;
+}
+declare const ClampedList: React.ForwardRefExoticComponent<ClampedListProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * One-artifact W1 (#5823) — the scroll hint: the ONE writer of how a box
+ * that scrolls says there is more. The last 1.5rem of the box (its end edge)
+ * fades out through a mask (3rem for a vertical box, below); the box carries
+ * the same length of end padding,
+ * so when nothing is clipped only that empty padding fades, and when content
+ * runs past the edge the clipped item fades, which is the hint.
+ *
+ * Static CSS (no script, no animation): it shows in a server render and in a
+ * still capture alike. A mask is surface-agnostic (no gradient in a guessed
+ * background colour). The style sheet's `scrollHint` check fails on a box
+ * that overflows on an axis it scrolls without one of these.
+ *
+ * Authored by Caqophony
+ */
+/** A horizontally scrolling box (a tab bar). */
+declare const SCROLL_HINT_X = "pr-6 [mask-image:linear-gradient(to_right,black_calc(100%-1.5rem),transparent)]";
+
 /**
  * UI Package Utilities
  *
@@ -1713,4 +2026,4 @@ declare function cn(...inputs: ClassValue[]): string;
 
 declare function useDebounce<T>(value: T, ms: number): T;
 
-export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, ActionCard, type ActionCardProps, ActionPanel, type ActionPanelProps, ActivityFeed, ActivityFeedItem, type ActivityFeedItemProps, type ActivityFeedProps, Alert, type AlertProps, AppShell, type AppShellProps, AvatarGroup, AvatarGroupItem, type AvatarGroupItemProps, type AvatarGroupProps, Button, ButtonGroup, ButtonGroupItem, type ButtonGroupItemProps, type ButtonGroupProps, type ButtonProps, Calendar, type CalendarEvent, type CalendarProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, CollapsibleSidebar, Combobox, type ComboboxOption, type ComboboxProps, CommandPalette, type CommandPaletteProps, type CommandPaletteResult, ConfirmDialog, type ConfirmDialogProps, Container, type ContainerProps, DataTable, type DataTableProps, DatePicker, type DatePickerProps, DescriptionItem, type DescriptionItemProps, DescriptionList, type DescriptionListProps, DiceBearAvatar, type DiceBearAvatarProps, type DiceBearStyle, DistributionChip, type DistributionChipProps, Divider, type DividerProps, Drawer, DrawerBody, DrawerFooter, DrawerHeader, type DrawerProps, EmptyState, type EmptyStateProps, FilterChip, type FilterChipProps, FormError, type FormErrorProps, FormField, FormFieldGroup, type FormFieldGroupProps, type FormFieldProps, FormLayout, type FormLayoutProps, FormLayoutSection, type FormLayoutSectionProps, FormSection, type FormSectionProps, FormSuccess, type FormSuccessProps, GlobalErrorContent, type GlobalErrorContentProps, GridList, GridListItem, type GridListItemProps, type GridListProps, HorizontalCard, type HorizontalCardProps, HoverCard, type HoverCardProps, ImageCard, type ImageCardProps, Input, InputGroup, type InputGroupProps, type InputProps, IntentIcon, type IntentIconProps, MediaObject, type MediaObjectProps, ModalBody, ModalDialog, type ModalDialogProps, ModalFooter, ModalHeader, type NavItem, Navbar, NavbarLink, type NavbarLinkProps, type NavbarProps, NotificationBanner, type NotificationBannerProps, NotificationPanel, NotificationPanelItem, type NotificationPanelItemProps, type NotificationPanelProps, PageContent, type PageContentProps, Pagination, PaginationButton, type PaginationProps, Popover, type PopoverProps, RadioGroup, type RadioGroupOption, type RadioGroupProps, SectionHeading, type SectionHeadingProps, type NavItem as SidebarNavItem, SimpleAccordion, SkeletonBar, type SkeletonBarProps, SkeletonCard, SkeletonCardGrid, type SkeletonCardGridProps, type SkeletonCardProps, SkeletonDetail, type SkeletonDetailProps, SkeletonRow, type SkeletonRowProps, SkeletonTable, type SkeletonTableProps, StackedList, StackedListItem, type StackedListItemProps, type StackedListProps, StatCardExtended, type StatCardExtendedProps, StatGroup, type StatGroupProps, Stepper, type StepperProps, StepperStep, type StepperStepProps, StickyActionBar, type StickyActionBarProps, Switch, type SwitchProps, TabBar, TabBarItem, type TabBarItemProps, type TabBarProps, TableBody, TableCaption, TableCell, type TableCellProps, TableHeader, TableRow, type TableRowProps, Toggle, ToggleGroup, type ToggleGroupProps, type ToggleProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, avatarVariants, buildDiceBearUrl, buttonVariants, cn, getPageRange, useDebounce, useSidebar };
+export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, ActionCard, type ActionCardProps, ActionPanel, type ActionPanelProps, ActivityFeed, ActivityFeedItem, type ActivityFeedItemProps, type ActivityFeedProps, Alert, type AlertProps, AppShell, type AppShellProps, AvatarGroup, AvatarGroupItem, type AvatarGroupItemProps, type AvatarGroupProps, Button, ButtonGroup, ButtonGroupItem, type ButtonGroupItemProps, type ButtonGroupProps, type ButtonProps, Calendar, type CalendarEvent, type CalendarProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, ClampedList, type ClampedListProps, CollapsibleSidebar, Combobox, type ComboboxOption, type ComboboxProps, CommandPalette, type CommandPaletteProps, type CommandPaletteResult, ConfirmDialog, type ConfirmDialogProps, Container, type ContainerProps, DataTable, type DataTableProps, DatePicker, type DatePickerProps, DescriptionItem, type DescriptionItemProps, DescriptionList, type DescriptionListProps, DiceBearAvatar, type DiceBearAvatarProps, type DiceBearStyle, DistributionChip, type DistributionChipProps, Divider, type DividerProps, Drawer, DrawerBody, DrawerFooter, DrawerHeader, type DrawerProps, EMPTY_VALUE_GLYPH, EmptyState, type EmptyStateProps, EmptyValue, type EmptyValueProps, FilterChip, type FilterChipProps, FormError, type FormErrorProps, FormField, FormFieldGroup, type FormFieldGroupProps, type FormFieldProps, FormLayout, type FormLayoutProps, FormLayoutSection, type FormLayoutSectionProps, FormSection, type FormSectionProps, FormSuccess, type FormSuccessProps, GlobalErrorContent, type GlobalErrorContentProps, GridList, GridListItem, type GridListItemProps, type GridListProps, HorizontalCard, type HorizontalCardProps, HoverCard, type HoverCardProps, ICONS, ICON_SIZES, INTENT_SUBTLE_STYLES, Icon, type IconName, type IconProps, type IconSize, ImageCard, type ImageCardProps, Input, InputGroup, type InputGroupProps, type InputProps, IntentBadge, type IntentBadgeIntent, type IntentBadgeProps, IntentIcon, type IntentIconProps, MediaObject, type MediaObjectProps, ModalBody, ModalDialog, type ModalDialogProps, ModalFooter, ModalHeader, type NavItem, Navbar, NavbarLink, type NavbarLinkProps, type NavbarProps, NotificationBanner, type NotificationBannerProps, NotificationPanel, NotificationPanelItem, type NotificationPanelItemProps, type NotificationPanelProps, OverflowMenu, type OverflowMenuItem, type OverflowMenuProps, PageContent, type PageContentProps, PageGutter, type PageGutterProps, PageHeading, type PageHeadingProps, Pagination, PaginationButton, type PaginationProps, Popover, type PopoverProps, RadioGroup, type RadioGroupOption, type RadioGroupProps, SCROLL_HINT_X, SectionCard, type SectionCardProps, SectionHeading, type SectionHeadingProps, SidePanelLayout, type SidePanelLayoutProps, type NavItem as SidebarNavItem, SimpleAccordion, SkeletonBar, type SkeletonBarProps, SkeletonCard, SkeletonCardGrid, type SkeletonCardGridProps, type SkeletonCardProps, SkeletonDetail, type SkeletonDetailProps, SkeletonRow, type SkeletonRowProps, SkeletonTable, type SkeletonTableProps, StackedList, StackedListItem, type StackedListItemProps, type StackedListProps, type Stage, StageList, type StageListProps, StatCardExtended, type StatCardExtendedProps, StatGroup, type StatGroupProps, Stepper, type StepperProps, StepperStep, type StepperStepProps, StickyActionBar, type StickyActionBarProps, Switch, type SwitchProps, TabBar, TabBarItem, type TabBarItemProps, type TabBarProps, TabbedCard, type TabbedCardProps, TableBody, TableCaption, TableCell, type TableCellProps, TableHeader, TableRow, type TableRowProps, Toggle, ToggleGroup, type ToggleGroupProps, type ToggleProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, avatarVariants, buildDiceBearUrl, buttonVariants, cn, getPageRange, isEmptyValue, useDebounce, useSidebar };