@tensor_1/react 2.43.0 → 2.44.0

package/dist/components/DashboardCanvas.d.ts

@@ -0,0 +1,78 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+import { DashboardCanvasItem } from '../dashboard-canvas-model.js';
+
+/** Every word the canvas renders. `{label}` is the item's name; the others are grid units. */
+interface DashboardCanvasLabels {
+    /** The region's accessible name. */
+    region: string;
+    /** The move handle's name. */
+    move: string;
+    /** The resize handle's name. */
+    resize: string;
+    /** How the handles work, read with each handle (`aria-describedby`). */
+    instructions: string;
+    /** Announced after a move. `{col}` and `{row}` count from 1. */
+    moved: string;
+    /** Announced after a resize. */
+    resized: string;
+    /** Announced when a step would leave the canvas or pass the item's size limit. */
+    atEdge: string;
+    /** Announced when Escape drops a drag. */
+    cancelled: string;
+}
+declare const DEFAULT_DASHBOARD_CANVAS_LABELS: DashboardCanvasLabels;
+/** Space between items: `sm` --uix-space-3, `md` --uix-space-4, `lg` --uix-space-6. */
+type DashboardCanvasGap = 'sm' | 'md' | 'lg';
+/** What changed, for the product's save and its journey event. */
+interface DashboardCanvasChange {
+    readonly id: string;
+    readonly kind: 'move' | 'resize';
+    readonly source: 'pointer' | 'keyboard';
+}
+interface DashboardCanvasProps<T extends DashboardCanvasItem> extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'children'> {
+    /** The layout. Overlaps and out-of-range values are settled before rendering. */
+    items: readonly T[];
+    /** One cell's content: a widget, a card. Its last child takes the spare height. */
+    renderItem: (item: T) => ReactNode;
+    /** The item's name in labels and announcements. Default: its id. */
+    itemLabel?: (item: T) => string;
+    /**
+     * Edit mode: each item gets a move handle and a resize handle, both draggable and both
+     * operable with the arrow keys. Off, the canvas is a plain layout and server-renderable.
+     */
+    editable?: boolean;
+    /** The next layout, once per drop or key press. The canvas never keeps its own copy. */
+    onLayoutChange?: (items: T[], change: DashboardCanvasChange) => void;
+    /** Height of one row, any CSS length. Default `--uix-dashboard-canvas-row` (5rem). */
+    rowHeight?: string;
+    /** Default `md`. */
+    gap?: DashboardCanvasGap;
+    labels?: Partial<DashboardCanvasLabels>;
+}
+/**
+ * A free dashboard layout (TENSOR HAR-1823): twelve columns, rows of one fixed height, and each
+ * item at its own `{ col, row, w, h }` in grid units. In edit mode a person drags an item by its
+ * move handle and resizes it by the corner handle; both snap to the grid, push what they land
+ * on downwards, and report one new layout per drop. Both handles also take the arrow keys, and
+ * the pure functions behind them (`moveCanvasItem`, `resizeCanvasItem`) are exported for the
+ * product's own item menu, so dragging is never the only way (WCAG 2.5.7).
+ *
+ * Below 36rem of its own width the canvas is one column in reading order (row by row, left to
+ * right), each item keeping its height, and the handles step aside: the item menu remains.
+ *
+ * Owns interaction, never persistence: the product stores `items` and passes them back.
+ *
+ * ```tsx
+ * <DashboardCanvas
+ *   items={layout}
+ *   editable={editing}
+ *   itemLabel={(item) => titles[item.id]}
+ *   renderItem={(item) => <Widget id={item.id} />}
+ *   onLayoutChange={(next) => save(next)}
+ * />
+ * ```
+ */
+declare function DashboardCanvas<T extends DashboardCanvasItem>({ items, renderItem, itemLabel, editable, onLayoutChange, rowHeight, gap, labels: labelOverrides, className, style, ...props }: DashboardCanvasProps<T>): react.JSX.Element;
+
+export { DEFAULT_DASHBOARD_CANVAS_LABELS, DashboardCanvas, type DashboardCanvasChange, type DashboardCanvasGap, type DashboardCanvasLabels, type DashboardCanvasProps };

