@astryxdesign/core 0.2.0-canary.37626ca → 0.2.0-canary.416db07

package/README.md

@@ -75,6 +75,8 @@ astryx gap-report                   # report a missing capability
 
 ## Quick Start
 
+Astryx requires **React 19** or later (`react` and `react-dom` >= 19.0.0 are peer dependencies).
+
 Install Astryx and a theme:
 
 ```bash

package/dist/Carousel/Carousel.d.ts

@@ -5,7 +5,9 @@
  * @position Horizontal scroll container with fade-edge overflow indication,
  *   optional prev/next buttons on the top layer, scroll-snap, a 1px
  *   visual bleed allowance for child selection indicators, and Shift + wheel
- *   mapping so mouse users can scroll horizontally. Exposes APG
+ *   mapping so mouse users can scroll horizontally. Supports optional
+ *   wrap-around looping and an imperative handle (handleRef) for programmatic
+ *   scroll control. Exposes APG
  *   carousel semantics: the root is a labelled region with
  *   aria-roledescription="carousel" and each item wrapper is a group with
  *   aria-roledescription="slide" named "Slide N of M".
@@ -18,8 +20,47 @@
 import { type ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';
 import type { SpacingStep } from '../utils/types';
+/**
+ * Imperative control surface for the Carousel, accessed via the `handleRef`
+ * prop. Methods drive the same native-scroll machinery as the built-in
+ * buttons, so they respect RTL, reduced-motion, and `hasLoop`.
+ */
+export interface CarouselHandle {
+    /**
+     * Scroll forward by roughly one viewport. With `hasLoop`, wraps to the
+     * start once the end is reached.
+     */
+    scrollNext(): void;
+    /**
+     * Scroll backward by roughly one viewport. With `hasLoop`, wraps to the
+     * end once the start is reached.
+     */
+    scrollPrev(): void;
+    /**
+     * Scroll the item at the given 0-based index to the start edge. The index
+     * is clamped to the item range, and only the carousel scrolls — the page
+     * position is left untouched.
+     */
+    scrollTo(index: number): void;
+    /**
+     * Whether there is scrollable content past the trailing edge. With
+     * `hasLoop`, returns true whenever the content overflows, since wrapping
+     * is always available. Reads live state — safe to call in an event handler.
+     */
+    canScrollNext(): boolean;
+    /**
+     * Whether there is scrollable content past the leading edge. With
+     * `hasLoop`, returns true whenever the content overflows. Reads live state.
+     */
+    canScrollPrev(): boolean;
+}
 export interface CarouselProps extends BaseProps<HTMLDivElement> {
     ref?: React.Ref<HTMLDivElement>;
+    /**
+     * Imperative handle for programmatic scroll control. Exposes scrollNext,
+     * scrollPrev, scrollTo, and the canScrollNext/canScrollPrev queries.
+     */
+    handleRef?: React.Ref<CarouselHandle>;
     /** Carousel items — rendered in a horizontal scroll container. */
     children: ReactNode;
     /**
@@ -39,6 +80,16 @@ export interface CarouselProps extends BaseProps<HTMLDivElement> {
      * @default true
      */
     hasEdgeFade?: boolean;
+    /**
+     * Enable wrap-around scrolling. When the content overflows, pressing Next
+     * at the end scrolls back to the start, and Prev at the start scrolls to
+     * the end — for both the built-in buttons and the imperative handle. The
+     * navigation buttons stay visible at both edges instead of hiding, since a
+     * scroll is always available. Has no effect when the content fits without
+     * overflowing.
+     * @default false
+     */
+    hasLoop?: boolean;
     /**
      * Enable scroll-snap on items. Each direct child snaps to the start edge.
      * @default false
@@ -79,7 +130,7 @@ export interface CarouselProps extends BaseProps<HTMLDivElement> {
  * </Carousel>
  * ```
  */
-export declare function Carousel({ ref, children, gap, hasButtons, hasEdgeFade, hasSnap, padding, 'aria-label': ariaLabelFromProps, xstyle, className, style, 'data-testid': testId, ...htmlProps }: CarouselProps): import("react").JSX.Element;
+export declare function Carousel({ ref, handleRef, children, gap, hasButtons, hasEdgeFade, hasLoop, hasSnap, padding, 'aria-label': ariaLabelFromProps, xstyle, className, style, 'data-testid': testId, ...htmlProps }: CarouselProps): import("react").JSX.Element;
 export declare namespace Carousel {
     var displayName: string;
 }

