@multiplatform.one/components 7.4.1 → 7.6.0

package/src/Skeleton/Skeleton.spec.tsx

@@ -0,0 +1,282 @@
+/**
+ * Skeleton / SkeletonText / SkeletonCircle — design-law contract.
+ *
+ * Locks LC-20 (anatomy + animation:none), LC-60 (R-PILL circle), LC-61
+ * (specimen a11y: one announcer, decorative bones), LC-80 (size recipe
+ * geometry), and named-export identity.
+ */
+import { Preset, sizeRecipeForToken } from "@multiplatform.one/theme";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import * as SkeletonExports from "./index";
+import { Skeleton, SkeletonCircle, SkeletonGroup, SkeletonText } from "./index";
+
+afterEach(cleanup);
+
+function radiusClasses(el: Element): string[] {
+  return String((el as HTMLElement).className || "")
+    .split(" ")
+    .filter((c) => c.startsWith("_btlr-"));
+}
+
+describe("Skeleton named exports", () => {
+  it("serves named exports only (no default) and keeps the namespace statics", () => {
+    expect(SkeletonExports.default).toBeUndefined();
+    expect(SkeletonExports.Skeleton).toBe(Skeleton);
+    expect(SkeletonExports.SkeletonText).toBe(SkeletonText);
+    expect(SkeletonExports.SkeletonCircle).toBe(SkeletonCircle);
+    expect(SkeletonExports.SkeletonGroup).toBe(SkeletonGroup);
+    expect(Skeleton.Text).toBe(SkeletonText);
+    expect(Skeleton.Circle).toBe(SkeletonCircle);
+    expect(Skeleton.Group).toBe(SkeletonGroup);
+  });
+});
+
+describe("Skeleton — LC-20 / LC-61 announcer and motion", () => {
+  it("announces a root bone as a polite busy status", () => {
+    const { container } = renderWithProviders(<Skeleton width={200} />);
+    const bone = container.querySelector("[data-skeleton]") as HTMLElement;
+    expect(bone.getAttribute("role")).toBe("status");
+    expect(bone.getAttribute("aria-busy")).toBe("true");
+    expect(bone.getAttribute("aria-live")).toBe("polite");
+    expect(bone.getAttribute("aria-label")).toBe("Loading");
+    expect(bone.getAttribute("data-skeleton-variant")).toBe("text");
+    expect(bone.getAttribute("tabindex")).toBeNull();
+  });
+
+  it("pulses by default and goes static when animate=false", () => {
+    const live = renderWithProviders(<Skeleton width={120} />);
+    const liveBone = live.container.querySelector("[data-skeleton]") as HTMLElement;
+    expect(liveBone.getAttribute("data-animate")).toBe("true");
+    expect(liveBone.className).toMatch(/mp-skeleton-pulse/);
+    expect(liveBone.className).not.toMatch(/mp-skeleton-static/);
+    cleanup();
+
+    const still = renderWithProviders(<Skeleton width={120} animate={false} />);
+    const stillBone = still.container.querySelector("[data-skeleton]") as HTMLElement;
+    expect(stillBone.getAttribute("data-animate")).toBe("false");
+    expect(stillBone.className).toMatch(/mp-skeleton-static/);
+    expect(stillBone.className).not.toMatch(/mp-skeleton-pulse/);
+  });
+
+  it("animation:none stops the pulse even when animate is true (LC-20 / LC-68)", () => {
+    const { container } = renderWithProviders(
+      <Preset overrides={{ animation: "none" }}>
+        <Skeleton width={120} animate />
+      </Preset>,
+    );
+    const bone = container.querySelector("[data-skeleton]") as HTMLElement;
+    expect(bone.getAttribute("data-animate")).toBe("false");
+    expect(bone.className).toMatch(/mp-skeleton-static/);
+  });
+
+  it("never accepts pointer events", () => {
+    const { container } = renderWithProviders(<Skeleton width={80} height={16} />);
+    const bone = container.querySelector("[data-skeleton]") as HTMLElement;
+    expect(bone.className).toMatch(/_pe-none/);
+  });
+
+  it("fillStyle does not recolour the bone (neutral chrome)", () => {
+    const filled = renderWithProviders(
+      <Preset overrides={{ fillStyle: "filled" }}>
+        <Skeleton width={80} />
+      </Preset>,
+    );
+    const outlined = renderWithProviders(
+      <Preset overrides={{ fillStyle: "outlined" }}>
+        <Skeleton width={80} />
+      </Preset>,
+    );
+    const filledBg = String(
+      (filled.container.querySelector("[data-skeleton]") as HTMLElement).className,
+    )
+      .split(" ")
+      .filter((c) => c.startsWith("_bg-"))
+      .sort()
+      .join(" ");
+    const outlinedBg = String(
+      (outlined.container.querySelector("[data-skeleton]") as HTMLElement).className,
+    )
+      .split(" ")
+      .filter((c) => c.startsWith("_bg-"))
+      .sort()
+      .join(" ");
+    expect(filledBg).toBe(outlinedBg);
+    expect(filledBg.length).toBeGreaterThan(0);
+  });
+});
+
+describe("Skeleton — radius classes (LC-20 / LC-60)", () => {
+  it("text bones go square at radius:none and clamp at full (R-CLAMP)", () => {
+    const none = renderWithProviders(
+      <Preset overrides={{ borderRadius: "none" }}>
+        <Skeleton variant="text" width={120} />
+      </Preset>,
+    );
+    expect(radiusClasses(none.container.querySelector("[data-skeleton]") as Element)).toEqual([
+      "_btlr-0px",
+    ]);
+    cleanup();
+
+    const full = renderWithProviders(
+      <Preset overrides={{ borderRadius: "full" }}>
+        <Skeleton variant="text" width={120} />
+      </Preset>,
+    );
+    expect(radiusClasses(full.container.querySelector("[data-skeleton]") as Element)).toEqual([
+      "_btlr-t-radius-2",
+    ]);
+  });
+
+  it("rounded bones track the radius knob (R-SCALE)", () => {
+    const none = renderWithProviders(
+      <Preset overrides={{ borderRadius: "none" }}>
+        <Skeleton variant="rounded" width={80} height={32} />
+      </Preset>,
+    );
+    expect(radiusClasses(none.container.querySelector("[data-skeleton]") as Element)).toEqual([
+      "_btlr-t-radius-0",
+    ]);
+    cleanup();
+
+    const full = renderWithProviders(
+      <Preset overrides={{ borderRadius: "full" }}>
+        <Skeleton variant="rounded" width={80} height={32} />
+      </Preset>,
+    );
+    expect(radiusClasses(full.container.querySelector("[data-skeleton]") as Element)).toEqual([
+      "_btlr-t-radius-12",
+    ]);
+  });
+
+  it("circular bones declare R-PILL and stay round at radius:none", () => {
+    const { container } = renderWithProviders(
+      <Preset overrides={{ borderRadius: "none" }}>
+        <Skeleton variant="circular" width={40} height={40} />
+      </Preset>,
+    );
+    const bone = container.querySelector("[data-skeleton]") as HTMLElement;
+    expect(bone.getAttribute("data-radius-class")).toBe("R-PILL");
+    expect(bone.getAttribute("data-radius-part")).toBe("SkeletonCircle");
+    expect(bone.getAttribute("data-skeleton-variant")).toBe("circular");
+  });
+
+  it("rectangular bones stay square (no radius class, no R-PILL)", () => {
+    const { container } = renderWithProviders(
+      <Preset overrides={{ borderRadius: "full" }}>
+        <Skeleton variant="rectangular" width={80} height={32} />
+      </Preset>,
+    );
+    const bone = container.querySelector("[data-skeleton]") as HTMLElement;
+    expect(bone.getAttribute("data-radius-class")).toBeNull();
+    expect(radiusClasses(bone)).toEqual(["_btlr-0px"]);
+  });
+});
+
+describe("SkeletonText", () => {
+  it("announces once; child bones are decorative", () => {
+    const { container } = renderWithProviders(<SkeletonText lines={3} />);
+    const stack = container.querySelector("[data-skeleton-text]") as HTMLElement;
+    expect(stack.getAttribute("role")).toBe("status");
+    expect(stack.getAttribute("aria-busy")).toBe("true");
+    expect(stack.getAttribute("data-lines")).toBe("3");
+    const bones = container.querySelectorAll("[data-skeleton]");
+    expect(bones).toHaveLength(3);
+    for (const bone of bones) {
+      expect(bone.getAttribute("aria-hidden")).toBe("true");
+      expect(bone.getAttribute("role")).toBeNull();
+    }
+  });
+
+  it("renders nothing for 0 or negative lines", () => {
+    expect(
+      renderWithProviders(<SkeletonText lines={0} />).container.querySelector("[data-skeleton]"),
+    ).toBeNull();
+    cleanup();
+    expect(
+      renderWithProviders(<SkeletonText lines={-4} />).container.querySelector("[data-skeleton]"),
+    ).toBeNull();
+  });
+
+  it("shortens only the last line when more than one line exists", () => {
+    const { container } = renderWithProviders(<SkeletonText lines={3} lastLineWidth="40%" />);
+    const bones = [...container.querySelectorAll("[data-skeleton]")] as HTMLElement[];
+    expect(bones).toHaveLength(3);
+    expect(bones[0].getAttribute("data-width")).toBe("100%");
+    expect(bones[1].getAttribute("data-width")).toBe("100%");
+    expect(bones[2].getAttribute("data-width")).toBe("40%");
+  });
+
+  it("space knob drives the line gap (SP-GAP)", () => {
+    const small = renderWithProviders(
+      <Preset overrides={{ space: "small" }}>
+        <SkeletonText lines={2} />
+      </Preset>,
+    );
+    const large = renderWithProviders(
+      <Preset overrides={{ space: "large" }}>
+        <SkeletonText lines={2} />
+      </Preset>,
+    );
+    const smallGap = String(
+      (small.container.querySelector("[data-skeleton-text]") as HTMLElement).className,
+    );
+    const largeGap = String(
+      (large.container.querySelector("[data-skeleton-text]") as HTMLElement).className,
+    );
+    expect(smallGap).not.toEqual(largeGap);
+  });
+});
+
+describe("SkeletonCircle", () => {
+  it("stays 1:1 and scales with the size recipe when size is omitted", () => {
+    const medium = renderWithProviders(<SkeletonCircle />);
+    const mediumBone = medium.container.querySelector("[data-skeleton]") as HTMLElement;
+    expect(mediumBone.getAttribute("data-radius-class")).toBe("R-PILL");
+    expect(mediumBone.getAttribute("data-skeleton-variant")).toBe("circular");
+    const mediumMax = sizeRecipeForToken("$5").height;
+    expect(Number(mediumBone.getAttribute("data-diameter"))).toBe(mediumMax);
+    cleanup();
+
+    const small = renderWithProviders(
+      <Preset overrides={{ size: "small" }}>
+        <SkeletonCircle />
+      </Preset>,
+    );
+    const smallBone = small.container.querySelector("[data-skeleton]") as HTMLElement;
+    const smallMax = sizeRecipeForToken("$4").height;
+    const smallVal = Number(smallBone.getAttribute("data-diameter"));
+    expect(smallVal).toBe(smallMax);
+    expect(smallVal).toBeLessThan(mediumMax);
+  });
+
+  it("honors an explicit size and a zero diameter", () => {
+    const sized = renderWithProviders(<SkeletonCircle size={64} />);
+    const sizedBone = sized.container.querySelector("[data-skeleton]") as HTMLElement;
+    expect(Number(sizedBone.getAttribute("data-diameter"))).toBe(64);
+    cleanup();
+
+    const zero = renderWithProviders(<SkeletonCircle size={0} />);
+    const zeroBone = zero.container.querySelector("[data-skeleton]") as HTMLElement;
+    expect(Number(zeroBone.getAttribute("data-diameter"))).toBe(0);
+  });
+});
+
+describe("SkeletonGroup", () => {
+  it("announces the group once so nested bones stay decorative", () => {
+    const { container } = renderWithProviders(
+      <SkeletonGroup>
+        <Skeleton width={80} />
+        <SkeletonText lines={2} />
+      </SkeletonGroup>,
+    );
+    const group = container.querySelector("[data-skeleton-group]") as HTMLElement;
+    expect(group.getAttribute("role")).toBe("status");
+    expect(group.getAttribute("aria-busy")).toBe("true");
+    expect(container.querySelectorAll('[role="status"]')).toHaveLength(1);
+    for (const bone of container.querySelectorAll("[data-skeleton]")) {
+      expect(bone.getAttribute("aria-hidden")).toBe("true");
+    }
+  });
+});