package/dist/components/DashboardCanvas.js

@@ -0,0 +1,227 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useMemo, useRef, useState } from "react";
+import { cx } from "../cx.js";
+import { fillLabel } from "../fill-label.js";
+import { GripVerticalIcon, Maximize2Icon } from "../icons/components.js";
+import {
+  canvasMoveTarget,
+  canvasReadingOrder,
+  canvasResizeTarget,
+  DASHBOARD_CANVAS_COLUMNS,
+  normalizeCanvas,
+  placeCanvasItem
+} from "../dashboard-canvas-model.js";
+const DEFAULT_DASHBOARD_CANVAS_LABELS = {
+  region: "Dashboard layout",
+  move: "Move {label}",
+  resize: "Resize {label}",
+  instructions: "Arrow keys move or resize one step. Escape cancels a drag.",
+  moved: "{label}: column {col}, row {row}",
+  resized: "{label}: {w} columns wide, {h} rows tall",
+  atEdge: "{label} cannot go further that way",
+  cancelled: "Move cancelled"
+};
+const DRAG_THRESHOLD = 4;
+function measure(grid) {
+  const style = getComputedStyle(grid);
+  const width = grid.clientWidth - (Number.parseFloat(style.paddingLeft) || 0) - (Number.parseFloat(style.paddingRight) || 0);
+  const tracks = style.gridTemplateColumns.split(" ").map((track) => Number.parseFloat(track)).filter(Number.isFinite);
+  const trackSum = tracks.reduce((sum, track) => sum + track, 0);
+  const columnGap = tracks.length > 1 ? Math.max(0, (width - trackSum) / (tracks.length - 1)) : 0;
+  const colPitch = (width + columnGap) / DASHBOARD_CANVAS_COLUMNS;
+  const rowGap = Number.parseFloat(style.rowGap) || 0;
+  const rowTrack = Number.parseFloat(style.gridAutoRows) || 80;
+  return { colPitch, rowPitch: rowTrack + rowGap };
+}
+function DashboardCanvas({
+  items,
+  renderItem,
+  itemLabel = (item) => item.id,
+  editable = false,
+  onLayoutChange,
+  rowHeight,
+  gap = "md",
+  labels: labelOverrides,
+  className,
+  style,
+  ...props
+}) {
+  const labels = { ...DEFAULT_DASHBOARD_CANVAS_LABELS, ...labelOverrides };
+  const instructionsId = useId();
+  const gridRef = useRef(null);
+  const dragRef = useRef(null);
+  const [preview, setPreview] = useState(null);
+  const [announcement, setAnnouncement] = useState("");
+  const layout = useMemo(() => normalizeCanvas(items), [items]);
+  const order = useMemo(() => new Map(canvasReadingOrder(layout).map((item, index) => [item.id, index])), [layout]);
+  const live = useRef({ layout, onLayoutChange, labels, itemLabel });
+  live.current = { layout, onLayoutChange, labels, itemLabel };
+  useEffect(() => () => dragRef.current?.stop(), []);
+  const describe = (item, kind) => kind === "move" ? fillLabel(labels.moved, { label: itemLabel(item), col: item.col + 1, row: item.row + 1 }) : fillLabel(labels.resized, { label: itemLabel(item), w: item.w, h: item.h });
+  const commit = (id, placement, kind, source) => {
+    const state = live.current;
+    const next = placeCanvasItem(state.layout, id, placement);
+    const placed = next.find((item) => item.id === id);
+    if (!placed) return;
+    state.onLayoutChange?.(next, { id, kind, source });
+    setAnnouncement(describe(placed, kind));
+  };
+  const onHandleKeyDown = (event, item, kind) => {
+    const keys = { ArrowUp: "up", ArrowDown: "down", ArrowLeft: "left", ArrowRight: "right" };
+    const resizes = { ArrowRight: "wider", ArrowLeft: "narrower", ArrowDown: "taller", ArrowUp: "shorter" };
+    if (event.key === "Escape" && dragRef.current) {
+      event.preventDefault();
+      dragRef.current.stop();
+      dragRef.current = null;
+      setPreview(null);
+      setAnnouncement(labels.cancelled);
+      return;
+    }
+    if (!(event.key in keys)) return;
+    event.preventDefault();
+    const target = kind === "move" ? canvasMoveTarget(item, keys[event.key]) : canvasResizeTarget(item, resizes[event.key]);
+    if (!target) {
+      setAnnouncement(fillLabel(labels.atEdge, { label: itemLabel(item) }));
+      return;
+    }
+    commit(item.id, target, kind, "keyboard");
+  };
+  const onHandlePointerDown = (event, item, kind) => {
+    if (event.button !== 0 || dragRef.current || !gridRef.current) return;
+    const { colPitch, rowPitch } = measure(gridRef.current);
+    const origin = { col: item.col, row: item.row, w: item.w, h: item.h };
+    let moved = false;
+    let last = origin;
+    const targetFor = (move) => {
+      const dc = Math.round((move.clientX - drag.startX) / colPitch);
+      const dr = Math.round((move.clientY - drag.startY) / rowPitch);
+      return kind === "move" ? { ...origin, col: origin.col + dc, row: origin.row + dr } : { ...origin, w: origin.w + dc, h: origin.h + dr };
+    };
+    const onMove = (move) => {
+      if (move.pointerId !== drag.pointerId) return;
+      if (!moved && Math.hypot(move.clientX - drag.startX, move.clientY - drag.startY) < DRAG_THRESHOLD) return;
+      moved = true;
+      const placed = placeCanvasItem(live.current.layout, item.id, targetFor(move)).find((candidate) => candidate.id === item.id);
+      if (!placed) return;
+      last = { col: placed.col, row: placed.row, w: placed.w, h: placed.h };
+      setPreview({ id: item.id, placement: last });
+    };
+    const finish = (drop) => {
+      drag.stop();
+      dragRef.current = null;
+      setPreview(null);
+      const changed = last.col !== origin.col || last.row !== origin.row || last.w !== origin.w || last.h !== origin.h;
+      if (drop && moved && changed) commit(item.id, last, kind, "pointer");
+    };
+    const onUp = (up) => {
+      if (up.pointerId === drag.pointerId) finish(true);
+    };
+    const onCancel = (cancel) => {
+      if (cancel.pointerId === drag.pointerId) finish(false);
+    };
+    window.addEventListener("pointermove", onMove);
+    window.addEventListener("pointerup", onUp);
+    window.addEventListener("pointercancel", onCancel);
+    const drag = {
+      id: item.id,
+      kind,
+      pointerId: event.pointerId,
+      startX: event.clientX,
+      startY: event.clientY,
+      origin,
+      colPitch,
+      rowPitch,
+      stop: () => {
+        window.removeEventListener("pointermove", onMove);
+        window.removeEventListener("pointerup", onUp);
+        window.removeEventListener("pointercancel", onCancel);
+      }
+    };
+    dragRef.current = drag;
+  };
+  const placementStyle = (placement, readingIndex) => ({
+    "--uix-dashboard-canvas-col": placement.col + 1,
+    "--uix-dashboard-canvas-row-start": placement.row + 1,
+    "--uix-dashboard-canvas-w": placement.w,
+    "--uix-dashboard-canvas-h": placement.h,
+    "--uix-dashboard-canvas-order": readingIndex
+  });
+  const rootStyle = rowHeight ? { ...style, "--uix-dashboard-canvas-row": rowHeight } : style;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ...props,
+      ref: gridRef,
+      role: "region",
+      "aria-label": labels.region,
+      className: cx(
+        "uix-dashboard-canvas",
+        gap === "sm" && "uix-dashboard-canvas--gap-sm",
+        gap === "lg" && "uix-dashboard-canvas--gap-lg",
+        editable && "uix-dashboard-canvas--editing",
+        preview && "uix-dashboard-canvas--dragging",
+        className
+      ),
+      style: rootStyle,
+      children: [
+        layout.map((item) => {
+          const name = itemLabel(item);
+          const dragging = preview?.id === item.id;
+          return /* @__PURE__ */ jsxs(
+            "div",
+            {
+              className: cx("uix-dashboard-canvas__item", dragging && "uix-dashboard-canvas__item--dragging"),
+              style: placementStyle(item, order.get(item.id) ?? 0),
+              "data-canvas-id": item.id,
+              children: [
+                renderItem(item),
+                editable ? /* @__PURE__ */ jsxs(Fragment, { children: [
+                  /* @__PURE__ */ jsx(
+                    "button",
+                    {
+                      type: "button",
+                      className: "uix-dashboard-canvas__handle uix-dashboard-canvas__move",
+                      "aria-label": fillLabel(labels.move, { label: name }),
+                      "aria-describedby": instructionsId,
+                      onKeyDown: (event) => onHandleKeyDown(event, item, "move"),
+                      onPointerDown: (event) => onHandlePointerDown(event, item, "move"),
+                      children: /* @__PURE__ */ jsx(GripVerticalIcon, { "aria-hidden": "true" })
+                    }
+                  ),
+                  /* @__PURE__ */ jsx(
+                    "button",
+                    {
+                      type: "button",
+                      className: "uix-dashboard-canvas__handle uix-dashboard-canvas__resize",
+                      "aria-label": fillLabel(labels.resize, { label: name }),
+                      "aria-describedby": instructionsId,
+                      onKeyDown: (event) => onHandleKeyDown(event, item, "resize"),
+                      onPointerDown: (event) => onHandlePointerDown(event, item, "resize"),
+                      children: /* @__PURE__ */ jsx(Maximize2Icon, { "aria-hidden": "true" })
+                    }
+                  )
+                ] }) : null
+              ]
+            },
+            item.id
+          );
+        }),
+        preview ? /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: "uix-dashboard-canvas__preview",
+            style: placementStyle(preview.placement, order.get(preview.id) ?? 0),
+            "aria-hidden": "true"
+          }
+        ) : null,
+        editable ? /* @__PURE__ */ jsx("span", { id: instructionsId, className: "uix-visually-hidden", children: labels.instructions }) : null,
+        /* @__PURE__ */ jsx("span", { className: "uix-visually-hidden", role: "status", "aria-live": "polite", children: announcement })
+      ]
+    }
+  );
+}
+export {
+  DEFAULT_DASHBOARD_CANVAS_LABELS,
+  DashboardCanvas
+};

