@godxjp/ui 31.28.3 → 31.29.0

package/dist/props/components/feedback.prop.d.ts

@@ -1,7 +1,7 @@
 /** Feedback component prop types — @see docs/COMPONENTS.md#feedback */
 import type * as React from "react";
 import type { QueryErrorCategory } from "../../lib/query-error.js";
-import type { AlertVariantProp, AvatarShapeProp, CalloutKindProp, CancelLabelProp, ChildrenProp, ClassNameProp, ConfirmLabelProp, ConfirmVariantProp, DefaultOpenProp, DescriptionProp, HandlerProp, IconProp, OpenProp, OnOpenChangeProp, PendingProp, ShapeProp, SizeProp, ToneProp, TitleProp } from "../vocabulary/index.js";
+import type { AlertVariantProp, AvatarShapeProp, CalloutKindProp, CancelLabelProp, ChildrenProp, ClassNameProp, ConfirmLabelProp, ConfirmVariantProp, DefaultOpenProp, DescriptionProp, HandlerProp, IconProp, OpenProp, OnOpenChangeProp, PendingProp, ShapeProp, SizeProp, ToneProp, TitleProp, WidthProp } from "../vocabulary/index.js";
 /**
  * @see Dialog — the compound modal ROOT.
  *
@@ -38,6 +38,11 @@ export type DialogContentProp = {
     showClose?: boolean;
     /** Semantic class for the scrim the surface owns (RAC nests overlay → modal → dialog). */
     overlayClassName?: ClassNameProp;
+    /**
+     * Panel width (antd Modal `width`; same vocabulary as SheetContent `width`): number = px, string
+     * = any CSS length. Capped at the viewport minus `--dialog-viewport-inset`. Default 32rem.
+     */
+    width?: WidthProp;
     className?: ClassNameProp;
     children?: ChildrenProp;
 };

package/dist/props/components/layout.prop.d.ts

