@astryxdesign/core 0.2.0 → 0.3.0-canary.5f9896c

package/src/ProgressBar/ProgressBar.tsx

@@ -11,12 +11,13 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/ProgressBar/ProgressBar.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/ProgressBar/ProgressBar.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/ProgressBar/ProgressBarMarkTooltip.tsx (the lazy Tooltip wrapper for labeled marks)
  * - /packages/core/src/ProgressBar/index.ts (exports if types change)
  * - /apps/storybook/stories/ProgressBar.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/ProgressBar/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/ProgressBar/ (showcase blocks)
  */
 
-import {useId} from 'react';
+import {lazy, Suspense, useId} from 'react';
 import * as stylex from '@stylexjs/stylex';
 
 import {
@@ -32,27 +33,15 @@ import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {VisuallyHidden} from '../VisuallyHidden';
+import type {ProgressBarVariantMap} from './index';
 
-/**
- * Extensible variant map for ProgressBar.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/ProgressBar' {
- *   interface ProgressBarVariantMap {
- *     'brand': true;
- *   }
- * }
- * ```
- */
-export interface ProgressBarVariantMap {
-  accent: true;
-  success: true;
-  warning: true;
-  neutral: true;
-  error: true;
-}
+// Every mark is wrapped in a Tooltip (marks always carry a label), so load it
+// lazily: a ProgressBar with no marks never bundles the Tooltip chunk. While it
+// loads, the Suspense fallback shows the bare mark, so nothing disappears; the
+// tooltip simply attaches once the chunk is ready.
+const LazyProgressBarMarkTooltip = lazy(
+  async () => import('./ProgressBarMarkTooltip'),
+);
 
 /**
  * Progress bar variant type — maps to semantic color tokens.
@@ -60,6 +49,29 @@ export interface ProgressBarVariantMap {
  */
 export type ProgressBarVariant = keyof ProgressBarVariantMap;
 
+/**
+ * A fixed target mark drawn on the progress track.
+ *
+ * Positioned by `value` in the same `0..max` scale as the bar's `value` prop —
+ * mirroring the object shape of Slider's `marks` so the two APIs stay
+ * consistent.
+ */
+export interface ProgressBarMark {
+  /**
+   * Position of the mark in the same `0..max` scale as `value`. Values
+   * outside the range are clamped to the track edges.
+   */
+  value: number;
+  /**
+   * Names the mark. A mark stands for something meaningful on the track — a
+   * goal, a threshold, a quarter target — so a label is required: it is the
+   * mark's accessible name and the text revealed in a `Tooltip` on hover and
+   * keyboard focus. Can be the value itself (e.g. `'70%'`) or something richer
+   * (e.g. `'Q1 target: 50%'`).
+   */
+  label: string;
+}
+
 export interface ProgressBarProps extends BaseProps<HTMLDivElement> {
   /** Ref forwarded to the root element */
   ref?: React.Ref<HTMLDivElement>;
@@ -107,6 +119,18 @@ export interface ProgressBarProps extends BaseProps<HTMLDivElement> {
    * @default false
    */
   isIndeterminate?: boolean;
+  /**
+   * Target marks drawn on the track at fixed points in the same `0..max`
+   * scale as `value` — e.g. a goal line. Marks stay visible whether progress
+   * is below or past them, and take their color from what they sit on: a mark
+   * inside the filled area uses the fill variant's on-color (on-accent,
+   * on-warning, on-error, …), while a mark still out on the bare track uses
+   * `--color-text-primary` (`--color-text-secondary` on a disabled bar, which
+   * dims everything it draws). Each mark's required `label` names it for
+   * assistive tech and is revealed via a `Tooltip` on hover/focus. Ignored when
+   * `isIndeterminate` is true.
+   */
+  marks?: ReadonlyArray<ProgressBarMark>;
   /**
    * When true, the progress bar is visually disabled — the fill bar and
    * text use disabled colors. Use for canceled or inactive operations.
@@ -190,11 +214,27 @@ const styles = stylex.create({
     whiteSpace: 'nowrap',
     borderWidth: 0,
   },
+  // The `role="progressbar"` element. In determinate mode it does NOT clip its
+  // content (`overflow` stays visible) so a themed mark taller than the bar can
+  // overhang it; the determinate fill rounds its own corners via `border-radius`
+  // (see `fill`) and is always inside the track box, so dropping the clip does
+  // not change its appearance at any progress. Indeterminate mode re-adds the
+  // clip via `trackClipped` (see below) — its sliding fill travels outside the
+  // track and must be clipped, and marks are ignored while indeterminate, so
+  // there is nothing to overhang.
   track: {
+    position: 'relative',
     width: '100%',
     height: '8px',
     backgroundColor: colorVars['--color-background-muted'],
     borderRadius: radiusVars['--radius-full'],
+  },
+  // Indeterminate-only clip. The indeterminate fill slides from translateX
+  // -100% to 250%, so it deliberately overshoots the track on both sides and
+  // relies on the track clipping it to the visible window. Applied only when
+  // `isIndeterminate` (marks are suppressed then, so nothing needs to overhang)
+  // so it never re-clips a themed tall mark in determinate mode.
+  trackClipped: {
     overflow: 'hidden',
   },
   fill: {
@@ -219,6 +259,37 @@ const styles = stylex.create({
     animationTimingFunction: 'ease-in-out',
     animationIterationCount: 'infinite',
   },
+  // A mark is a vertical tick centered on the track, a child of the
+  // `role="progressbar"` element (unchanged DOM). The track no longer clips, so
+  // its height — 8px by default, directly overridable via the `progressbar-mark`
+  // theme target — may exceed the bar and overhang; the centering translate
+  // keeps any overhang symmetric. Positioned horizontally via `insetInlineStart`;
+  // the translate mirrors under RTL.
+  //
+  // The tick's color is not set here: it depends on what the mark sits on, so
+  // it comes from `markOnFillStyles[variant]` (mark inside the filled area) or
+  // `markOnTrackStyles.track` (mark out on the bare track). Both remain
+  // directly overridable via the `progressbar-mark` theme target — a theme can
+  // set `backgroundColor`, `width`, and `height` (e.g. a taller "flag" tick
+  // that overhangs the bar) with `defineTheme`; no dedicated CSS vars needed.
+  mark: {
+    position: 'absolute',
+    top: '50%',
+    width: 2,
+    height: 8,
+    outline: {
+      default: 'none',
+      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+    },
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': '2px',
+    },
+    transform: {
+      default: 'translate(-50%, -50%)',
+      ':is([dir="rtl"] *)': 'translate(50%, -50%)',
+    },
+  },
 });
 
 const variantStyles = stylex.create({
@@ -242,6 +313,64 @@ const variantStyles = stylex.create({
   },
 });
 
+// A mark sitting inside the filled area is drawn *on* the bar, so it takes the
+// on-color that pairs with the fill's own variant color — the same pairing
+// Badge uses for solid semantic backgrounds.
+//
+// `neutral` and `disabled` both fill with the muted `--color-text-disabled`
+// gray, which carries no semantic weight and has no dedicated on-token, so
+// they fall back to a plain foreground. They pick different ones: a `neutral`
+// bar is live, so its mark keeps the full-contrast `--color-text-primary` a
+// mark uses out on the track; a `disabled` bar is deliberately low-emphasis —
+// its own label and value text drop to muted colors — so its mark steps down
+// to `--color-text-secondary` rather than becoming the loudest thing on a
+// grayed-out component.
+const markOnFillStyles = stylex.create({
+  accent: {
+    backgroundColor: colorVars['--color-on-accent'],
+  },
+  success: {
+    backgroundColor: colorVars['--color-on-success'],
+  },
+  warning: {
+    backgroundColor: colorVars['--color-on-warning'],
+  },
+  error: {
+    backgroundColor: colorVars['--color-on-error'],
+  },
+  neutral: {
+    backgroundColor: colorVars['--color-text-primary'],
+  },
+  disabled: {
+    backgroundColor: colorVars['--color-text-secondary'],
+  },
+});
+
+// A mark out on the bare track is a foreground tick over the muted track
+// background, so it takes `--color-text-primary`.
+//
+// The obvious candidate was `--color-border-emphasized` — the emphasized
+// divider color `Divider`'s `strong` variant and `Slider`'s marks use — but
+// divider tokens sit a step or two from the track on the same neutral ramp, so
+// a mark drawn in one is at or near invisible: measured against each shipped
+// theme's track it lands between 1.00:1 (theme-neutral, both modes, where the
+// track is aliased to that very token) and 2.9:1, under the 3:1 WCAG 1.4.11
+// non-text floor in 7 of 8 themes. `--color-text-secondary` still misses in
+// two. `--color-text-primary` is the one foreground guaranteed to read against
+// every surface a theme defines: 5.8:1 to 15.7:1 on the track across all
+// themes and both modes.
+const markOnTrackStyles = stylex.create({
+  track: {
+    backgroundColor: colorVars['--color-text-primary'],
+  },
+  // A disabled bar dims everything it draws, so its track marks step down to
+  // the secondary foreground for the same reason the disabled on-fill mark
+  // does — matching the muted label and value text.
+  trackDisabled: {
+    backgroundColor: colorVars['--color-text-secondary'],
+  },
+});
+
 function defaultFormatValueLabel(value: number, max: number): string {
   const pct = max > 0 ? Math.round((value / max) * 100) : 0;
   return `${pct}%`;
@@ -256,7 +385,8 @@ function defaultFormatValueLabel(value: number, max: number): string {
  *
  * ProgressBar is intentionally minimal — compose additional labels, status
  * icons, and descriptions alongside the bar using layout components rather
- * than adding props to ProgressBar itself.
+ * than adding props to ProgressBar itself. The exception is on-track content
+ * like `marks`, which are positioned by value over the track.
  *
  * Styles use Astryx theme tokens via StyleX.
  * Wrap your app in <Theme> to apply a theme.
@@ -268,6 +398,24 @@ function defaultFormatValueLabel(value: number, max: number): string {
  * <ProgressBar value={3.2} max={5} label="Disk usage" hasValueLabel
  *   formatValueLabel={(v, m) => `${v} GB / ${m} GB`} />
  * <ProgressBar value={30} label="Canceled" isDisabled hasValueLabel />
+ * <ProgressBar value={45} label="Fundraiser" marks={[{value: 80, label: 'Goal'}]} />
+ * ```
+ *
+ * A mark's height, width, and color are directly themeable via the
+ * `progressbar-mark` target. The target reflects `data-placement`
+ * (`"fill"` when the mark sits inside the filled area, `"track"` when it is
+ * still out on the bare track) and `data-variant` (the fill's variant), so a
+ * theme can style the two cases separately — e.g. a taller "goal flag" tick
+ * that overhangs the bar (centered, so the overhang is symmetric):
+ *
+ * @example
+ * ```
+ * defineTheme({
+ *   name: 'campaign',
+ *   components: {
+ *     'progressbar-mark': {base: {height: '16px', backgroundColor: 'red'}},
+ *   },
+ * });
  * ```
  */
 export function ProgressBar({
@@ -280,6 +428,7 @@ export function ProgressBar({
   variant = 'accent',
   isIndeterminate = false,
   isDisabled = false,
+  marks,
   xstyle,
   className,
   style,
@@ -302,6 +451,32 @@ export function ProgressBar({
 
   const fillVariant = isDisabled ? 'disabled' : variant;
 
+  // Marks make no sense without a determinate value, so they are only drawn
+  // in determinate mode. Non-finite mark values are dropped; the rest are
+  // clamped to the track edges, matching the bar's own `clampedValue`.
+  //
+  // Each mark also records whether it lands on the filled part of the bar
+  // (`isOnFill`), which decides its color: a mark inside the fill reads against
+  // the variant color, one out on the bare track reads against the track. A
+  // mark exactly at the fill's leading edge counts as on the fill — it is the
+  // "reached the target" moment — except at zero progress, where there is no
+  // fill for it to sit on.
+  const resolvedMarks =
+    !isIndeterminate && marks
+      ? marks
+          .filter(mark => Number.isFinite(mark.value))
+          .map(mark => {
+            const clamped = Math.min(Math.max(0, mark.value), safeMax);
+            const pct = safeMax > 0 ? (clamped / safeMax) * 100 : 0;
+            return {
+              value: mark.value,
+              label: mark.label,
+              pct,
+              isOnFill: percentage > 0 && pct <= percentage,
+            };
+          })
+      : [];
+
   return (
     <div
       ref={ref}
@@ -339,7 +514,10 @@ export function ProgressBar({
         <VisuallyHidden id={labelId}>{label}</VisuallyHidden>
       )}
 
-      {/* Progress track */}
+      {/* Progress track — the `role="progressbar"` element, holding the fill
+          and marks as its children (unchanged DOM shape). It no longer clips
+          (`overflow` is visible), so a themed taller mark can overhang it;
+          the fill preserves its rounded shape via its own `border-radius`. */}
       <div
         role="progressbar"
         aria-valuenow={isIndeterminate ? undefined : clampedValue}
@@ -349,7 +527,7 @@ export function ProgressBar({
         aria-valuetext={isIndeterminate ? undefined : valueText}
         {...mergeProps(
           themeProps('progressbar-track'),
-          stylex.props(styles.track),
+          stylex.props(styles.track, isIndeterminate && styles.trackClipped),
         )}>
         {isIndeterminate ? (
           <div
@@ -370,6 +548,53 @@ export function ProgressBar({
             style={{width: `${percentage}%`}}
           />
         )}
+        {/* Target marks — children of the progressbar element (unchanged),
+            layered above the fill so they show whether progress is below or
+            past them. A mark's color follows what it sits on: inside the fill
+            it uses the fill variant's on-color, out on the bare track it uses
+            the emphasized divider color. Each mark is labeled, so it is a
+            focusable Tooltip trigger: the label is visible on hover/focus and
+            names the mark for assistive tech via the Tooltip's
+            aria-describedby, without adding a labeled child to the
+            progressbar's own a11y subtree. */}
+        {resolvedMarks.map(mark => {
+          // The tick element. It is both the Tooltip's anchor and the Suspense
+          // fallback shown while the lazy Tooltip chunk loads, so the tick is
+          // always visible and the label attaches once ready. The list `key`
+          // lives on the mapped <Suspense>, not here.
+          //
+          // `placement` is reflected as `data-placement` (and a class) so a
+          // theme can style the two cases separately on the
+          // `progressbar-mark` target; `variant` mirrors the fill's variant
+          // for the same reason.
+          const markEl = (
+            <span
+              tabIndex={0}
+              {...mergeProps(
+                themeProps('progressbar-mark', {
+                  variant: fillVariant,
+                  placement: mark.isOnFill ? 'fill' : 'track',
+                }),
+                stylex.props(
+                  styles.mark,
+                  mark.isOnFill
+                    ? markOnFillStyles[fillVariant]
+                    : isDisabled
+                      ? markOnTrackStyles.trackDisabled
+                      : markOnTrackStyles.track,
+                ),
+              )}
+              style={{insetInlineStart: `${mark.pct}%`}}
+            />
+          );
+          return (
+            <Suspense key={`${mark.value}:${mark.label}`} fallback={markEl}>
+              <LazyProgressBarMarkTooltip content={mark.label}>
+                {markEl}
+              </LazyProgressBarMarkTooltip>
+            </Suspense>
+          );
+        })}
       </div>
     </div>
   );

package/src/ProgressBar/ProgressBarMarkTooltip.tsx

@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ProgressBarMarkTooltip.tsx
+ * @input Uses React, Tooltip, the mark element to wrap, and its label
+ * @output Default-exports the lazily-loaded Tooltip wrapper for a labeled mark
+ * @position Split out of ProgressBar so the Tooltip only loads when a mark is
+ *   actually rendered — a ProgressBar with no marks never bundles the Tooltip
+ *   chunk.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/ProgressBar/ProgressBar.tsx (the lazy() + Suspense wrapper)
+ * - /packages/core/src/ProgressBar/ProgressBar.test.tsx
+ */
+
+import type {ReactElement} from 'react';
+import {Tooltip} from '../Tooltip/Tooltip';
+
+export interface ProgressBarMarkTooltipProps {
+  /** The mark's accessible name / visible tooltip text. */
+  content: string;
+  /** The bare mark element the tooltip anchors to (also the Suspense fallback). */
+  children: ReactElement;
+}
+
+/**
+ * Wraps a labeled mark in a `Tooltip` that reveals its label on hover and
+ * keyboard focus. Placement and focus behavior match the inline usage this
+ * split replaced (`placement="above"`, `focusTrigger="always"`), so the
+ * rendered result is identical — only the load timing changes.
+ */
+export default function ProgressBarMarkTooltip({
+  content,
+  children,
+}: ProgressBarMarkTooltipProps): ReactElement {
+  return (
+    <Tooltip content={content} placement="above" focusTrigger="always">
+      {children}
+    </Tooltip>
+  );
+}

package/src/ProgressBar/index.ts

@@ -6,9 +6,30 @@
  * @file ProgressBar component barrel export
  */
 
+/**
+ * Extensible variant map for ProgressBar.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/ProgressBar' {
+ *   interface ProgressBarVariantMap {
+ *     'brand': true;
+ *   }
+ * }
+ * ```
+ */
+export interface ProgressBarVariantMap {
+  accent: true;
+  success: true;
+  warning: true;
+  neutral: true;
+  error: true;
+}
+
 export {ProgressBar} from './ProgressBar';
 export type {
   ProgressBarProps,
+  ProgressBarMark,
   ProgressBarVariant,
-  ProgressBarVariantMap,
 } from './ProgressBar';

package/src/RadioList/RadioList.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'RadioList',
@@ -149,7 +149,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -171,7 +171,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Radio group component for single-value selection from list of options.',

package/src/RadioList/RadioList.test.tsx

@@ -14,6 +14,7 @@ import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {RadioList} from './RadioList';
 import {RadioListItem} from './RadioListItem';
+import {getForcedColorsRules} from '../__tests__/forcedColors';
 
 // Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
 // reflects its open state via a `popover-open` attribute the tests can assert.
@@ -580,7 +581,11 @@ describe('RadioList', () => {
     it('submits the selected value under htmlName', () => {
       const {container} = render(
         <form>
-          <RadioList label="Preference" htmlName="pref" value="b" onChange={() => {}}>
+          <RadioList
+            label="Preference"
+            htmlName="pref"
+            value="b"
+            onChange={() => {}}>
             <RadioListItem label="Option A" value="a" />
             <RadioListItem label="Option B" value="b" />
           </RadioList>
@@ -599,13 +604,14 @@ describe('RadioList', () => {
             value="a"
             onChange={() => {}}
             isDisabled
-            disabledMessage="Locked"
-          >
+            disabledMessage="Locked">
             <RadioListItem label="Option A" value="a" />
           </RadioList>
         </form>,
       );
-      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
     });
 
     it('keeps working as an isolated group when htmlName is omitted', () => {
@@ -642,3 +648,19 @@ describe('RadioList', () => {
     });
   });
 });
+
+// jsdom cannot emulate forced-colors rendering, so this asserts that the
+// compiled output includes the forced-colors rule; visual behavior needs
+// manual verification under Windows High Contrast.
+describe('forced colors (WCAG 1.4.11)', () => {
+  it('compiles a forced-colors fill so the selected dot survives Windows High Contrast', () => {
+    render(
+      <RadioList label="Preference" value="a" onChange={() => {}}>
+        <RadioListItem label="Option A" value="a" />
+      </RadioList>,
+    );
+    // The painted inner dot would be stripped to Canvas (invisible), making
+    // checked and unchecked radios identical; CanvasText keeps it perceivable.
+    expect(getForcedColorsRules()).toContain('background-color: canvastext;');
+  });
+});

package/src/RadioList/RadioList.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/RadioList/RadioList.test.tsx
  * - /packages/core/src/RadioList/index.ts
  * - /apps/storybook/stories/RadioList.stories.tsx
- * - /packages/cli/templates/blocks/components/RadioList/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/RadioList/ (showcase blocks)
  */
 
 import React, {

package/src/RadioList/RadioListItem.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'RadioListItem',

package/src/RadioList/RadioListItem.tsx

@@ -15,7 +15,7 @@
  * - /packages/core/src/RadioList/RadioList.test.tsx
  * - /packages/core/src/RadioList/index.ts
  * - /apps/storybook/stories/RadioList.stories.tsx
- * - /packages/cli/templates/blocks/components/RadioList/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/RadioList/ (showcase blocks)
  */
 
 import React, {use, useId, type ReactNode} from 'react';
@@ -119,7 +119,14 @@ const styles = stylex.create({
   },
   innerDot: {
     borderRadius: '50%',
-    backgroundColor: colorVars['--color-on-accent'],
+    backgroundColor: {
+      default: colorVars['--color-on-accent'],
+      // Forced colors (Windows High Contrast) strips painted backgrounds,
+      // which would make the selected dot invisible — checked and unchecked
+      // radios would look identical. CanvasText keeps the dot perceivable on
+      // the Canvas circle fill (WCAG 1.4.11).
+      '@media (forced-colors: active)': 'CanvasText',
+    },
   },
   labelDisabled: {
     color: colorVars['--color-text-disabled'],

package/src/Resizable/Resizable.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docs = {
   name: 'Resizable',
   displayName: 'Resizable',
@@ -188,7 +188,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Hook-based resizable panel system. useResizable() manages size state; ResizeHandle provides interactive pill-grip separator.',
   usage: {

package/src/Resizable/ResizeHandle.test.tsx

@@ -150,7 +150,55 @@ describe('ResizeHandle', () => {
     const separator = getSeparator();
     act(() => separator.focus());
     fireEvent.keyDown(separator, {key: 'Enter'});
-    expect(separator).toHaveAttribute('aria-valuenow', '0');
+    // The panel's real size is 0, but aria-valuenow must never drop below
+    // aria-valuemin (WCAG 4.1.2) — it clamps to the minimum and the state
+    // is announced via aria-valuetext instead.
+    expect(separator).toHaveAttribute('aria-valuenow', '100');
+    expect(separator).toHaveAttribute('aria-valuetext', 'Collapsed');
+  });
+
+  it('keeps aria-valuenow >= aria-valuemin and announces "Collapsed" while collapsed', () => {
+    render(
+      <Harness
+        config={{
+          defaultSize: 200,
+          minSizePx: 100,
+          maxSizePx: 400,
+          collapsible: true,
+        }}
+      />,
+    );
+    const separator = getSeparator();
+    act(() => separator.focus());
+    fireEvent.keyDown(separator, {key: 'Enter'});
+
+    const valueNow = Number(separator.getAttribute('aria-valuenow'));
+    const valueMin = Number(separator.getAttribute('aria-valuemin'));
+    expect(valueNow).toBeGreaterThanOrEqual(valueMin);
+    expect(separator).toHaveAttribute('aria-valuetext', 'Collapsed');
+  });
+
+  it('removes aria-valuetext when the panel is expanded', () => {
+    render(
+      <Harness
+        config={{
+          defaultSize: 200,
+          minSizePx: 100,
+          maxSizePx: 400,
+          collapsible: true,
+        }}
+      />,
+    );
+    const separator = getSeparator();
+    expect(separator).not.toHaveAttribute('aria-valuetext');
+
+    act(() => separator.focus());
+    fireEvent.keyDown(separator, {key: 'Enter'}); // collapse
+    expect(separator).toHaveAttribute('aria-valuetext', 'Collapsed');
+
+    fireEvent.keyDown(separator, {key: 'Enter'}); // expand again
+    expect(separator).not.toHaveAttribute('aria-valuetext');
+    expect(separator).toHaveAttribute('aria-valuenow', '100');
   });
 
   // --- Disabled guard ---
@@ -290,8 +338,9 @@ describe('ResizeHandle', () => {
   it('centers the grab zone on the divider when the pill is centered (no bias)', () => {
     render(<Harness handleProps={{pillPlacement: 'center'}} />);
     const hitArea = getSeparator().firstElementChild as HTMLElement;
-    // No physical offset — a plain logical centering class, no biased transform.
-    expect(hitArea.className).toContain('hitAreaCenteredX');
+    // Centered via the shared rtlStyles.centerInline helper (direction-symmetric
+    // left+translateX), not a biased offset.
+    expect(hitArea.className).toContain('centerInline');
     expect(hitArea.className).not.toContain('hitAreaOffsetX');
   });