package/dist/components/DiscardPrompt.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { RefObject, KeyboardEvent, ReactNode } from 'react';
+import { SyntheticEvent, RefObject, KeyboardEvent, ReactNode } from 'react';
 import { ButtonProps } from './Button.js';
 import '../link.js';
 import './Kbd.js';
@@ -15,6 +15,12 @@ interface DiscardPromptLabels {
     /** Close and throw the input away. */
     discard: string;
 }
+/**
+ * What asked a `Drawer` or `Modal` to close, handed to its `onClose`: the click on the close
+ * button, a `DialogClose`, the drawer's backdrop or "Discard". Absent when the browser closed the
+ * dialog itself (Escape on a clean dialog, a `<form method="dialog">`), as before 2.42.
+ */
+type DialogCloseEvent = SyntheticEvent | Event;
 type DialogCloseProps = ButtonProps;
 /**
  * A button that closes the surrounding `Drawer` or `Modal` the way its × does (HAR-2029): at once
@@ -25,7 +31,7 @@ type DialogCloseProps = ButtonProps;
 declare const DialogClose: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
 interface GuardedDialogOptions {
     open: boolean;
-    onClose?: () => void;
+    onClose?: (event?: DialogCloseEvent) => void;
     dirty?: boolean;
     pending?: boolean;
     labels?: Partial<DiscardPromptLabels>;
@@ -45,10 +51,10 @@ interface GuardedDialogOptions {
  */
 declare function useGuardedDialog({ open, onClose, dirty, pending, labels: labelsProp, closeRef }: GuardedDialogOptions): {
     ref: RefObject<HTMLDialogElement>;
-    requestClose: (anchor?: HTMLElement | null) => void;
+    requestClose: (anchor?: HTMLElement | null, event?: DialogCloseEvent) => void;
     onKeyDown: (event: KeyboardEvent<HTMLDialogElement>) => void;
     prompt: react.JSX.Element | null;
     provide: (children: ReactNode) => react.JSX.Element;
 };
 