@@ -1430,6 +1430,16 @@ export type AppLauncherProp = {
      */
     side?: "top" | "right" | "bottom" | "left";
     align?: "start" | "center" | "end";
+    /**
+     * Secondary links UNDER the grid — "Request access", "All apps", "Add apps": the row Google
+     * Workspace, Okta and Microsoft My Apps put below their launcher grid (gh#1172). Pass the links
+     * themselves (`<a>` or a router link); the launcher draws the row (a hairline above it, the
+     * small type step, `--app-launcher-footer-*`) outside the scrolling grid, so it stays in view and
+     * comes after the tiles in focus order. Rendered in every state — loading, error and empty
+     * included — because "request access" is most needed when there is nothing to open. Not a tile:
+     * a link dressed as an app reads as an app.
+     */
+    footer?: ReactNode;
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
     className?: ClassNameProp;
@@ -1463,6 +1473,14 @@ export type SidebarProp = {
      * not belong here — see AppShell's `navRail` for where it goes and why.
      */
     brand?: ReactNode | ((collapsed: boolean) => ReactNode);
+    /**
+     * The rail's ONE primary action ("New issue", "+ Create", "New page"), rendered between `brand`
+     * and the scrolling nav and never scrolling with it. Put exactly one primary control here: a
+     * `Button` (variant primary) full width when expanded, icon-only with an `aria-label` + tooltip
+     * when collapsed. It takes a function for the same reason `brand` and `footer` do: it receives the
+     * EFFECTIVE collapsed value, so the mobile drawer (which never collapses) gets the full button.
+     */
+    action?: ReactNode | ((collapsed: boolean) => ReactNode);
     collapsed?: boolean;
     children?: ChildrenProp;
     /**
@@ -1620,6 +1638,10 @@ export type TopbarItemProp = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>,
      *
      * The count is not an accessible name: give the cell an `aria-label` that says what the number
      * means (`aria-label={t("topbar.notifications.unread", { count })}`).
+     *
+     * Drawn under `asChild` too (gh#1171): the pill goes inside the child element, after its own
+     * children, so a bell that is a link (`<TopbarItem asChild badge={3}><a …/></TopbarItem>`) keeps
+     * its count.
      */
     badge?: ReactNode;
     /**

package/dist/props/registry.d.ts

@@ -2017,6 +2017,11 @@ export declare const COMPONENT_PROP_REGISTRY: {
         readonly file: "components/data-display.prop.ts";
         readonly vocabulary: readonly [];
     };
+    readonly AvatarImageFitProp: {
+        readonly group: "data-display";
+        readonly file: "components/data-display.prop.ts";
+        readonly vocabulary: readonly [];
+    };
     readonly BadgeProp: {
         readonly group: "data-display";
         readonly file: "components/data-display.prop.ts";
@@ -2428,7 +2433,7 @@ export declare const COMPONENT_PROP_REGISTRY: {
     readonly DialogContentProp: {
         readonly group: "feedback";
         readonly file: "components/feedback.prop.ts";
-        readonly vocabulary: readonly ["ConfirmVariantProp", "ClassNameProp", "ChildrenProp", {
+        readonly vocabulary: readonly ["ConfirmVariantProp", "ClassNameProp", "ChildrenProp", "WidthProp", {
             readonly field: "showCloseButton";
             readonly local: true;
             readonly reason: 'Corner ✕ opt-out; defaults to false under variant="destructive".';
@@ -3312,13 +3317,39 @@ export declare const COMPONENT_PROP_REGISTRY: {
             readonly reason: "antd `onDrop` info: true when it lands as a sibling, false inside.";
         }];
     };
+    readonly SortableListItemProp: {
+        readonly group: "data-entry";
+        readonly file: "components/data-entry.prop.ts";
+        readonly vocabulary: readonly ["ValueProp", "LabelProp", "DisabledProp"];
+    };
+    readonly SortableListProp: {
+        readonly group: "data-entry";
+        readonly file: "components/data-entry.prop.ts";
+        readonly vocabulary: readonly ["ValueProp", "DefaultValueProp", "OnValueChangeProp", "DisabledProp", "IdProp", "ClassNameProp", {
+            readonly field: "items";
+            readonly local: true;
+            readonly reason: "The rows to order — key + spoken label + per-item disabled; not select options (nothing is chosen, the order is the value).";
+        }, {
+            readonly field: "renderItem";
+            readonly local: true;
+            readonly reason: "Draws an item's content beside the grip, with its index and whether it is held.";
+        }, {
+            readonly field: "layout";
+            readonly local: true;
+            readonly reason: "list (stacked rows) vs grid (auto-filled tiles) — the same keyboard order either way; not OrientationProp, a grid is neither axis.";
+        }, {
+            readonly field: "aria-label";
+            readonly local: true;
+            readonly reason: "Accessible name of the list.";
+        }];
+    };
     readonly EmojiPickerProp: {
         readonly group: "data-entry";
         readonly file: "components/data-entry.prop.ts";
         readonly vocabulary: readonly ["ValueProp", "DefaultValueProp", "OnValueChangeProp", "OpenProp", "DefaultOpenProp", "OnOpenChangeProp", "SizeProp", "DisabledProp", "IdProp", "ClassNameProp", {
             readonly field: "removable";
             readonly local: true;
-            readonly reason: "Whether \"remove icon\" is offered while a value is set — a picker for an OPTIONAL icon (gh#1164), not AllowClearProp's inline ✕ on a field.";
+            readonly reason: 'Whether "remove icon" is offered while a value is set — a picker for an OPTIONAL icon (gh#1164), not AllowClearProp\'s inline ✕ on a field.';
         }, {
             readonly field: "recentsKey";
             readonly local: true;

package/dist/props/registry.js

@@ -2417,6 +2417,11 @@ const COMPONENT_PROP_REGISTRY = {
     file: "components/data-display.prop.ts",
     vocabulary: []
   },
+  AvatarImageFitProp: {
+    group: "data-display",
+    file: "components/data-display.prop.ts",
+    vocabulary: []
+  },
   BadgeProp: {
     group: "data-display",
     file: "components/data-display.prop.ts",
@@ -2850,6 +2855,7 @@ const COMPONENT_PROP_REGISTRY = {
       "ConfirmVariantProp",
       "ClassNameProp",
       "ChildrenProp",
+      "WidthProp",
       {
         field: "showCloseButton",
         local: true,
@@ -3917,6 +3923,39 @@ const COMPONENT_PROP_REGISTRY = {
       }
     ]
   },
+  SortableListItemProp: {
+    group: "data-entry",
+    file: "components/data-entry.prop.ts",
+    vocabulary: ["ValueProp", "LabelProp", "DisabledProp"]
+  },
+  SortableListProp: {
+    group: "data-entry",
+    file: "components/data-entry.prop.ts",
+    vocabulary: [
+      "ValueProp",
+      "DefaultValueProp",
+      "OnValueChangeProp",
+      "DisabledProp",
+      "IdProp",
+      "ClassNameProp",
+      {
+        field: "items",
+        local: true,
+        reason: "The rows to order \u2014 key + spoken label + per-item disabled; not select options (nothing is chosen, the order is the value)."
+      },
+      {
+        field: "renderItem",
+        local: true,
+        reason: "Draws an item's content beside the grip, with its index and whether it is held."
+      },
+      {
+        field: "layout",
+        local: true,
+        reason: "list (stacked rows) vs grid (auto-filled tiles) \u2014 the same keyboard order either way; not OrientationProp, a grid is neither axis."
+      },
+      { field: "aria-label", local: true, reason: "Accessible name of the list." }
+    ]
+  },
   EmojiPickerProp: {
     group: "data-entry",
     file: "components/data-entry.prop.ts",
@@ -3946,7 +3985,11 @@ const COMPONENT_PROP_REGISTRY = {
         local: true,
         reason: "Replaces the default trigger button (a page icon drawn large, a reaction chip) \u2014 a ReactNode slot, not a TriggerProp mode."
       },
-      { field: "aria-label", local: true, reason: "Accessible name of the trigger and the popover." }
+      {
+        field: "aria-label",
+        local: true,
+        reason: "Accessible name of the trigger and the popover."
+      }
     ]
   },
   TreeProp: {

package/dist/styles/control.css

@@ -1026,6 +1026,56 @@
     background-color: hsl(var(--accent));
   }
 
+  .ui-sortable-list-items {
+    display: flex;
+    flex-direction: column;
+    gap: var(--sortable-list-gap);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .ui-sortable-list[data-layout="grid"] .ui-sortable-list-items {
+    display: grid;
+    grid-template-columns: repeat(
+      auto-fill,
+      minmax(min(100%, var(--sortable-list-grid-item-min-inline-size)), 1fr)
+    );
+  }
+
+  .ui-sortable-list-item {
+    display: flex;
+    min-inline-size: 0;
+    align-items: center;
+    gap: var(--sortable-list-gap);
+    border: var(--stroke-hairline) solid hsl(var(--border));
+    border-radius: var(--sortable-list-item-radius);
+    background: hsl(var(--card));
+    padding: var(--sortable-list-item-padding);
+  }
+
+  .ui-sortable-list-item[data-dragging] {
+    position: relative;
+    z-index: 1;
+    border-color: hsl(var(--ring));
+    box-shadow: var(--shadow-md);
+  }
+
+  .ui-sortable-list-content {
+    min-inline-size: 0;
+    flex: 1 1 0%;
+  }
+
+  .ui-sortable-list-handle {
+    flex-shrink: 0;
+    cursor: grab;
+    touch-action: none;
+  }
+
+  .ui-sortable-list-item[data-dragging] .ui-sortable-list-handle {
+    cursor: grabbing;
+  }
+
   .ui-emoji-picker-grid {
     display: flex;
     flex-direction: column;

package/dist/styles/data-display-layout.css

@@ -72,6 +72,10 @@
     object-fit: cover;
   }
 
+  .ui-avatar-image[data-fit="contain"] {
+    object-fit: contain;
+  }
+
   .ui-avatar-fallback {
     display: flex;
     width: 100%;

package/dist/styles/dialog-layout.css

@@ -47,7 +47,12 @@
     top: 50%;
     z-index: var(--overlay-z-index);
     display: grid;
-    width: min(var(--dialog-width-default), calc(100% - var(--dialog-viewport-inset)));
+    width: min(
+      var(--dialog-width, var(--dialog-width-default)),
+      calc(100% - var(--dialog-viewport-inset))
+    );
+
+    --tw-animation-duration: var(--dialog-motion-duration, var(--duration-fast));
     max-width: none;
     transform: translate(-50%, -50%);
     gap: var(--dialog-space-gap);
@@ -424,6 +429,14 @@
     inset: 0;
   }
 
+  .ui-sheet-panel[data-state="open"] {
+    --tw-animation-duration: var(--sheet-enter-duration, var(--duration-fast));
+  }
+
+  .ui-sheet-panel[data-state="closed"] {
+    --tw-animation-duration: var(--sheet-exit-duration, var(--duration-fast));
+  }
+
   .ui-sheet-panel {
 
     background-color: var(--sheet-surface-background, hsl(var(--background)));

package/dist/styles/layers.json

@@ -1,5 +1,5 @@
 {
-  "version": "31.28.3",
+  "version": "31.29.0",
   "generatedBy": "scripts/gen-style-layers.mjs — do not edit by hand; run `pnpm gen:style-layers`",
   "base": "base.css",
   "fonts": "fonts.css",
@@ -1035,6 +1035,11 @@
         "control.css"
       ]
     },
+    "SortableList": {
+      "layers": [
+        "control.css"
+      ]
+    },
     "SpaceCompact": {
       "layers": [
         "layout.css"

package/dist/styles/layout.css

@@ -138,7 +138,10 @@
     min-inline-size: 0;
   }
 
-  .ui-space-compact[data-orientation="horizontal"][data-full-width="true"] > [data-slot="space-compact-item"]:not(:has(.ui-control, .ui-control-multiline, .ui-tag-input)) {
+  .ui-space-compact[data-orientation="horizontal"][data-full-width="true"]
+    > [data-slot="space-compact-item"]:not(
+      :has(.ui-control, .ui-control-multiline, .ui-tag-input)
+    ) {
     flex: none;
   }
 
@@ -146,16 +149,21 @@
     flex-direction: column;
   }
 
-  .ui-space-compact[data-orientation="vertical"][data-full-width="true"] > [data-slot="space-compact-item"] {
+  .ui-space-compact[data-orientation="vertical"][data-full-width="true"]
+    > [data-slot="space-compact-item"] {
     min-inline-size: auto;
     min-block-size: 0;
   }
 
-  .ui-space-compact[data-orientation="horizontal"] > [data-slot="space-compact-item"] + [data-slot="space-compact-item"] {
+  .ui-space-compact[data-orientation="horizontal"]
+    > [data-slot="space-compact-item"]
+    + [data-slot="space-compact-item"] {
     margin-inline-start: calc(var(--control-border-width, var(--stroke-hairline)) * -1);
   }
 
-  .ui-space-compact[data-orientation="vertical"] > [data-slot="space-compact-item"] + [data-slot="space-compact-item"] {
+  .ui-space-compact[data-orientation="vertical"]
+    > [data-slot="space-compact-item"]
+    + [data-slot="space-compact-item"] {
     margin-block-start: calc(var(--control-border-width, var(--stroke-hairline)) * -1);
   }
 
@@ -175,12 +183,14 @@
     z-index: 1;
   }
 
-  .ui-space-compact[data-orientation="horizontal"] > [data-slot="space-compact-item"]:not(:first-child) {
+  .ui-space-compact[data-orientation="horizontal"]
+    > [data-slot="space-compact-item"]:not(:first-child) {
     --input-radius-start: 0;
     --control-trigger-radius-start: 0;
   }
 
-  .ui-space-compact[data-orientation="horizontal"] > [data-slot="space-compact-item"]:not(:last-child) {
+  .ui-space-compact[data-orientation="horizontal"]
+    > [data-slot="space-compact-item"]:not(:last-child) {
     --input-radius-end: 0;
     --control-trigger-radius-end: 0;
   }
@@ -410,6 +420,10 @@
     align-items: start;
   }
 
+  .ui-responsive-grid[data-dense] {
+    grid-auto-flow: row dense;
+  }
+
   .ui-responsive-grid[data-align="start"] {
     align-items: start;
   }
@@ -926,7 +940,10 @@
 
   .ui-page-container[data-header-scale="display"] .ui-page-title,
   .ui-page-container[data-header-scale="display"] .ui-page-header .ui-page-title {
-    font-size: var(--page-title-font-size-display);
+    font-size: var(
+      --page-title-font-size-display,
+      var(--font-size-4xl, calc(var(--font-size-display) / var(--font-size-display-ratio)))
+    );
     font-weight: var(--font-weight-semibold);
     line-height: var(--page-title-line-height-display);
     text-wrap: balance;
@@ -1966,22 +1983,27 @@
   .ui-master-detail[data-rail-width="wide"] {
     --master-detail-rail-size: var(--master-detail-rail-wide);
   }
+
   .ui-responsive-grid-item {
     grid-column: span min(var(--responsive-grid-base, 1), var(--responsive-grid-item-base, 1));
+    grid-row: span var(--responsive-grid-item-row-base, 1);
   }
   @container responsive-grid (min-width: 40rem) {
     .ui-responsive-grid-item {
       grid-column: span min(var(--responsive-grid-sm, 1), var(--responsive-grid-item-sm, 1));
+      grid-row: span var(--responsive-grid-item-row-sm, 1);
     }
   }
   @container responsive-grid (min-width: 48rem) {
     .ui-responsive-grid-item {
       grid-column: span min(var(--responsive-grid-md, 1), var(--responsive-grid-item-md, 1));
+      grid-row: span var(--responsive-grid-item-row-md, 1);
     }
   }
   @container responsive-grid (min-width: 64rem) {
     .ui-responsive-grid-item {
       grid-column: span min(var(--responsive-grid-lg, 1), var(--responsive-grid-item-lg, 1));
+      grid-row: span var(--responsive-grid-item-row-lg, 1);
     }
   }
   .ui-separator[data-label-size="2xs"] .ui-separator-label {

package/dist/styles/shell-layout.css

@@ -1504,6 +1504,21 @@
     font-weight: var(--font-weight-medium);
   }
 
+  .ui-app-launcher-footer {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--app-launcher-footer-gap);
+    margin-block-start: var(--app-launcher-footer-space-block);
+    padding-block-start: var(--app-launcher-footer-space-block);
+    border-block-start: var(--stroke-hairline) solid hsl(var(--border));
+    font-size: var(--app-launcher-footer-font-size);
+  }
+
+  .ui-app-launcher-launchpad .ui-app-launcher-footer {
+    justify-content: center;
+  }
+
   .ui-app-launcher-state {
     display: flex;
     min-height: var(--app-launcher-state-min-height);
@@ -1606,6 +1621,17 @@
     height: var(--sidebar-product-caret-icon-size);
   }
 
+  .sb-action {
+    display: flex;
+    flex-shrink: 0;
+    flex-direction: column;
+    padding: var(--sidebar-action-padding);
+  }
+
+  .sb-root[data-collapsed="true"] .sb-action {
+    align-items: center;
+  }
+
   .sb-nav-scroll {
     flex: 1;
     min-height: 0;

package/dist/tokens/components/control.css

@@ -470,6 +470,11 @@
   );
   --emoji-picker-glyph-size: var(--icon-size-lg);
   --emoji-picker-grid-max-block-size: 16rem;
+
+  --sortable-list-gap: var(--space-2);
+  --sortable-list-item-padding: var(--space-2);
+  --sortable-list-item-radius: var(--control-radius);
+  --sortable-list-grid-item-min-inline-size: 12rem;
 }
 
 @media (pointer: coarse) {

package/dist/tokens/components/feedback.css

@@ -29,6 +29,12 @@
   --sheet-close-rest-alpha: 0.7;
   --sheet-header-close-space-inline-end: var(--space-8);
   --dialog-width-default: 32rem;
+
+  --dialog-width: initial;
+
+  --dialog-motion-duration: initial;
+  --sheet-enter-duration: initial;
+  --sheet-exit-duration: initial;
   --dialog-viewport-inset: 1.5rem;
   --dialog-overlay-background: initial;
 

package/dist/tokens/components/shell.css

@@ -139,6 +139,8 @@
 
   --sidebar-nav-item-radius: initial;
   --sidebar-nav-scroll-padding: var(--space-3) var(--space-2);
+
+  --sidebar-action-padding: var(--space-3) var(--space-2) 0;
   --sidebar-section-gap: var(--space-4);
   --sidebar-section-label-padding-x: var(--space-2);
   --sidebar-section-label-padding-bottom: var(--space-1);
@@ -240,6 +242,10 @@
   --app-launcher-group-label-color: initial;
   --app-launcher-state-min-height: 8rem;
 
+  --app-launcher-footer-space-block: var(--space-2);
+  --app-launcher-footer-gap: var(--space-3);
+  --app-launcher-footer-font-size: var(--font-size-sm, var(--font-size-base));
+
   --app-launcher-launchpad-backdrop-background: initial;
   --app-launcher-launchpad-backdrop-blur-size: var(--blur-lg);
   --app-launcher-launchpad-backdrop-alpha: 55%;

package/dist/tokens/semantic/layout.css

@@ -91,10 +91,7 @@
 
   --page-title-font-size-chrome: var(--heading-h3, var(--font-size-base));
 
-  --page-title-font-size-display: var(
-    --font-size-4xl,
-    calc(var(--font-size-display) / var(--font-size-display-ratio))
-  );
+  --page-title-font-size-display: initial;
   --page-title-line-height-display: 1.4;
 
   --page-icon-size: var(--icon-size-4xl);

package/docs/FRAME-COVERAGE-REPORT.md

@@ -3,8 +3,8 @@
 > Generated by `scripts/frame-coverage.mjs` (issue #163). Do not edit by hand — run `pnpm check:frame-coverage`.
 > Standard: [FRAME-COVERAGE-STANDARD.md](./FRAME-COVERAGE-STANDARD.md). A missing dimension is **UNTESTED**, never a pass.
 
-- Public components: **184**
-- With ≥1 frame: **160** · zero-frame: **24**
+- Public components: **185**
+- With ≥1 frame: **161** · zero-frame: **24**
 - Fully covered (every contract axis declared): **0**
 
 ## UNTESTED — no `/frame/**` route
@@ -195,6 +195,7 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | PieChart | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
 | CommandPalette | ✓ | N/A | · | · | · | · | · | · | · | · |
 | EmojiPicker | ✓ | · | · | · | · | · | · | · | · | · |
+| SortableList | ✓ | N/A | · | · | · | · | · | · | · | · |
 | TwoFactorSetup | ✓ | N/A | · | · | · | · | · | · | · | · |
 | AuthDivider | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | AuthFooter | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |

package/docs/data-display/avatar.tsx

@@ -11,9 +11,11 @@ import {
 } from "@godxjp/ui/data-display";
 import { Button, Text } from "@godxjp/ui/general";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
+import { useTranslation } from "@godxjp/ui/i18n";
 import { Building2, KeyRound, ShieldCheck, Sparkles } from "lucide-react";
 
 import portraitAmber from "../assets/portrait-amber.svg";
+import shotLandscape from "../assets/shot-landscape.svg";
 import portraitClay from "../assets/portrait-clay.svg";
 import portraitIndigo from "../assets/portrait-indigo.svg";
 import portraitIris from "../assets/portrait-iris.svg";
@@ -39,9 +41,39 @@ import portraitSlate from "../assets/portrait-slate.svg";
  * Composed only from real @godxjp/ui components.
  */
 export default function Demo() {
+  const { t } = useTranslation();
   return (
     <PageContainer title="Avatar" subtitle="Identity image with a readable fallback">
       <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>{t("avatarDocs.fitTitle")}</CardTitle>
+            <CardDescription>{t("avatarDocs.fitDescription")}</CardDescription>
+          </CardHeader>
+          <CardContent>
+            {/* gh#1176: a wide logo — cover crops it, contain shows it whole. */}
+            <Flex direction="row" wrap align="center" gap="md">
+              <Flex direction="col" align="center" gap="xs">
+                <Avatar shape="square" size="lg">
+                  <AvatarImage src={shotLandscape} alt={t("avatarDocs.logo")} />
+                  <AvatarFallback>AC</AvatarFallback>
+                </Avatar>
+                <Text size="sm" tone="muted">
+                  cover
+                </Text>
+              </Flex>
+              <Flex direction="col" align="center" gap="xs">
+                <Avatar shape="square" size="lg">
+                  <AvatarImage src={shotLandscape} alt={t("avatarDocs.logo")} fit="contain" />
+                  <AvatarFallback>AC</AvatarFallback>
+                </Avatar>
+                <Text size="sm" tone="muted">
+                  contain
+                </Text>
+              </Flex>
+            </Flex>
+          </CardContent>
+        </Card>
         <Card>
           <CardHeader>
             <CardTitle level={2}>Image + fallback</CardTitle>

package/docs/data-entry/sortable-list.tsx

@@ -0,0 +1,76 @@
+import * as React from "react";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { SortableList } from "@godxjp/ui/data-entry";
+import { Text } from "@godxjp/ui/general";
+import { useTranslation } from "@godxjp/ui/i18n";
+import { Flex, PageContainer } from "@godxjp/ui/layout";
+
+/**
+ * SortableList (gh#1173) — a desktop editor's widget order (tiles) and a settings list of tabs,
+ * reordered by dragging a grip or by the keyboard, every step announced.
+ */
+export default function Demo() {
+  const { t, locale } = useTranslation();
+  const list = new Intl.ListFormat(locale, { style: "narrow", type: "unit" });
+  const ordinal = new Intl.NumberFormat(locale);
+  const widgets = [
+    { value: "calendar", label: t("sortableListDocs.calendar") },
+    { value: "mail", label: t("sortableListDocs.mail") },
+    { value: "tasks", label: t("sortableListDocs.tasks") },
+    { value: "notes", label: t("sortableListDocs.notes") },
+  ];
+  const tabs = [
+    { value: "overview", label: t("sortableListDocs.overview") },
+    { value: "members", label: t("sortableListDocs.members") },
+    { value: "billing", label: t("sortableListDocs.billing"), disabled: true },
+    { value: "audit", label: t("sortableListDocs.audit") },
+  ];
+  const [order, setOrder] = React.useState(widgets.map((w) => w.value));
+  return (
+    <PageContainer title="SortableList" subtitle={t("sortableListDocs.subtitle")}>
+      <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>{t("sortableListDocs.widgetsTitle")}</CardTitle>
+            <CardDescription>{t("sortableListDocs.widgetsDescription")}</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="sm">
+              <SortableList
+                aria-label={t("sortableListDocs.widgetsTitle")}
+                layout="grid"
+                items={widgets}
+                value={order}
+                onValueChange={setOrder}
+                renderItem={(item, { index }) => (
+                  <Flex direction="col" gap="xs">
+                    <Text weight="medium">{item.label}</Text>
+                    <Text size="sm" tone="muted">
+                      {t("sortableListDocs.slot", { position: ordinal.format(index + 1) })}
+                    </Text>
+                  </Flex>
+                )}
+              />
+              <Text size="sm" tone="muted">
+                {t("sortableListDocs.saved", {
+                  order: list.format(
+                    order.map((key) => widgets.find((w) => w.value === key)?.label ?? key),
+                  ),
+                })}
+              </Text>
+            </Flex>
+          </CardContent>
+        </Card>
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>{t("sortableListDocs.tabsTitle")}</CardTitle>
+            <CardDescription>{t("sortableListDocs.tabsDescription")}</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <SortableList aria-label={t("sortableListDocs.tabsTitle")} items={tabs} />
+          </CardContent>
+        </Card>
+      </Flex>
+    </PageContainer>
+  );
+}