package/src/Skeleton/SkeletonCircle.stories.tsx

@@ -6,14 +6,14 @@ const meta: Meta<typeof SkeletonCircle> = {
   title: "Components/SkeletonCircle",
   component: SkeletonCircle,
   parameters: {
-    status: { type: "beta" },
+    status: { type: "stable" },
     // D-10 SKELETONS-RESOLVE: explicitly-labeled skeleton specimen (the
     // skeleton is the subject here, not a promise about pending data).
     skeletonSpecimen: true,
     docs: {
       description: {
         component:
-          "SKELETON SPECIMEN (D-10). Circular loading placeholder (avatar-shaped). Default diameter 40px. Skeletons persist on this page by design; product surfaces must show zero skeletons once their pending source settles.",
+          "SKELETON SPECIMEN (D-10). Circular loading placeholder (avatar-shaped). Default diameter follows the size recipe (LC-80): one height step above the control ramp, 1:1 at every radius (R-PILL). Skeletons persist on this page by design; product surfaces must show zero skeletons once their pending source settles.",
       },
     },
   },

package/src/Skeleton/SkeletonText.stories.tsx

@@ -6,7 +6,7 @@ const meta: Meta<typeof SkeletonText> = {
   title: "Components/SkeletonText",
   component: SkeletonText,
   parameters: {
-    status: { type: "beta" },
+    status: { type: "stable" },
     // D-10 SKELETONS-RESOLVE: explicitly-labeled skeleton specimen (the
     // skeleton is the subject here, not a promise about pending data).
     skeletonSpecimen: true,

package/src/Skeleton/index.tsx

@@ -106,10 +106,14 @@ export function Skeleton({
   if (isWeb) ensureShimmerStyles();
 
   const decorative = props["aria-hidden"] === true || !shouldAnnounce;
+  // Corner-smoothing is an R-SCALE/R-CLAMP arc. Circular is R-PILL (a
+  // squircle would break 1:1); rectangular is square by variant.
+  const smoothingClass =
+    variant === "text" || variant === "rounded" ? knobProps.borderRadius.className : undefined;
   const boneClass = [
     "mp-skeleton-bone",
     pulsing ? "mp-skeleton-pulse" : "mp-skeleton-static",
-    variant !== "rectangular" ? knobProps.borderRadius.className : undefined,
+    smoothingClass,
     className,
   ]
     .filter(Boolean)
@@ -138,6 +142,16 @@ export function Skeleton({
       {...(style ? { style } : undefined)}
       pointerEvents="none"
       data-skeleton=""
+      data-skeleton-variant={variant}
+      data-animate={pulsing ? "true" : "false"}
+      data-width={width != null ? String(width) : undefined}
+      data-height={
+        height != null
+          ? String(height)
+          : variant === "text"
+            ? String(resolveTextHeight(knobProps.sizeToken, "body"))
+            : undefined
+      }
       aria-hidden={decorative ? true : undefined}
       role={decorative ? undefined : "status"}
       aria-busy={decorative ? undefined : true}
@@ -185,6 +199,7 @@ export function SkeletonText({
         width={width ?? "100%"}
         gap={gap}
         data-skeleton-text=""
+        data-lines={String(count)}
         aria-hidden={decorative ? true : undefined}
         role={decorative ? undefined : "status"}
         aria-busy={decorative ? undefined : true}
@@ -224,6 +239,7 @@ export function SkeletonCircle({
       maxWidth={diameter}
       aspectRatio={1}
       alignSelf="flex-start"
+      data-diameter={String(diameter)}
     />
   );
 }

package/src/SkipLink/SkipLink.spec.tsx

@@ -64,6 +64,15 @@ describe("SkipLink", () => {
     expect(target.getAttribute("tabindex")).toBe("-1");
   });
 
+  it("paints the skip label at weight 400 (R7 / §6.1)", () => {
+    const { container } = renderWithTarget();
+    const label = container.querySelector("a.mp-skip-link")?.querySelector("span, p, div");
+    const node = (label ?? container.querySelector("a.mp-skip-link")) as HTMLElement;
+    expect(node).toBeTruthy();
+    const weight = node.style.fontWeight || getComputedStyle(node).fontWeight;
+    expect(["400", "normal"]).toContain(String(weight));
+  });
+
   it("reports the focused target through onSkip", () => {
     const onSkip = vi.fn();
     const { container } = renderWithProviders(

package/src/SkipLink/index.tsx

@@ -181,8 +181,8 @@ export function SkipLink({
       >
         <SizableText
           {...knobProps.body}
-          fontWeight="600"
-          fontSize="$3"
+          {...knobProps.label}
+          fontWeight="400"
           color="$color12"
           whiteSpace="nowrap"
         >

package/src/SortableList/SortableHandle.tsx

@@ -0,0 +1,97 @@
+import {
+  ensureKeyboardModalityTracking,
+  keyboardFocusRingProps,
+  useResolvedKnobs,
+  wasKeyboardFocus,
+} from "@multiplatform.one/theme";
+import { DotsSixVerticalIcon } from "@phosphor-icons/react";
+import { useState } from "react";
+import { View } from "tamagui";
+import { useTranslation } from "../shared/i18n";
+import { withInterp } from "../shared/t";
+import { useSortableDragging } from "./useSortableRows";
+
+const GRIP_PX = 16;
+
+export interface SortableHandleProps {
+  label: string;
+  itemId: string;
+  dragging?: boolean;
+  compact?: boolean;
+  onPointerDown?: (e: {
+    pointerType?: string;
+    clientY: number;
+    preventDefault?: () => void;
+  }) => void;
+  onKeyDown?: (e: { key: string; preventDefault: () => void }) => void;
+}
+
+/**
+ * Leading grab handle: nested well, 16px 6-dot grip, opacity .45 → 1.
+ * Focusable (W1-focus-ring): 2px ring, offset 0. Keyboard path can also
+ * live on the row — this control is tabIndex 0 so tables have a target
+ * that is not an in-cell editor.
+ */
+export function SortableHandle({
+  label,
+  itemId,
+  dragging,
+  compact,
+  onPointerDown,
+  onKeyDown,
+}: SortableHandleProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs({ compact });
+  const well = knobProps.nestedControl.px;
+  const [kb, setKb] = useState(false);
+  const isDragging = useSortableDragging(itemId, dragging);
+  if (typeof document !== "undefined") ensureKeyboardModalityTracking();
+
+  return (
+    <View
+      role="button"
+      tabIndex={0}
+      aria-label={withInterp(t("Reorder {{label}}", { label }), { label })}
+      width={well}
+      height={well}
+      minWidth={well}
+      minHeight={well}
+      alignItems="center"
+      justifyContent="center"
+      opacity={isDragging ? 1 : 0.45}
+      hoverStyle={{ opacity: 1 }}
+      {...({
+        tag: "button",
+        cursor: isDragging ? "grabbing" : "grab",
+        hitSlop: knobProps.nestedControl.hitSlop,
+        ...(kb ? keyboardFocusRingProps : {}),
+        "data-sortable-handle": itemId,
+        "data-focus-ring": "2/0",
+        onPointerDown: (e: {
+          pointerType?: string;
+          clientY: number;
+          preventDefault?: () => void;
+        }) => onPointerDown?.(e),
+        onKeyDown: (e: { key: string; preventDefault: () => void }) => onKeyDown?.(e),
+        onFocus: () => setKb(wasKeyboardFocus()),
+        onBlur: () => setKb(false),
+      } as Record<string, unknown>)}
+    >
+      <DotsSixVerticalIcon size={GRIP_PX} weight="bold" />
+    </View>
+  );
+}
+
+export function SortableHandleWell({ itemId, compact }: { itemId: string; compact?: boolean }) {
+  const { knobProps } = useResolvedKnobs({ compact });
+  const well = knobProps.nestedControl.px;
+  return (
+    <View
+      width={well}
+      height={well}
+      minWidth={well}
+      minHeight={well}
+      {...({ "data-sortable-well": itemId } as Record<string, unknown>)}
+    />
+  );
+}

package/src/SortableList/SortableList.spec.tsx

@@ -0,0 +1,122 @@
+import { fireEvent } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { useState } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { SortableList } from "./index";
+
+const ITEMS = [
+  { id: "mon", label: "Monday standup" },
+  { id: "tue", label: "Tuesday review" },
+  { id: "dep", label: "Deploy window" },
+  { id: "ret", label: "Retro notes" },
+];
+
+function Harness({
+  onChange = vi.fn(),
+  readOnly,
+  canReorder,
+}: {
+  onChange?: (next: typeof ITEMS) => void;
+  readOnly?: boolean;
+  canReorder?: (item: (typeof ITEMS)[number], index: number) => boolean;
+}) {
+  const [items, setItems] = useState(ITEMS);
+  return (
+    <SortableList
+      items={items}
+      getId={(item) => item.id}
+      getLabel={(item) => item.label}
+      canReorder={canReorder}
+      readOnly={readOnly}
+      onChange={(next) => {
+        setItems(next);
+        onChange(next);
+      }}
+    />
+  );
+}
+
+function liveRegion() {
+  return document.querySelector('[data-sortable-live="true"]');
+}
+
+describe("SortableList", () => {
+  it("completes a keyboard-only reorder and announces each step (LC-43, board 03)", () => {
+    const onChange = vi.fn();
+    const { container } = renderWithProviders(<Harness onChange={onChange} />);
+    const rows = container.querySelectorAll("[data-sortable-row]");
+    expect(rows).toHaveLength(4);
+
+    const tuesday = container.querySelector('[data-sortable-row="tue"]') as HTMLElement;
+    tuesday.focus();
+    fireEvent.keyDown(tuesday, { key: " " });
+    expect(liveRegion()?.getAttribute("aria-live")).toBe("polite");
+    expect(liveRegion()?.textContent).toBe(
+      "Lifted “Tuesday review”, position 2 of 4. Use arrow keys to move, space to drop, escape to cancel.",
+    );
+
+    fireEvent.keyDown(tuesday, { key: "ArrowDown" });
+    expect(liveRegion()?.textContent).toBe("Moved “Tuesday review”, position 3 of 4.");
+
+    fireEvent.keyDown(tuesday, { key: "ArrowDown" });
+    expect(liveRegion()?.textContent).toBe("Moved “Tuesday review”, position 4 of 4.");
+
+    const beforeBoundary = liveRegion()?.textContent;
+    fireEvent.keyDown(tuesday, { key: "ArrowDown" });
+    expect(liveRegion()?.textContent).toBe(beforeBoundary);
+
+    fireEvent.keyDown(tuesday, { key: " " });
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange.mock.calls[0][0].map((r: { id: string }) => r.id)).toEqual([
+      "mon",
+      "dep",
+      "ret",
+      "tue",
+    ]);
+    expect(liveRegion()?.textContent).toBe("Dropped “Tuesday review”, position 4 of 4.");
+    expect(document.activeElement?.getAttribute("data-sortable-row")).toBe("tue");
+  });
+
+  it("cancels a lift with Escape and leaves the list unchanged", () => {
+    const onChange = vi.fn();
+    const { container } = renderWithProviders(<Harness onChange={onChange} />);
+    const tuesday = container.querySelector('[data-sortable-row="tue"]') as HTMLElement;
+    tuesday.focus();
+    fireEvent.keyDown(tuesday, { key: " " });
+    fireEvent.keyDown(tuesday, { key: "ArrowDown" });
+    fireEvent.keyDown(tuesday, { key: "Escape" });
+    expect(onChange).not.toHaveBeenCalled();
+    expect(liveRegion()?.textContent).toBe(
+      "Reorder cancelled. “Tuesday review” returned to position 2.",
+    );
+    expect(
+      container.querySelectorAll("[data-sortable-row]")[1].getAttribute("data-sortable-row"),
+    ).toBe("tue");
+  });
+
+  it("paints the grab handle as a focusable with a 2px offset-0 ring well", () => {
+    const { container } = renderWithProviders(<Harness />);
+    const handle = container.querySelector('[data-sortable-handle="tue"]') as HTMLElement;
+    expect(handle.getAttribute("role")).toBe("button");
+    expect(handle.getAttribute("aria-label")).toMatch(/Tuesday review/);
+    expect(handle.tabIndex).toBe(0);
+    handle.focus();
+    expect(
+      handle.style.outlineWidth === "2px" || handle.getAttribute("data-focus-ring") === "2/0",
+    ).toBe(true);
+  });
+
+  it("omits the handle on a row that cannot drag and reserves the well", () => {
+    const { container } = renderWithProviders(<Harness canReorder={(item) => item.id !== "tue"} />);
+    expect(container.querySelector('[data-sortable-handle="tue"]')).toBeNull();
+    expect(container.querySelector('[data-sortable-well="tue"]')).toBeTruthy();
+    expect(
+      container.querySelector('[data-sortable-row="tue"]')?.getAttribute("aria-disabled"),
+    ).toBe("true");
+  });
+
+  it("renders no handles when readOnly", () => {
+    const { container } = renderWithProviders(<Harness readOnly />);
+    expect(container.querySelectorAll("[data-sortable-handle]")).toHaveLength(0);
+  });
+});

package/src/SortableList/SortableList.stories.tsx

@@ -0,0 +1,55 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useState } from "react";
+import { SortableList } from "./index";
+
+const SEED = [
+  { id: "mon", label: "Monday standup" },
+  { id: "tue", label: "Tuesday review" },
+  { id: "dep", label: "Deploy window" },
+  { id: "ret", label: "Retro notes" },
+];
+
+const meta: Meta<typeof SortableList> = {
+  title: "Components/SortableList",
+  component: SortableList,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Grab-handle plus keyboard reorder. One kanbanDnd session serves List, DataTable, and ChildTable (LC-16 / LC-43).",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof SortableList>;
+
+function Demo(props: { readOnly?: boolean; locked?: string }) {
+  const [items, setItems] = useState(SEED);
+  return (
+    <SortableList
+      items={items}
+      getId={(item) => item.id}
+      getLabel={(item) => item.label}
+      canReorder={props.locked ? (item) => item.id !== props.locked : undefined}
+      readOnly={props.readOnly}
+      onChange={setItems}
+      aria-label="Sprint rituals"
+    />
+  );
+}
+
+export const Default: Story = {
+  name: "Main",
+  render: () => <Demo />,
+};
+
+export const ReadOnly: Story = {
+  render: () => <Demo readOnly />,
+};
+
+export const LockedRow: Story = {
+  render: () => <Demo locked="tue" />,
+};