-export { DialogClose, type DialogCloseProps, type DiscardPromptLabels, type GuardedDialogOptions, useGuardedDialog };
+export { DialogClose, type DialogCloseEvent, type DialogCloseProps, type DiscardPromptLabels, type GuardedDialogOptions, useGuardedDialog };

package/dist/components/DiscardPrompt.js

@@ -37,7 +37,7 @@ const DialogClose = forwardRef(({ onClick, type = "button", ...props }, ref) =>
         }
         onClick?.(event);
         if (event.defaultPrevented) return;
-        dialog?.requestClose(event.currentTarget);
+        dialog?.requestClose(event.currentTarget, event);
       }
     }
   );
@@ -57,11 +57,11 @@ function useGuardedDialog({ open, onClose, dirty = false, pending = false, label
     setPromptState(next);
   }, []);
   const guarded = () => !!latest.current.onClose && (latest.current.dirty || latest.current.pending);
-  const requestClose = useCallback((anchor) => {
+  const requestClose = useCallback((anchor, event) => {
     const { open: isOpen, onClose: close, dirty: isDirty, pending: isPending, prompt: asking } = latest.current;
     if (!isOpen || !close || isPending || asking) return;
     if (!isDirty) {
-      close();
+      close(event);
       return;
     }
     const active = document.activeElement;
@@ -89,9 +89,9 @@ function useGuardedDialog({ open, onClose, dirty = false, pending = false, label
     return true;
   });
   dialogRef.current = ref.current;
-  const discard = useCallback(() => {
+  const discard = useCallback((event) => {
     setPrompt(null);
-    latest.current.onClose?.();
+    latest.current.onClose?.(event);
   }, [setPrompt]);
   useEffect(() => {
     if (open && dirty && !pending) return;

package/dist/components/Drawer.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { HTMLAttributes, ReactNode } from 'react';
-import { DiscardPromptLabels } from './DiscardPrompt.js';
+import { DialogCloseEvent, DiscardPromptLabels } from './DiscardPrompt.js';
 import './Button.js';
 import '../link.js';
 import './Kbd.js';
@@ -9,7 +9,11 @@ interface DrawerProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
     /** TENSOR RX-125 (UIX-04): translatable; English default. */
     closeLabel?: string;
     open: boolean;
-    onClose?: () => void;
+    /**
+     * Close the drawer. Gets the click that asked (the close button, the backdrop, a `DialogClose`,
+     * "Discard"); nothing when the browser closed it (Escape, `<form method="dialog">`).
+     */
+    onClose?: (event?: DialogCloseEvent) => void;
     /**
      * The drawer holds input that is not saved (HAR-2029), e.g. react-hook-form's
      * `formState.isDirty`. Escape, the close button, a backdrop click and a `DialogClose` then open

package/dist/components/Drawer.js

@@ -3,7 +3,7 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useId, useRef } from "react";
 import { cx } from "../cx.js";
 import { useUixLabels } from "../labels-context.js";
-import { backdropDismiss } from "../hooks/backdropDismiss.js";
+import { isBackdropClick } from "../hooks/backdropDismiss.js";
 import { useGuardedDialog } from "./DiscardPrompt.js";
 const CloseIcon = () => /* @__PURE__ */ jsx("svg", { width: "16", height: "16", viewBox: "0 0 16 16", fill: "none", stroke: "currentColor", strokeWidth: 1.5, strokeLinecap: "round", "aria-hidden": "true", children: /* @__PURE__ */ jsx("path", { d: "M4 4l8 8M12 4l-8 8" }) });
 function Drawer({
@@ -35,7 +35,10 @@ function Drawer({
       className: cx("uix-drawer", side !== "end" && `uix-drawer--${side}`, className),
       "aria-labelledby": title ? titleId : void 0,
       ...rest,
-      onClick: backdropDismiss(onClose && (() => guard.requestClose()), onClick, dismissOnBackdrop),
+      onClick: (event) => {
+        onClick?.(event);
+        if (dismissOnBackdrop && onClose && isBackdropClick(event)) guard.requestClose(null, event);
+      },
       onKeyDown: (event) => {
         onKeyDown?.(event);
         guard.onKeyDown(event);
@@ -51,7 +54,7 @@ function Drawer({
                   ref: closeRef,
                   type: "button",
                   className: "uix-drawer__close",
-                  onClick: () => guard.requestClose(),
+                  onClick: (event) => guard.requestClose(event.currentTarget, event),
                   "aria-label": closeLabel,
                   "aria-disabled": pending || void 0,
                   children: /* @__PURE__ */ jsx(CloseIcon, {})

package/dist/components/Modal.d.ts

@@ -1,13 +1,17 @@
 import * as react from 'react';
 import { HTMLAttributes, ReactNode } from 'react';
-import { DiscardPromptLabels } from './DiscardPrompt.js';
+import { DialogCloseEvent, DiscardPromptLabels } from './DiscardPrompt.js';
 import './Button.js';
 import '../link.js';
 import './Kbd.js';
 
 interface ModalProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
     open: boolean;
-    onClose?: () => void;
+    /**
+     * Close the dialog. Gets the click that asked (the close button, a `DialogClose`, "Discard");
+     * nothing when the browser closed it (Escape, `<form method="dialog">`).
+     */
+    onClose?: (event?: DialogCloseEvent) => void;
     /**
      * The dialog holds input that is not saved (HAR-2029). Escape, the close button and a
      * `DialogClose` then open an anchored "Discard changes?" step with focus on "Keep editing"

package/dist/components/Modal.js

@@ -48,7 +48,7 @@ function Modal({
                   ref: closeRef,
                   type: "button",
                   className: "uix-dialog__close",
-                  onClick: () => guard.requestClose(),
+                  onClick: (event) => guard.requestClose(event.currentTarget, event),
                   "aria-label": closeLabel,
                   "aria-disabled": pending || void 0,
                   children: /* @__PURE__ */ jsx(CloseIcon, {})

package/dist/components/OrgChart.d.ts

@@ -97,7 +97,12 @@ interface OrgChartProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'
 }
 /** The next zoom step above (`dir` 1) or below (`dir` -1) `zoom`. */
 declare const orgChartZoomStep: (zoom: number, dir: 1 | -1) => number;
-/** "Mira Kovač" → "MK"; one word → its first letter. */
+/**
+ * "Mira Kovač" → "MK"; one word → its first letter. Bracketed parts ("(extern)", "[TST]") and
+ * a title ending in a full stop ("Dr.", "Prof.") are not part of the initials, so
+ * "Dr. Anna-Maria Koenig" → "AK" and "Tenant Admin (dev)" → "TA". The first letter of a word
+ * is its first letter in any script, never a quote or a hyphen in front of it.
+ */
 declare const orgChartInitials: (name: string) => string;
 /**
  * An org chart over `.uix-org-chart` (HAR-1807): managers above their direct reports, joined by

package/dist/components/OrgChart.js

@@ -31,11 +31,14 @@ const orgChartZoomStep = (zoom, dir) => {
   return [...ZOOM_STEPS].reverse().find((s) => s < zoom - 1e-3) ?? MIN_ZOOM;
 };
 const orgChartInitials = (name) => {
-  const words = name.trim().split(/\s+/).filter(Boolean);
-  if (words.length === 0) return "";
-  const first = words[0];
-  const last = words.length > 1 ? words[words.length - 1] : "";
-  return (Array.from(first)[0] ?? "").concat(last ? Array.from(last)[0] ?? "" : "").toUpperCase();
+  const letterOf = (word) => /\p{L}/u.exec(word)?.[0] ?? "";
+  const words = name.replace(/[([{][^)\]}]*[)\]}]/g, " ").trim().split(/\s+/).filter((word) => letterOf(word) !== "");
+  const named = words.length > 1 ? words.filter((word, i) => !(word.endsWith(".") && i < words.length - 1)) : words;
+  const parts = named.length > 0 ? named : words;
+  if (parts.length === 0) return "";
+  const first = letterOf(parts[0]);
+  const last = parts.length > 1 ? letterOf(parts[parts.length - 1]) : "";
+  return `${first}${last}`.toLocaleUpperCase();
 };
 const LOADING = "::uix-loading";
 const FAILED = "::uix-error";

package/dist/dashboard-canvas-model.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Pure model for `DashboardCanvas` (TENSOR HAR-1823): a free dashboard layout on a 12-column
+ * grid. Every item has a place and a size in grid units — `col` and `row` (0-based), `w`
+ * columns wide and `h` rows tall — and may declare the smallest and largest size it accepts.
+ *
+ * The canvas is free: an item stays where it is put, and nothing floats up into a gap. When a
+ * move or a resize lands on other items, they are pushed down below it, in reading order, and
+ * whatever they then land on is pushed in turn. `compactCanvas` is the separate, explicit
+ * "close the gaps" step for a product that wants one (after removing a widget, say).
+ *
+ * The same functions back the pointer drag in the component and the keyboard alternative a
+ * product puts in each item's menu (Move up / down / left / right, Wider / Narrower, Taller /
+ * Shorter), so dragging is never the only way to arrange the canvas (WCAG 2.5.7).
+ */
+/** The canvas has twelve columns: 12 divides into halves, thirds, quarters and sixths. */
+declare const DASHBOARD_CANVAS_COLUMNS = 12;
+interface DashboardCanvasItem {
+    /** Stable id: the key of the cell and of every change reported for it. */
+    readonly id: string;
+    /** First column, 0-based (0 – 11). */
+    readonly col: number;
+    /** First row, 0-based. */
+    readonly row: number;
+    /** Width in columns. */
+    readonly w: number;
+    /** Height in rows. */
+    readonly h: number;
+    /** Narrowest the item may be, in columns. Default 1. */
+    readonly minW?: number;
+    /** Widest the item may be, in columns. Default 12. */
+    readonly maxW?: number;
+    /** Shortest the item may be, in rows. Default 1. */
+    readonly minH?: number;
+    /** Tallest the item may be, in rows. Default: no limit. */
+    readonly maxH?: number;
+}
+/** A keyboard move: one column or one row at a time. */
+type DashboardCanvasDirection = 'up' | 'down' | 'left' | 'right';
+/** A keyboard resize: one column or one row at a time. */
+type DashboardCanvasResize = 'wider' | 'narrower' | 'taller' | 'shorter';
+/** Where and how big an item is, in grid units. */
+interface DashboardCanvasPlacement {
+    readonly col: number;
+    readonly row: number;
+    readonly w: number;
+    readonly h: number;
+}
+/** An item's size limits, made sane: whole numbers, inside the canvas, minimum never above maximum. */
+declare function canvasItemLimits(item: DashboardCanvasItem): {
+    readonly minW: number;
+    readonly maxW: number;
+    readonly minH: number;
+    readonly maxH: number;
+};
+/**
+ * The item made valid: whole numbers, its size inside its own limits and the canvas, and its
+ * place inside the twelve columns (a too-wide item at the right edge moves left). Limits from
+ * an untyped caller are made sane too: a maximum below the minimum is raised to it.
+ */
+declare function clampCanvasItem<T extends DashboardCanvasItem>(item: T): T;
+/** True when two different items share at least one cell. */
+declare function canvasItemsOverlap(a: DashboardCanvasPlacement & {
+    readonly id: string;
+}, b: DashboardCanvasPlacement & {
+    readonly id: string;
+}): boolean;
+/**
+ * Reading order: row by row from the top, left to right in a row. Ties keep the order they
+ * came in. This is the order the canvas collapses to on a narrow screen and the order a
+ * screen reader meets the items in.
+ */
+declare function canvasReadingOrder<T extends DashboardCanvasItem>(items: readonly T[]): T[];
+/** The number of rows the canvas uses: one past the lowest item's last row. */
+declare function canvasRowCount(items: readonly DashboardCanvasItem[]): number;
+/**
+ * A layout with every item valid and no two sharing a cell. Use it on a stored layout before
+ * showing it: an overlap someone saved elsewhere is settled the same way a move settles one.
+ */
+declare function normalizeCanvas<T extends DashboardCanvasItem>(items: readonly T[]): T[];
+/**
+ * Puts one item at a new place and size (clamped to its limits and the canvas) and pushes
+ * what it lands on down. Every other item keeps its place unless it had to move. Returns the
+ * items in the order they came in; an unknown id returns them unchanged.
+ */
+declare function placeCanvasItem<T extends DashboardCanvasItem>(items: readonly T[], id: string, placement: Partial<DashboardCanvasPlacement>): T[];
+/** One step of a keyboard move, as a new place. Null when the item is already at that edge. */
+declare function canvasMoveTarget(item: DashboardCanvasItem, direction: DashboardCanvasDirection): DashboardCanvasPlacement | null;
+/**
+ * One step of a keyboard resize, as a new place and size. `wider` grows to the right, or to the
+ * left when the item already touches the right edge. Null when the item is at its limit.
+ */
+declare function canvasResizeTarget(item: DashboardCanvasItem, change: DashboardCanvasResize): DashboardCanvasPlacement | null;
+/** Moves an item one column or row. At an edge the items come back unchanged. */
+declare function moveCanvasItem<T extends DashboardCanvasItem>(items: readonly T[], id: string, direction: DashboardCanvasDirection): T[];
+/** Resizes an item by one column or row. At a limit the items come back unchanged. */
+declare function resizeCanvasItem<T extends DashboardCanvasItem>(items: readonly T[], id: string, change: DashboardCanvasResize): T[];
+/**
+ * Closes the gaps: in reading order, each item rises as far as it can without landing on one
+ * above it. Columns and sizes never change. Not called by the canvas itself — a free canvas
+ * keeps the gaps a person leaves — but by a product that wants a tidy layout.
+ */
+declare function compactCanvas<T extends DashboardCanvasItem>(items: readonly T[]): T[];
+
+export { DASHBOARD_CANVAS_COLUMNS, type DashboardCanvasDirection, type DashboardCanvasItem, type DashboardCanvasPlacement, type DashboardCanvasResize, canvasItemLimits, canvasItemsOverlap, canvasMoveTarget, canvasReadingOrder, canvasResizeTarget, canvasRowCount, clampCanvasItem, compactCanvas, moveCanvasItem, normalizeCanvas, placeCanvasItem, resizeCanvasItem };