package/dist/Carousel/Carousel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Carousel.d.ts","sourceRoot":"","sources":["../../src/Carousel/Carousel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,KAAK,SAAS,EAMf,MAAM,OAAO,CAAC;AAef,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAIhD,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,kEAAkE;IAClE,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA+JD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,QAAQ,EACR,GAAO,EACP,UAAiB,EACjB,WAAkB,EAClB,OAAe,EACf,OAAO,EACP,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,SAAS,EACb,EAAE,aAAa,+BA6Mf;yBA3Ne,QAAQ"}
+{"version":3,"file":"Carousel.d.ts","sourceRoot":"","sources":["../../src/Carousel/Carousel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,KAAK,SAAS,EAOf,MAAM,OAAO,CAAC;AAef,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAIhD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,UAAU,IAAI,IAAI,CAAC;IACnB;;;OAGG;IACH,UAAU,IAAI,IAAI,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,aAAa,IAAI,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACtC,kEAAkE;IAClE,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA+JD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,SAAS,EACT,QAAQ,EACR,GAAO,EACP,UAAiB,EACjB,WAAkB,EAClB,OAAe,EACf,OAAe,EACf,OAAO,EACP,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,SAAS,EACb,EAAE,aAAa,+BAiRf;yBAjSe,QAAQ"}

package/dist/Carousel/Carousel.js

@@ -9,7 +9,9 @@
  * @position Horizontal scroll container with fade-edge overflow indication,
  *   optional prev/next buttons on the top layer, scroll-snap, a 1px
  *   visual bleed allowance for child selection indicators, and Shift + wheel
- *   mapping so mouse users can scroll horizontally. Exposes APG
+ *   mapping so mouse users can scroll horizontally. Supports optional
+ *   wrap-around looping and an imperative handle (handleRef) for programmatic
+ *   scroll control. Exposes APG
  *   carousel semantics: the root is a labelled region with
  *   aria-roledescription="carousel" and each item wrapper is a group with
  *   aria-roledescription="slide" named "Slide N of M".
@@ -19,7 +21,7 @@
  * - /apps/storybook/stories/Carousel.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/Carousel/ (showcase blocks)
  */
-import { useRef, useCallback, useEffect, Children, isValidElement } from 'react';
+import { useRef, useCallback, useEffect, useImperativeHandle, Children, isValidElement } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { spacingVars, colorVars, shadowVars, radiusVars, durationVars, easeVars } from "../theme/tokens.stylex.js";
@@ -31,6 +33,12 @@ import { isRtlElement } from "../hooks/isRtlElement.js";
 import { mergeProps, mergeRefs, rtlStyles } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 import { useTranslator } from "../i18n/index.js";
+
+/**
+ * Imperative control surface for the Carousel, accessed via the `handleRef`
+ * prop. Methods drive the same native-scroll machinery as the built-in
+ * buttons, so they respect RTL, reduced-motion, and `hasLoop`.
+ */
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 // =============================================================================
 // Styles
@@ -203,10 +211,12 @@ const paddingStyles = {
  */
 export function Carousel({
   ref,
+  handleRef,
   children,
   gap = 1,
   hasButtons = true,
   hasEdgeFade = true,
+  hasLoop = false,
   hasSnap = false,
   padding,
   'aria-label': ariaLabelFromProps,
@@ -222,7 +232,8 @@ export function Carousel({
   const {
     scrollRef,
     overflowStart,
-    overflowEnd
+    overflowEnd,
+    hasOverflow
   } = useScrollOverflow();
 
   // Children.toArray drops null/undefined/boolean children and assigns
@@ -277,22 +288,78 @@ export function Carousel({
     if (!el) {
       return;
     }
-    const firstChild = el.firstElementChild;
-    const itemWidth = firstChild ? firstChild.offsetWidth : 0;
-    const amount = el.clientWidth - itemWidth * 0.5;
     // Respect the user's reduced-motion preference — mirrors the CSS
     // scroll-behavior override so button-driven scrolling doesn't animate
     // for users who opted out of motion.
     const prefersReducedMotion = typeof window !== 'undefined' && typeof window.matchMedia === 'function' && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    const behavior = prefersReducedMotion ? 'auto' : 'smooth';
+    // Under RTL the scroll axis is inverted (start is scrollLeft 0, the end
+    // is negative), so flip the physical delta sign.
+    const rtlSign = isRtlElement(el) ? -1 : 1;
+
+    // Wrap-around: when looping over overflowing content, a press that would
+    // run past an edge jumps to the opposite edge instead. Overshoot by the
+    // full scroll width in the opposite logical direction and let the browser
+    // clamp to the far edge — this reuses the same RTL sign convention as a
+    // normal scroll, so it stays direction-correct without special-casing.
+    if (hasLoop && hasOverflow) {
+      const atEnd = direction === 1 && !overflowEnd;
+      const atStart = direction === -1 && !overflowStart;
+      if (atEnd || atStart) {
+        el.scrollBy({
+          left: rtlSign * -direction * el.scrollWidth,
+          behavior
+        });
+        return;
+      }
+    }
+    const firstChild = el.firstElementChild;
+    const itemWidth = firstChild ? firstChild.offsetWidth : 0;
+    const amount = el.clientWidth - itemWidth * 0.5;
     el.scrollBy({
       // `direction` is the logical intent (-1 = toward content start, +1 =
-      // toward content end). Under RTL the scroll axis is inverted (start is
-      // scrollLeft 0, the end is negative), so flip the physical delta sign.
-      left: (isRtlElement(el) ? -1 : 1) * direction * Math.max(amount, itemWidth),
+      // toward content end).
+      left: rtlSign * direction * Math.max(amount, itemWidth),
+      behavior
+    });
+  }, [hasLoop, hasOverflow, overflowStart, overflowEnd]);
+  const scrollToIndex = useCallback(index => {
+    const el = scrollElRef.current;
+    const items = el?.children;
+    if (!el || !items || items.length === 0) {
+      return;
+    }
+    const clamped = Math.max(0, Math.min(index, items.length - 1));
+    const target = items[clamped];
+    const prefersReducedMotion = typeof window !== 'undefined' && typeof window.matchMedia === 'function' && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    // Bring the item to the start edge by scrolling the container by the
+    // measured gap between the item and the container edge. Using scrollBy
+    // (not scrollIntoView) keeps the scroll contained to the carousel and
+    // never moves ancestors or the page. In RTL the start edge is the right
+    // edge, so align the trailing edges instead of the leading ones.
+    const containerRect = el.getBoundingClientRect();
+    const itemRect = target.getBoundingClientRect();
+    const delta = isRtlElement(el) ? itemRect.right - containerRect.right : itemRect.left - containerRect.left;
+    el.scrollBy({
+      left: delta,
       behavior: prefersReducedMotion ? 'auto' : 'smooth'
     });
   }, []);
-  const fadeStyle = hasEdgeFade ? overflowStart && overflowEnd ? styles.fadeBoth : overflowStart ? styles.fadeStart : overflowEnd ? styles.fadeEnd : null : null;
+  useImperativeHandle(handleRef, () => ({
+    scrollNext: () => scrollBy(1),
+    scrollPrev: () => scrollBy(-1),
+    scrollTo: index => scrollToIndex(index),
+    // With loop, either direction is reachable whenever the content
+    // overflows; otherwise reflect the live per-edge overflow state.
+    canScrollNext: () => hasLoop ? hasOverflow : overflowEnd,
+    canScrollPrev: () => hasLoop ? hasOverflow : overflowStart
+  }), [scrollBy, scrollToIndex, hasLoop, hasOverflow, overflowStart, overflowEnd]);
+
+  // With loop, the buttons stay reachable at both edges as long as there's
+  // something to scroll; without loop they follow the per-edge overflow state.
+  const canScrollStart = hasLoop && hasOverflow ? true : overflowStart;
+  const canScrollEnd = hasLoop && hasOverflow ? true : overflowEnd;
+  const fadeStyle = hasEdgeFade ? hasLoop && hasOverflow || overflowStart && overflowEnd ? styles.fadeBoth : overflowStart ? styles.fadeStart : overflowEnd ? styles.fadeEnd : null : null;
 
   // Self-authored position styles (positioning: 'custom' below): a cover
   // centered on the anchor, sized to it — direction-neutral by construction.
@@ -341,7 +408,7 @@ export function Carousel({
           1: {
             className: "x78zum5 x6s0dn4 xl56j7k x1prclbq xjspbzw x14hfi27 x19991ni xuedmi6 xlr8y92 xuuh30 x1nyx83j xg01cxk x47corl"
           }
-        }[!!!overflowStart << 0],
+        }[!!!canScrollStart << 0],
         children: /*#__PURE__*/_jsx(Button, {
           icon: /*#__PURE__*/_jsx("span", {
             ...stylex.props(rtlStyles.mirror),
@@ -359,7 +426,7 @@ export function Carousel({
           // tab order and a11y tree while it's visually hidden, so
           // keyboard users don't land on an invisible control.
           ,
-          isDisabled: !overflowStart,
+          isDisabled: !canScrollStart,
           onClick: () => scrollBy(-1),
           xstyle: styles.buttonRadiusOverride
         })
@@ -371,7 +438,7 @@ export function Carousel({
           1: {
             className: "x78zum5 x6s0dn4 xl56j7k x1prclbq xjspbzw x14hfi27 x19991ni xuedmi6 xlr8y92 xitnhlw x36dvrd xg01cxk x47corl"
           }
-        }[!!!overflowEnd << 0],
+        }[!!!canScrollEnd << 0],
         children: /*#__PURE__*/_jsx(Button, {
           icon: /*#__PURE__*/_jsx("span", {
             ...stylex.props(rtlStyles.mirror),
@@ -387,7 +454,7 @@ export function Carousel({
           // See "Scroll left" — disabled while visually hidden so the
           // button stays mounted but out of the tab order / a11y tree.
           ,
-          isDisabled: !overflowEnd,
+          isDisabled: !canScrollEnd,
           onClick: () => scrollBy(1),
           xstyle: styles.buttonRadiusOverride
         })

package/dist/Carousel/index.d.ts

@@ -5,5 +5,5 @@
  * @position Public entry point for the Carousel module
  */
 export { Carousel } from './Carousel';
-export type { CarouselProps } from './Carousel';
+export type { CarouselProps, CarouselHandle } from './Carousel';
 //# sourceMappingURL=index.d.ts.map

package/dist/Carousel/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Carousel/index.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AACpC,YAAY,EAAC,aAAa,EAAC,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Carousel/index.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AACpC,YAAY,EAAC,aAAa,EAAE,cAAc,EAAC,MAAM,YAAY,CAAC"}

package/dist/Timestamp/Timestamp.d.ts

@@ -1,7 +1,7 @@
 import type { TextType, TextSize, TextColor, TextWeight } from '../theme/types';
 import type { BaseProps } from '../BaseProps';
 import type { TimestampTooltipEntry } from './tooltipEntries';
-export type TimestampFormat = 'relative' | 'auto' | 'date' | 'date_long' | 'date_weekday' | 'date_time' | 'time' | 'system_date' | 'system_date_time' | 'system_time';
+export type TimestampFormat = 'relative' | 'relative_short' | 'auto' | 'date' | 'date_long' | 'date_weekday' | 'date_time' | 'time' | 'system_date' | 'system_date_time' | 'system_time';
 export interface TimestampProps extends BaseProps<HTMLTimeElement> {
     /** Ref forwarded to the root `<time>` element. */
     ref?: React.Ref<HTMLTimeElement>;
@@ -10,6 +10,9 @@ export interface TimestampProps extends BaseProps<HTMLTimeElement> {
     /**
      * Display format.
      * - `'relative'`: "2 hours ago", "yesterday", "now"
+     * - `'relative_short'`: "2h ago", "1d ago", "now" — the same tiers as
+     *   `'relative'` with abbreviated units (s/m/h/d/mo/y), for compact,
+     *   space-constrained surfaces
      * - `'auto'`: Relative for recent times, `date_time` for older
      * - `'date'`: "Mar 21, 2025"
      * - `'date_long'`: "March 21, 2025"

package/dist/Timestamp/Timestamp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Timestamp.d.ts","sourceRoot":"","sources":["../../src/Timestamp/Timestamp.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAC,MAAM,gBAAgB,CAAC;AAG9E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAK5C,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,kBAAkB,CAAC;AAU5D,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,MAAM,GACN,MAAM,GACN,WAAW,GACX,cAAc,GACd,WAAW,GACX,MAAM,GACN,aAAa,GACb,kBAAkB,GAClB,aAAa,CAAC;AAElB,MAAM,WAAW,cAAe,SAAQ,SAAS,CAAC,eAAe,CAAC;IAChE,kDAAkD;IAClD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACjC,uFAAuF;IACvF,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAC;IACtD;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;OAEG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;OAEG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA2LD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,MAAe,EACf,aAAsC,EACtC,UAAiB,EACjB,cAAc,EACd,eAAuB,EACvB,MAAc,EACd,IAAmB,EACnB,IAAI,EACJ,KAAmB,EACnB,MAAM,EACN,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,aAAa,EAAE,MAAM,GACtB,EAAE,cAAc,sCA4IhB;yBA7Je,SAAS"}
+{"version":3,"file":"Timestamp.d.ts","sourceRoot":"","sources":["../../src/Timestamp/Timestamp.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAC,MAAM,gBAAgB,CAAC;AAG9E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAK5C,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,kBAAkB,CAAC;AAU5D,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,gBAAgB,GAChB,MAAM,GACN,MAAM,GACN,WAAW,GACX,cAAc,GACd,WAAW,GACX,MAAM,GACN,aAAa,GACb,kBAAkB,GAClB,aAAa,CAAC;AAElB,MAAM,WAAW,cAAe,SAAQ,SAAS,CAAC,eAAe,CAAC;IAChE,kDAAkD;IAClD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACjC,uFAAuF;IACvF,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAC;IACtD;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;OAEG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;OAEG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAwQD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,MAAe,EACf,aAAsC,EACtC,UAAiB,EACjB,cAAc,EACd,eAAuB,EACvB,MAAc,EACd,IAAmB,EACnB,IAAI,EACJ,KAAmB,EACnB,MAAM,EACN,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,aAAa,EAAE,MAAM,GACtB,EAAE,cAAc,sCA8IhB;yBA/Je,SAAS"}

package/dist/Timestamp/Timestamp.js

@@ -139,6 +139,67 @@ function getRelativeTimeString(date, now) {
   return `${years} ${years === 1 ? 'year' : 'years'} ago`;
 }
 
+/**
+ * The compact sibling of `getRelativeTimeString`: the same tier boundaries and
+ * present/future-skew handling, rendered with abbreviated units for
+ * space-constrained surfaces (chat metadata, dense tables, chips).
+ *
+ * Units follow the common compact convention (and the Microsoft Style Guide):
+ * `s` seconds, `m` minutes, `h` hours, `d` days, `mo` months, `y` years.
+ * Months use `mo` — not `m` — because `m` already means minutes; a bare `m`
+ * for months would be ambiguous. The value is always numeric (no "yesterday"
+ * idiom, which belongs to the long form) so the short form stays predictable
+ * and easy to scan. The `ago` / `in` affixes are kept so direction stays
+ * unambiguous at a glance.
+ */
+function getRelativeTimeShortString(date, now) {
+  const diffSeconds = Math.round((now.getTime() - date.getTime()) / 1000);
+
+  // Present clamp — identical to the long form (see getRelativeTimeString).
+  if (Math.abs(diffSeconds) < 10) {
+    return 'now';
+  }
+  if (diffSeconds < 0) {
+    // Future dates.
+    const absDiff = Math.abs(diffSeconds);
+    if (absDiff <= FUTURE_SKEW_TOLERANCE) {
+      return 'now';
+    }
+    if (absDiff < MINUTE) {
+      return `in ${absDiff}s`;
+    }
+    if (absDiff < HOUR) {
+      return `in ${Math.floor(absDiff / MINUTE)}m`;
+    }
+    if (absDiff < DAY) {
+      return `in ${Math.floor(absDiff / HOUR)}h`;
+    }
+    if (absDiff < MONTH) {
+      return `in ${Math.floor(absDiff / DAY)}d`;
+    }
+    if (absDiff < YEAR) {
+      return `in ${Math.floor(absDiff / MONTH)}mo`;
+    }
+    return `in ${Math.floor(absDiff / YEAR)}y`;
+  }
+  if (diffSeconds < MINUTE) {
+    return `${diffSeconds}s ago`;
+  }
+  if (diffSeconds < HOUR) {
+    return `${Math.floor(diffSeconds / MINUTE)}m ago`;
+  }
+  if (diffSeconds < DAY) {
+    return `${Math.floor(diffSeconds / HOUR)}h ago`;
+  }
+  if (diffSeconds < MONTH) {
+    return `${Math.floor(diffSeconds / DAY)}d ago`;
+  }
+  if (diffSeconds < YEAR) {
+    return `${Math.floor(diffSeconds / MONTH)}mo ago`;
+  }
+  return `${Math.floor(diffSeconds / YEAR)}y ago`;
+}
+
 /** Returns the interval (in ms) at which a relative timestamp should update. */
 function getLiveInterval(diffSeconds) {
   const absDiff = Math.abs(diffSeconds);
@@ -156,7 +217,17 @@ function getLiveInterval(diffSeconds) {
 
 /** Whether a format is non-relative (i.e. shows a fixed date/time). */
 function isAbsoluteFormat(format) {
-  return format !== 'relative' && format !== 'auto';
+  return format !== 'relative' && format !== 'relative_short' && format !== 'auto';
+}
+
+/**
+ * Whether a format renders a relative phrase ("2 hours ago" / "2h ago") rather
+ * than a fixed instant. Both the long and short relative forms share the same
+ * treatment: they get the accessible full-date name, the hover tooltip, and
+ * live updates.
+ */
+function isRelativeFormat(format) {
+  return format === 'relative' || format === 'relative_short';
 }
 
 // =============================================================================
@@ -213,7 +284,7 @@ export function Timestamp({
 
   // Format the display text. No time zone is passed: the visible text always
   // reads in the viewer's own zone, and only the tooltip names others.
-  const displayText = !isValidDate ? '' : effectiveFormat === 'relative' ? getRelativeTimeString(date, now) : isAbsoluteFormat(effectiveFormat) ? formatInstant(date, effectiveFormat, {
+  const displayText = !isValidDate ? '' : effectiveFormat === 'relative' ? getRelativeTimeString(date, now) : effectiveFormat === 'relative_short' ? getRelativeTimeShortString(date, now) : isAbsoluteFormat(effectiveFormat) ? formatInstant(date, effectiveFormat, {
     isTimezoneShown
   }) : '';
 
@@ -222,7 +293,7 @@ export function Timestamp({
 
   // Live updates
   useEffect(() => {
-    if (!isLive || !isValidDate || effectiveFormat !== 'relative') {
+    if (!isLive || !isValidDate || !isRelativeFormat(effectiveFormat)) {
       return;
     }
     const interval = getLiveInterval(diffSeconds);
@@ -246,7 +317,7 @@ export function Timestamp({
   // when a consumer has explicitly configured tooltip lines would let `format`
   // silently suppress another prop's output, so entry presence opens it too.
   // With no entries this reduces to the original condition exactly.
-  const showTooltip = hasTooltip && (effectiveFormat === 'relative' || entries !== undefined);
+  const showTooltip = hasTooltip && (isRelativeFormat(effectiveFormat) || entries !== undefined);
   const timestampProps = mergeProps(themeProps('timestamp', {
     format: effectiveFormat
   }), {
@@ -263,7 +334,7 @@ export function Timestamp({
     children: /*#__PURE__*/_jsx("time", {
       ref: mergeRefs(ref, timeRef),
       dateTime: isoString,
-      "aria-label": effectiveFormat === 'relative' ? fullAbsoluteText : undefined
+      "aria-label": isRelativeFormat(effectiveFormat) ? fullAbsoluteText : undefined
       // The absolute-time tooltip is anchored here with the default 'auto'
       // focus trigger, which only activates on focusable anchors. A bare
       // <time> is not focusable, so without a tab stop sighted keyboard

package/dist/Timestamp/formatInstant.d.ts

@@ -4,10 +4,10 @@ import type { TimestampFormat } from './Timestamp';
  * style ("February 19, 2026 at 5:00:00 PM UTC") that backs a relative
  * timestamp's accessible name and the tooltip's default line.
  *
- * `'relative'` and `'auto'` are excluded: a relative phrase names no instant,
- * so a zone could not change what it says.
+ * `'relative'`, `'relative_short'`, and `'auto'` are excluded: a relative
+ * phrase names no instant, so a zone could not change what it says.
  */
-export type InstantFormat = Exclude<TimestampFormat, 'relative' | 'auto'> | 'full';
+export type InstantFormat = Exclude<TimestampFormat, 'relative' | 'relative_short' | 'auto'> | 'full';
 export interface FormatInstantOptions {
     /**
      * IANA time zone identifier. Omit for the viewer's own zone — which is what

package/dist/Timestamp/formatInstant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatInstant.d.ts","sourceRoot":"","sources":["../../src/Timestamp/formatInstant.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AAMjD;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GACrB,OAAO,CAAC,eAAe,EAAE,UAAU,GAAG,MAAM,CAAC,GAC7C,MAAM,CAAC;AAEX,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AA6ED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,aAAa,EACrB,EAAC,QAAQ,EAAE,eAAuB,EAAC,GAAE,oBAAyB,GAC7D,MAAM,CA0DR"}
+{"version":3,"file":"formatInstant.d.ts","sourceRoot":"","sources":["../../src/Timestamp/formatInstant.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AAMjD;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GACvB,OAAO,CAAC,eAAe,EAAE,UAAU,GAAG,gBAAgB,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC;AAE5E,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AA6ED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,aAAa,EACrB,EAAC,QAAQ,EAAE,eAAuB,EAAC,GAAE,oBAAyB,GAC7D,MAAM,CA0DR"}

package/dist/Timestamp/formatInstant.js

@@ -40,8 +40,8 @@ import { SHARED_DATE_FORMAT_OPTIONS, getTimeZoneParts } from "../utils/plainDate
  * style ("February 19, 2026 at 5:00:00 PM UTC") that backs a relative
  * timestamp's accessible name and the tooltip's default line.
  *
- * `'relative'` and `'auto'` are excluded: a relative phrase names no instant,
- * so a zone could not change what it says.
+ * `'relative'`, `'relative_short'`, and `'auto'` are excluded: a relative
+ * phrase names no instant, so a zone could not change what it says.
  */
 
 // =============================================================================

package/dist/Timestamp/tooltipEntries.d.ts

@@ -4,8 +4,9 @@ import type { InstantFormat } from './formatInstant';
  *
  * Every `TimestampFormat` that names a fixed instant, plus `'full'` — the long
  * absolute style the tooltip has always shown ("February 19, 2026 at 5:00:00 PM
- * UTC"). `'relative'` and `'auto'` are excluded: a relative phrase ignores any
- * zone, which would make `timezoneID` silently inert on that line.
+ * UTC"). `'relative'`, `'relative_short'`, and `'auto'` are excluded: a
+ * relative phrase ignores any zone, which would make `timezoneID` silently
+ * inert on that line.
  *
  * `'full'` lives only in this vocabulary, never in `TimestampFormat` — nothing
  * asked for it as a visible display format, and keeping it out means new

package/dist/Timestamp/tooltipEntries.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tooltipEntries.d.ts","sourceRoot":"","sources":["../../src/Timestamp/tooltipEntries.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAMnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,sBAAsB,GAAG,aAAa,CAAC;AAEnD,yCAAyC;AACzC,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,+BAA+B;AAC/B,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAqGD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,aAAa,CAAC,qBAAqB,CAAC,GAC5C,aAAa,CAAC,oBAAoB,CAAC,CAoBrC"}
+{"version":3,"file":"tooltipEntries.d.ts","sourceRoot":"","sources":["../../src/Timestamp/tooltipEntries.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAMnD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,sBAAsB,GAAG,aAAa,CAAC;AAEnD,yCAAyC;AACzC,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,+BAA+B;AAC/B,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAqGD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,aAAa,CAAC,qBAAqB,CAAC,GAC5C,aAAa,CAAC,oBAAoB,CAAC,CAoBrC"}

package/dist/Timestamp/tooltipEntries.js

@@ -33,8 +33,9 @@ import { formatInstant } from "./formatInstant.js";
  *
  * Every `TimestampFormat` that names a fixed instant, plus `'full'` — the long
  * absolute style the tooltip has always shown ("February 19, 2026 at 5:00:00 PM
- * UTC"). `'relative'` and `'auto'` are excluded: a relative phrase ignores any
- * zone, which would make `timezoneID` silently inert on that line.
+ * UTC"). `'relative'`, `'relative_short'`, and `'auto'` are excluded: a
+ * relative phrase ignores any zone, which would make `timezoneID` silently
+ * inert on that line.
  *
  * `'full'` lives only in this vocabulary, never in `TimestampFormat` — nothing
  * asked for it as a visible display format, and keeping it out means new