@multiplatform.one/components 7.78.0 → 7.80.0

package/src/MachineLiteral/MachineLiteral.spec.tsx

@@ -0,0 +1,86 @@
+/**
+ * LC-221 MACHINE-LITERAL: the literal renders byte for byte in $mono, never
+ * re-cased or cut; the reading shows when a formatter derives one; the copy
+ * glyph writes the literal itself.
+ */
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, fireEvent, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { resetFeedback } from "../feedback/store";
+import { resetToasts } from "../Toast/store";
+import { MachineLiteral, type MachineLiteralProps } from "./index";
+import meta, { Default, Literals } from "./MachineLiteral.stories";
+
+const writeText = vi.fn();
+
+beforeEach(() => {
+  writeText.mockReset();
+  writeText.mockResolvedValue(undefined);
+  vi.stubGlobal("navigator", {
+    ...(typeof navigator !== "undefined" ? navigator : {}),
+    clipboard: { writeText },
+  });
+  resetToasts();
+  resetFeedback();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  resetToasts();
+  resetFeedback();
+});
+
+const digest = "sha256:9F86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08";
+
+function literalOf(container: HTMLElement) {
+  return container.querySelector("[data-machine-literal]") as HTMLElement;
+}
+
+describe("MachineLiteral (LC-221)", () => {
+  it("renders the literal byte for byte in the mono voice, uncut", () => {
+    const { container } = renderWithProviders(<MachineLiteral value={digest} label="digest" />);
+    const literal = literalOf(container);
+    expect(literal.textContent).toBe(digest);
+    expect(literal.className + (literal.getAttribute("style") ?? "")).toMatch(/mono/i);
+    expect(literal.textContent).not.toContain("…");
+  });
+
+  it("the copy glyph writes the literal and is named for it", async () => {
+    const { container } = renderWithProviders(<MachineLiteral value={digest} label="digest" />);
+    const copy = container.querySelector("[aria-label='Copy digest']") as HTMLElement;
+    expect(copy).toBeTruthy();
+    expect(copy.textContent?.trim()).toBe("");
+    fireEvent.click(copy);
+    await waitFor(() => expect(writeText).toHaveBeenCalledWith(digest));
+  });
+
+  it("shows the reading beside the literal only when the formatter derives one", () => {
+    const reading = (cron: string) => (cron === "0 2 * * *" ? "daily at 02:00" : undefined);
+    const daily = renderWithProviders(<MachineLiteral value="0 2 * * *" reading={reading} />);
+    expect(daily.container.querySelector("[data-machine-reading]")?.textContent).toBe(
+      "daily at 02:00",
+    );
+    expect(literalOf(daily.container).textContent).toBe("0 2 * * *");
+    daily.unmount();
+
+    const odd = renderWithProviders(<MachineLiteral value="*/7 3 * * 1" reading={reading} />);
+    expect(odd.container.querySelector("[data-machine-reading]")).toBeNull();
+    expect(literalOf(odd.container).textContent).toBe("*/7 3 * * 1");
+  });
+
+  it("the stories mount: Main reads the cron, Literals keep each literal verbatim", () => {
+    expect(meta.title).toBe("Components/MachineLiteral");
+    const main = renderWithProviders(<MachineLiteral {...(Default.args as MachineLiteralProps)} />);
+    expect(main.container.querySelector("[data-machine-reading]")?.textContent).toBe(
+      "daily at 02:00",
+    );
+    main.unmount();
+    const all = renderWithProviders(<>{Literals.render?.({} as never, {} as never)}</>);
+    const values = [...all.container.querySelectorAll("[data-machine-literal]")].map(
+      (node) => node.textContent,
+    );
+    expect(values).toContain("ERR_TLS_CERT_ALTNAME_INVALID");
+    expect(values).toContain("SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8");
+  });
+});

package/src/MachineLiteral/MachineLiteral.stories.tsx

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { YStack } from "tamagui";
+import { MachineLiteral } from "./index";
+
+const meta: Meta<typeof MachineLiteral> = {
+  title: "Components/MachineLiteral",
+  component: MachineLiteral,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "A machine literal in display (LC-221): verbatim in $mono, its human reading beside it, and a bare copy glyph that writes the literal byte for byte. In a field, use CopyField.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof MachineLiteral>;
+
+const cronReading = (cron: string) => (cron === "0 2 * * *" ? "daily at 02:00" : undefined);
+
+export const Default: Story = {
+  name: "Main",
+  args: { value: "0 2 * * *", reading: cronReading, label: "cron expression" },
+};
+
+export const Literals: Story = {
+  render: () => (
+    <YStack gap="$3">
+      <MachineLiteral value="0 2 * * *" reading={cronReading} label="cron expression" />
+      <MachineLiteral
+        value="sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
+        label="digest"
+      />
+      <MachineLiteral
+        value="SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8"
+        label="fingerprint"
+      />
+      <MachineLiteral value="ERR_TLS_CERT_ALTNAME_INVALID" label="error code" />
+    </YStack>
+  ),
+};

package/src/MachineLiteral/index.tsx

@@ -0,0 +1,75 @@
+/**
+ * MachineLiteral — a cron expression, digest, fingerprint, error code or key
+ * id in display (LC-221). The literal renders verbatim in `$mono`, never
+ * re-cased or cut; its human reading sits beside it when one is given or
+ * derived; a bare copy glyph (LC-176) writes the literal byte for byte. In a
+ * field, the same literal is a CopyField.
+ */
+import { CopyIcon } from "@phosphor-icons/react";
+import { Button } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { Text, XStack, YStack, type XStackProps } from "tamagui";
+import { NotifyRegion } from "../feedback/NotifyHost";
+import { useCopyFeedback } from "../feedback/copy";
+import { useTranslation } from "../shared/i18n";
+import { withInterp } from "../shared/t";
+
+export interface MachineLiteralProps extends Omit<XStackProps, "children"> {
+  /** The literal, shown and copied exactly as given. */
+  value: string;
+  /** Its human reading, or a formatter that derives one ("daily at 02:00"). */
+  reading?: string | ((value: string) => string | null | undefined);
+  /** What the literal is, for the copy action's name ("cron expression"). */
+  label?: string;
+  /** False drops the copy action (default true). */
+  copyable?: boolean;
+}
+
+export function MachineLiteral({
+  value,
+  reading,
+  label,
+  copyable = true,
+  ...rowProps
+}: MachineLiteralProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs({ component: "MachineLiteral" });
+  const { region, copy } = useCopyFeedback();
+  const readingText = typeof reading === "function" ? reading(value) : reading;
+  const copyLabel = label ? withInterp(t("Copy {{label}}", { label }), { label }) : t("Copy");
+  return (
+    <YStack>
+      <XStack alignItems="center" {...knobProps.gapSm} flexWrap="wrap" {...rowProps}>
+        <Text
+          {...knobProps.body}
+          fontFamily="$mono"
+          letterSpacing={0}
+          color="$color12"
+          selectable
+          userSelect="text"
+          data-machine-literal=""
+        >
+          {value}
+        </Text>
+        {readingText ? (
+          <Text {...knobProps.body} {...knobProps.textRole.meta} data-machine-reading="">
+            {readingText}
+          </Text>
+        ) : null}
+        {copyable ? (
+          <Button
+            chromeless
+            size={knobProps.sizeToken}
+            icon={CopyIcon}
+            aria-label={copyLabel}
+            onPress={() => {
+              void copy(value);
+            }}
+            data-machine-copy=""
+          />
+        ) : null}
+      </XStack>
+      {copyable ? <NotifyRegion scope="field" region={region} size="$3" /> : null}
+    </YStack>
+  );
+}

package/src/Material/blur.native.spec.tsx

@@ -0,0 +1,135 @@
+/**
+ * The material's native blur (FZ-8099): expo-blur when the binary carries it,
+ * the theme fill when it does not, so an OTA never crashes an older build.
+ */
+import { TestProviders, renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, renderHook, screen } from "@testing-library/react";
+import { readFileSync, readdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  type BlurSources,
+  type MaterialBlurView,
+  blurNativeModule,
+  blurTintFor,
+  materialBlurTint,
+  resolveBlurView,
+} from "./blur.native";
+import { Material, useMaterial } from "./index";
+
+const blurState = vi.hoisted(() => ({ present: false }));
+
+vi.mock("@multiplatform.one/platform", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@multiplatform.one/platform")>()),
+  isWeb: false,
+  isNative: true,
+}));
+
+vi.mock("./blur", () => ({
+  useMaterialBlur: () =>
+    blurState.present ? { BlurView: () => null, tint: "systemChromeMaterialLight" } : null,
+  MaterialBlurFill: ({ radius }: { radius?: number }) =>
+    blurState.present ? <span data-testid="material-blur" data-radius={radius} /> : null,
+}));
+
+afterEach(() => {
+  cleanup();
+  blurState.present = false;
+});
+
+const FakeBlurView: MaterialBlurView = () => null;
+
+function sources(nativeModule: unknown, blur: () => { BlurView?: MaterialBlurView }): BlurSources {
+  return { core: () => ({ requireOptionalNativeModule: () => nativeModule }), blur };
+}
+
+describe("native blur detection", () => {
+  it("draws expo-blur's view on iOS when the binary registers ExpoBlur", () => {
+    const probe = vi.fn((name: string) => (name === blurNativeModule ? {} : null));
+    const view = resolveBlurView(
+      {
+        core: () => ({ requireOptionalNativeModule: probe }),
+        blur: () => ({ BlurView: FakeBlurView }),
+      },
+      "ios",
+    );
+    expect(view).toBe(FakeBlurView);
+    expect(probe).toHaveBeenCalledWith("ExpoBlur");
+  });
+
+  it("never requires expo-blur on a binary without its native module", () => {
+    const blur = vi.fn(() => ({ BlurView: FakeBlurView }));
+    expect(resolveBlurView(sources(null, blur), "ios")).toBeNull();
+    expect(blur).not.toHaveBeenCalled();
+  });
+
+  it("falls back when expo-modules-core or expo-blur cannot load", () => {
+    const throws = () => {
+      throw new Error("Cannot find module");
+    };
+    expect(
+      resolveBlurView({ core: throws, blur: () => ({ BlurView: FakeBlurView }) }, "ios"),
+    ).toBeNull();
+    expect(resolveBlurView(sources({}, throws), "ios")).toBeNull();
+  });
+
+  it("keeps the fill on Android, where expo-blur needs a BlurTargetView to blur", () => {
+    const blur = vi.fn(() => ({ BlurView: FakeBlurView }));
+    expect(resolveBlurView(sources({}, blur), "android")).toBeNull();
+    expect(blur).not.toHaveBeenCalled();
+  });
+
+  it("picks the HIG chrome material per colour scheme", () => {
+    expect(blurTintFor("light")).toBe(materialBlurTint.light);
+    expect(blurTintFor("light_accent")).toBe("systemChromeMaterialLight");
+    expect(blurTintFor("dark")).toBe(materialBlurTint.dark);
+    expect(blurTintFor("dark_accent")).toBe("systemChromeMaterialDark");
+  });
+
+  it("probes the name expo-blur registers its view under", () => {
+    const require = createRequire(import.meta.url);
+    const build = join(dirname(require.resolve("expo-blur/package.json")), "build");
+    const names = new Set<string>();
+    for (const file of readdirSync(build).filter((name) => name.endsWith(".js"))) {
+      const source = readFileSync(join(build, file), "utf8");
+      for (const match of source.matchAll(/requireNativeViewManager\(\s*['"]([^'"]+)['"]/g)) {
+        names.add(match[1]!);
+      }
+    }
+    expect([...names]).toEqual([blurNativeModule]);
+  });
+});
+
+describe("Material on native", () => {
+  it("lets the system material paint when the binary has expo-blur", () => {
+    blurState.present = true;
+    const { result } = renderHook(() => useMaterial(), { wrapper: TestProviders });
+    expect(result.current.backgroundColor).toBe("transparent");
+    expect(result.current).toMatchObject({ borderColor: "$borderColor", shadowColor: "$shadow3" });
+    expect(result.current).not.toHaveProperty("backdropFilter");
+  });
+
+  it("keeps the 94% chrome fill when the binary has no expo-blur", () => {
+    const { result } = renderHook(() => useMaterial(), { wrapper: TestProviders });
+    expect(result.current.backgroundColor).toMatch(/^rgba\(\d+, \d+, \d+, 0\.94\)$/);
+  });
+
+  it("puts the blur behind its content, clipped to its radius", () => {
+    blurState.present = true;
+    renderWithProviders(
+      <Material testID="material" borderRadius={20}>
+        <span>inside</span>
+      </Material>,
+    );
+    const material = screen.getByTestId("material");
+    expect(material.firstElementChild?.getAttribute("data-testid")).toBe("material-blur");
+    expect(screen.getByTestId("material-blur").getAttribute("data-radius")).toBe("20");
+    expect(material.textContent).toBe("inside");
+  });
+
+  it("draws no blur view without expo-blur", () => {
+    renderWithProviders(<Material testID="material">inside</Material>);
+    expect(screen.queryByTestId("material-blur")).toBeNull();
+  });
+});

package/src/Material/blur.native.tsx

@@ -0,0 +1,93 @@
+/**
+ * The material's native blur (FZ-8099): expo-blur's BlurView drawing the iOS
+ * system chrome material, when the app binary carries it.
+ *
+ * expo-blur is native code, so it reaches a phone only through a new binary.
+ * An OTA carries this JS to every binary at the same runtimeVersion, including
+ * the ones built before expo-blur was added, so the view is feature-detected
+ * at runtime: `requireOptionalNativeModule("ExpoBlur")` answers null on those
+ * binaries and the material keeps its theme fill. The probe runs before the
+ * `require`, the same order as the picker and maps loaders, because a module
+ * factory that throws is a fatal LogBox in dev even when the caller catches.
+ *
+ * iOS only. On Android expo-blur blurs only content wrapped in a
+ * BlurTargetView it is given a ref to; without one it draws a flat
+ * translucent view, which is what the theme fill already is.
+ */
+import { isDarkThemeName } from "@multiplatform.one/theme";
+import type { ComponentType } from "react";
+import { Platform, StyleSheet, type ViewStyle } from "react-native";
+import { useThemeName } from "tamagui";
+
+/** The name expo-blur registers its native module and view under. */
+export const blurNativeModule = "ExpoBlur";
+
+/** The HIG material a tab bar or toolbar uses, per colour scheme. */
+export const materialBlurTint = {
+  light: "systemChromeMaterialLight",
+  dark: "systemChromeMaterialDark",
+} as const;
+
+export function blurTintFor(themeName: string | undefined): string {
+  return isDarkThemeName(themeName) ? materialBlurTint.dark : materialBlurTint.light;
+}
+
+export type MaterialBlurView = ComponentType<{
+  tint?: string;
+  intensity?: number;
+  pointerEvents?: "none";
+  style?: ViewStyle | ViewStyle[];
+}>;
+
+export interface BlurSources {
+  core: () => { requireOptionalNativeModule?: (name: string) => unknown };
+  blur: () => { BlurView?: MaterialBlurView };
+}
+
+const appSources: BlurSources = {
+  core: () => require("expo-modules-core"),
+  blur: () => require("expo-blur"),
+};
+
+/** The BlurView, or null when this platform or binary cannot draw it. */
+export function resolveBlurView(sources: BlurSources, os: string): MaterialBlurView | null {
+  if (os !== "ios") return null;
+  try {
+    if (sources.core().requireOptionalNativeModule?.(blurNativeModule) == null) return null;
+    return sources.blur().BlurView ?? null;
+  } catch {
+    return null;
+  }
+}
+
+let cached: MaterialBlurView | null | undefined;
+
+function loadBlurView(): MaterialBlurView | null {
+  if (cached === undefined) cached = resolveBlurView(appSources, Platform.OS);
+  return cached;
+}
+
+export function useMaterialBlur(): { BlurView: MaterialBlurView; tint: string } | null {
+  const themeName = useThemeName() as string | undefined;
+  const BlurView = loadBlurView();
+  if (!BlurView) return null;
+  return { BlurView, tint: blurTintFor(themeName) };
+}
+
+/**
+ * The blur behind a material's content: fills its parent inside the hairline
+ * and clips to the parent's corner radius, so the parent keeps its shadow.
+ */
+export function MaterialBlurFill({ radius = 0 }: { radius?: number }) {
+  const blur = useMaterialBlur();
+  if (!blur) return null;
+  const { BlurView, tint } = blur;
+  return (
+    <BlurView
+      tint={tint}
+      intensity={100}
+      pointerEvents="none"
+      style={[StyleSheet.absoluteFill, { borderRadius: radius, overflow: "hidden" }]}
+    />
+  );
+}

package/src/Material/blur.ts

@@ -0,0 +1,11 @@
+/**
+ * The material's native blur, web arm: the browser blurs through
+ * `backdropFilter`, so there is no blur view to draw.
+ */
+export function useMaterialBlur(): null {
+  return null;
+}
+
+export function MaterialBlurFill(_props: { radius?: number }): null {
+  return null;
+}

package/src/Material/index.tsx

@@ -8,13 +8,15 @@
  * The material is one theme token on every platform: the chrome surface
  * step one off the page (`$color2`, as the SystemBar paints it), shown
  * through at the material's opacity, with the hairline and the floating
- * shadow. Web blurs and saturates what is behind it. Native draws the same
- * token at a higher opacity, because React Native has no backdrop blur
- * without a native view in the app binary.
+ * shadow. Web blurs and saturates what is behind it. On iOS, a binary that
+ * carries expo-blur draws the system chrome material instead (FZ-8099,
+ * `blur.native.tsx`); any other native binary draws the token at a higher
+ * opacity, because React Native has no backdrop blur without that view.
  */
 import { hairlineWidth, normalizeToHex } from "@multiplatform.one/theme";
 import { isWeb } from "@multiplatform.one/platform";
 import { forwardRef } from "react";
+import { MaterialBlurFill, useMaterialBlur } from "./blur";
 import { type TamaguiElement, YStack, type YStackProps, useTheme } from "tamagui";
 
 export type MaterialThickness = "chrome";
@@ -45,10 +47,13 @@ export function translucent(color: string | undefined, opacity: number): string
 export function useMaterial(thickness: MaterialThickness = "chrome") {
   const theme = useTheme() as unknown as Record<string, { val?: unknown } | undefined>;
   const { base, blur } = materials[thickness];
+  const nativeBlur = useMaterialBlur();
   const resolved = theme[base.slice(1)]?.val;
   const color = typeof resolved === "string" ? resolved : undefined;
   return {
-    backgroundColor: translucent(color, materialOpacity(thickness)) ?? base,
+    backgroundColor: nativeBlur
+      ? "transparent"
+      : (translucent(color, materialOpacity(thickness)) ?? base),
     borderWidth: hairlineWidth,
     borderColor: "$borderColor",
     shadowColor: "$shadow3",
@@ -64,9 +69,16 @@ export interface MaterialProps extends YStackProps {
 }
 
 export const Material = forwardRef<TamaguiElement, MaterialProps>(function Material(
-  { thickness = "chrome", ...props },
+  { thickness = "chrome", children, ...props },
   ref,
 ) {
   const material = useMaterial(thickness);
-  return <YStack ref={ref} {...material} {...props} />;
+  return (
+    <YStack ref={ref} {...material} {...props}>
+      <MaterialBlurFill
+        radius={typeof props.borderRadius === "number" ? props.borderRadius : undefined}
+      />
+      {children}
+    </YStack>
+  );
 });

package/src/Meter/index.tsx

@@ -23,7 +23,6 @@ import {
   METER_TICK,
   METER_TRACK,
   METER_ZONE_PAINT,
-  UNKNOWN_VALUE,
   formatMeterValue,
   meterFillRatio,
   meterTrackHeightPx,
@@ -114,13 +113,16 @@ function tickLeftPercent(cut: number, min: number, max: number): number | null {
   return ((cut - min) / (max - min)) * 100;
 }
 
+/** LC-220: an unknown level is spoken as no reading, never as a zero or a bare dash. */
+export const NO_READING = "No reading";
+
 function defaultValueText(opts: {
   value?: number | null;
   visible: string;
   unit?: string;
   format?: MeterFormat;
 }): string {
-  if (opts.value == null || !Number.isFinite(opts.value)) return UNKNOWN_VALUE;
+  if (opts.value == null || !Number.isFinite(opts.value)) return NO_READING;
   if (opts.format === "percent") return opts.visible;
   if (opts.unit) return `${opts.visible} used`;
   return opts.visible;

package/src/SortableList/index.tsx

@@ -23,6 +23,8 @@ import { Text } from "../Text";
 export { SortableHandle, SortableHandleWell } from "./SortableHandle";
 export { SortableSessionProvider, useSortableRows } from "./useSortableRows";
 export type { SortableSession, UseSortableRowsOptions } from "./useSortableRows";
+export { applyUserOrder, useUserOrder } from "./useUserOrder";
+export type { UseUserOrderOptions, UserOrderStorage } from "./useUserOrder";
 
 export type SortableDisabledStyle = "keepLabel" | "dimWhole";
 

package/src/SortableList/useUserOrder.spec.tsx

@@ -0,0 +1,110 @@
+/**
+ * LC-209 USER-ORDER: a hand-arranged collection keeps the user's order. A new
+ * item lands last with every other index unchanged, a data refresh that
+ * returns the source's own order changes nothing, and a reload reads the same
+ * arrangement back.
+ */
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { act, cleanup, fireEvent } from "@testing-library/react";
+import { useState } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import { SortableList } from "./index";
+import { applyUserOrder, useUserOrder, type UserOrderStorage } from "./useUserOrder";
+
+afterEach(cleanup);
+
+interface Pin {
+  id: string;
+  label: string;
+}
+
+const source: Pin[] = [
+  { id: "mail", label: "Mail" },
+  { id: "files", label: "Files" },
+  { id: "chat", label: "Chat" },
+];
+const idOf = (pin: Pin) => pin.id;
+
+function memoryStorage(): UserOrderStorage & { data: Map<string, string> } {
+  const data = new Map<string, string>();
+  return {
+    data,
+    getItem: (key) => data.get(key) ?? null,
+    setItem: (key, value) => {
+      data.set(key, value);
+    },
+  };
+}
+
+let refresh: (pins: Pin[]) => void = () => {};
+
+function Dock({ storage }: { storage: UserOrderStorage }) {
+  const [pins, setPins] = useState(source);
+  refresh = setPins;
+  const ordered = useUserOrder("dock", pins, idOf, { storage });
+  return (
+    <SortableList
+      items={ordered.items}
+      getId={idOf}
+      getLabel={(pin) => pin.label}
+      onChange={ordered.onChange}
+    />
+  );
+}
+
+function shown(container: HTMLElement) {
+  return [...container.querySelectorAll("[data-sortable-row]")].map((row) =>
+    row.getAttribute("data-sortable-row"),
+  );
+}
+
+function moveDown(container: HTMLElement, id: string) {
+  const row = container.querySelector(`[data-sortable-row="${id}"]`) as HTMLElement;
+  row.focus();
+  fireEvent.keyDown(row, { key: " " });
+  fireEvent.keyDown(row, { key: "ArrowDown" });
+  fireEvent.keyDown(row, { key: " " });
+}
+
+describe("applyUserOrder (LC-209)", () => {
+  it("keeps saved places and appends new ids at the end", () => {
+    const result = applyUserOrder(
+      [...source, { id: "maps", label: "Maps" }],
+      ["chat", "mail", "files"],
+      idOf,
+    );
+    expect(result.items.map(idOf)).toEqual(["chat", "mail", "files", "maps"]);
+    expect(result.order).toEqual(["chat", "mail", "files", "maps"]);
+  });
+
+  it("an id missing from a partial read keeps its slot", () => {
+    const result = applyUserOrder([source[0]!, source[2]!], ["files", "chat", "mail"], idOf);
+    expect(result.items.map(idOf)).toEqual(["chat", "mail"]);
+    expect(result.order).toEqual(["files", "chat", "mail"]);
+  });
+});
+
+describe("a reorderable dock keeps the user's order (LC-209)", () => {
+  it("a new item lands last and the others keep their index", () => {
+    const storage = memoryStorage();
+    const { container } = renderWithProviders(<Dock storage={storage} />);
+    moveDown(container, "mail");
+    expect(shown(container)).toEqual(["files", "mail", "chat"]);
+
+    act(() => refresh([...source, { id: "maps", label: "Maps" }]));
+    expect(shown(container)).toEqual(["files", "mail", "chat", "maps"]);
+  });
+
+  it("a refresh in the source's order and a reload both keep the arrangement", () => {
+    const storage = memoryStorage();
+    const first = renderWithProviders(<Dock storage={storage} />);
+    moveDown(first.container, "mail");
+    act(() => refresh([...source]));
+    expect(shown(first.container)).toEqual(["files", "mail", "chat"]);
+    first.unmount();
+
+    const reloaded = renderWithProviders(<Dock storage={storage} />);
+    expect(shown(reloaded.container)).toEqual(["files", "mail", "chat"]);
+    expect(JSON.parse(storage.data.get("dock") ?? "[]")).toEqual(["files", "mail", "chat"]);
+  });
+});