@terpjs/react-core 0.7.0 → 0.8.0

package/src/dataview/DataViewToolbar.tsx

@@ -49,6 +49,14 @@ export interface DataViewToolbarProps<T> {
  * the page-size selector, the table/cards toggle and the column-settings menu; when
  * rows are selected it switches to selection mode ("N selected", batch actions,
  * select-all-across-pages, clear selection).
+ *
+ * It renders no inline styles: the band, both its modes and every part inside it take
+ * their geometry from the injected react-core sheet, matched on the `data-terp` markers
+ * stamped below and on `data-variant="selection"` (ADR 0094). Two of this element's
+ * direct children are arbitrary caller slots — `children` and `trailing` — which is why
+ * the band's own rule declares no `color` and why the refresh status carries a marker
+ * instead of being reached as `[data-terp="dataview-toolbar"] > [role="status"]`: owning
+ * one instance of an attribute is not owning every element such a selector reaches.
  */
 export function DataViewToolbar<T>(props: DataViewToolbarProps<T>) {
   const { strings, resolve, format } = useDataViewText();
@@ -56,25 +64,16 @@ export function DataViewToolbar<T>(props: DataViewToolbarProps<T>) {
 
   const selectionMode = props.selectedCount > 0;
 
-  const barStyle = {
-    display: "flex",
-    alignItems: "center",
-    gap: "var(--space-2)",
-    flexWrap: "wrap",
-    padding: "var(--space-2) var(--space-3)",
-    borderBottom: "1px solid var(--color-neutral-200)",
-    background: selectionMode ? "var(--color-neutral-50)" : "var(--color-neutral-0)",
-    borderTopLeftRadius: "var(--radius-lg)",
-    borderTopRightRadius: "var(--radius-lg)",
-    minHeight: "3rem",
-  } as const;
-
   if (selectionMode) {
     const inlineActions = (props.batchActions ?? []).filter((action) => action.inline !== false);
     const overflowActions = (props.batchActions ?? []).filter((action) => action.inline === false);
     return (
-      <div data-terp="dataview-toolbar" style={barStyle}>
-        <span style={{ fontWeight: "var(--font-weight-medium)" as never }}>
+      // data-variant rather than data-selected: in this cluster "selected" already means
+      // "this element is selected" (rows, cards, menu items), and the toolbar is not
+      // selected — it is showing a different mode. Stamped as a literal in this branch and
+      // omitted in the other, which is the cluster's idiom of not naming the default.
+      <div data-terp="dataview-toolbar" data-variant="selection">
+        <span data-terp="dataview-toolbar-count">
           {format(strings.selected, { count: props.selectedCount })}
         </span>
         {props.onSelectAllAcrossPages !== undefined && !props.selectAllAcrossPages && (
@@ -82,18 +81,17 @@ export function DataViewToolbar<T>(props: DataViewToolbarProps<T>) {
             {format(strings.selectAllResults, { total: props.totalCount })}
           </Button>
         )}
-        <span style={{ display: "inline-flex", gap: "var(--space-2)", flexWrap: "wrap" }}>
+        <span data-terp="dataview-toolbar-actions">
           {inlineActions.map((action, index) => (
             <Button
               key={index}
               variant={action.variant === "destructive" ? "danger" : "secondary"}
+              // Button's own icon slot, rather than a hand-rolled aria-hidden span: it
+              // renders [data-terp="button-icon"], which is already ruled and already
+              // carries flex-shrink: 0 that the hand-rolled one lacked.
+              icon={action.icon}
               onClick={() => props.onBatchAction(action)}
             >
-              {action.icon !== undefined && (
-                <span aria-hidden style={{ display: "inline-flex", marginRight: "var(--space-1)" }}>
-                  {action.icon}
-                </span>
-              )}
               {resolve(action.label)}
             </Button>
           ))}
@@ -118,7 +116,7 @@ export function DataViewToolbar<T>(props: DataViewToolbarProps<T>) {
             </DataViewMenu>
           )}
         </span>
-        <span style={{ flex: 1 }} />
+        <span data-terp="dataview-toolbar-spacer" />
         <Button variant="secondary" onClick={props.onClearSelection}>
           {resolve(strings.clearSelection)}
         </Button>
@@ -127,19 +125,12 @@ export function DataViewToolbar<T>(props: DataViewToolbarProps<T>) {
   }
 
   return (
-    <div data-terp="dataview-toolbar" style={barStyle}>
+    <div data-terp="dataview-toolbar">
       {props.searchEnabled && (
-        <span style={{ position: "relative", display: "inline-flex", alignItems: "center" }}>
-          <span
-            aria-hidden
-            style={{
-              position: "absolute",
-              left: "var(--space-2)",
-              display: "inline-flex",
-              color: "var(--color-neutral-500)",
-              pointerEvents: "none",
-            }}
-          >
+        <span data-terp="dataview-toolbar-search">
+          {/* Unmarked, and reached as this wrapper's only span child: it is decoration with
+              no state, and the wrapper holds no caller slot. */}
+          <span aria-hidden>
             <SearchGlyph size={14} />
           </span>
           <Input
@@ -148,38 +139,32 @@ export function DataViewToolbar<T>(props: DataViewToolbarProps<T>) {
             onChange={(event) => search.setInputValue(event.target.value)}
             placeholder={resolve(props.searchPlaceholder ?? strings.searchPlaceholder)}
             aria-label={resolve(props.searchPlaceholder ?? strings.searchPlaceholder)}
-            style={{
-              paddingLeft: "var(--space-6)",
-              paddingRight: "var(--space-6)",
-              width: "16rem",
-              maxWidth: "100%",
-            }}
           />
           {search.inputValue !== "" && (
             <button
               type="button"
+              data-terp="iconbutton"
               aria-label={resolve(strings.clearSearch)}
               onClick={search.clear}
-              style={{
-                position: "absolute",
-                right: "var(--space-1)",
-                display: "inline-flex",
-                padding: "var(--space-1)",
-                background: "transparent",
-                border: "none",
-                cursor: "pointer",
-                color: "var(--color-neutral-500)",
-              }}
             >
               <CloseGlyph size={14} />
             </button>
           )}
         </span>
       )}
+      {/* No aria-pressed, and its absence is the decision. This control swaps its LABEL
+          between the caller's `label` and `broadenedLabel` — "Search everything" becomes
+          "Searching everything" — so the state is already in the accessible name. Adding
+          aria-pressed encodes the same fact a second way and announces it twice ("Searching
+          everything, toggle button, pressed"), which is the case ARIA's own guidance names:
+          when the label changes to describe the new state, the state is the label. The two
+          encodings can also disagree, because the labels are caller-supplied and nothing
+          checks that broadenedLabel actually reads as the broadened one.
+          No specimen or test rendered this branch until the search-scope one existed, which
+          is why this shipped for as long as it did: it needs a non-empty search term. */}
       {props.searchScope !== undefined && props.search.trim() !== "" && (
         <Button
           variant="secondary"
-          aria-pressed={props.searchScope.broadened}
           onClick={() => props.searchScope?.onBroadenedChange(!props.searchScope.broadened)}
         >
           {resolve(
@@ -194,22 +179,25 @@ export function DataViewToolbar<T>(props: DataViewToolbarProps<T>) {
         </Button>
       )}
       {props.isFetching && (
-        <span
-          role="status"
-          style={{ fontSize: "var(--font-size-sm)", color: "var(--color-neutral-500)" }}
-        >
+        <span role="status" data-terp="dataview-toolbar-status">
           {resolve(strings.refreshing)}
         </span>
       )}
-      <span style={{ flex: 1 }} />
+      <span data-terp="dataview-toolbar-spacer" />
       {props.onPageSizeChange !== undefined && props.pageSize !== undefined && (
         <DataViewMenu
           triggerLabel={resolve(strings.pageSize)}
+          // A fragment, not a wrapper span: [data-terp="menu-trigger"] already declares
+          // display: inline-flex, align-items: center, justify-content: center and
+          // gap: var(--space-1) — the deleted span's three declarations verbatim, with the
+          // gap applying to exactly this pair. Keeping the span would need a marker of its
+          // own, because [data-terp="menu-trigger"] > span would also catch the
+          // column-settings trigger's text span in this same toolbar.
           trigger={
-            <span style={{ display: "inline-flex", alignItems: "center", gap: "var(--space-1)" }}>
+            <>
               {props.pageSize}
               <ChevronDownGlyph size={14} />
-            </span>
+            </>
           }
         >
           {(close) =>
@@ -228,22 +216,26 @@ export function DataViewToolbar<T>(props: DataViewToolbarProps<T>) {
         </DataViewMenu>
       )}
       {props.onLayoutChange !== undefined && (
-        <span style={{ display: "inline-flex", gap: "var(--space-1)" }}>
+        <span data-terp="dataview-toolbar-layout">
+          {/* The shared icon-button marker, so these two gain the transition, the focus
+              ring and reduced-motion coverage they escaped entirely. Which one is active is
+              aria-pressed — the real ARIA state, not a data attribute duplicating it — and
+              this component is its sole author, setting it from its own layout prop. */}
           <button
             type="button"
+            data-terp="iconbutton"
             aria-label={resolve(strings.tableView)}
             aria-pressed={props.layout === "table"}
             onClick={() => props.onLayoutChange?.("table")}
-            style={layoutToggleStyle(props.layout === "table")}
           >
             <TableGlyph />
           </button>
           <button
             type="button"
+            data-terp="iconbutton"
             aria-label={resolve(strings.cardView)}
             aria-pressed={props.layout === "cards"}
             onClick={() => props.onLayoutChange?.("cards")}
-            style={layoutToggleStyle(props.layout === "cards")}
           >
             <CardsGlyph />
           </button>
@@ -254,18 +246,3 @@ export function DataViewToolbar<T>(props: DataViewToolbarProps<T>) {
     </div>
   );
 }
-
-function layoutToggleStyle(active: boolean) {
-  return {
-    display: "inline-flex",
-    alignItems: "center",
-    justifyContent: "center",
-    minHeight: "2rem",
-    padding: "var(--space-1) var(--space-2)",
-    background: active ? "var(--color-neutral-100)" : "transparent",
-    border: "1px solid var(--color-neutral-300)",
-    borderRadius: "var(--radius-md)",
-    cursor: "pointer",
-    color: active ? "var(--color-neutral-900)" : "var(--color-neutral-500)",
-  } as const;
-}

package/src/dataview/README.md

@@ -133,6 +133,12 @@ versioned envelope; corrupt data falls back to defaults) and
   from `meta.mobileSlot` (`title` / `subtitle` / `status` / `date`), with
   `renderCard(row)` as a full escape hatch; selection, actions and expansion keep
   working in card view.
+- **Density**: `density="compact"` stamps `data-density="compact"` on the root, which
+  re-scopes the live density tokens for the whole subtree — cell padding here, plus the
+  control heights `Button`, `Input` and `Select` already read, so the toolbar tightens
+  with the table. `"comfortable"` is the default and stamps no attribute, because
+  comfortable is what the token sheet declares on `:root`; the consequence is that
+  `density="comfortable"` cannot make one view comfortable inside a compact subtree.
 - **Variants**: `variant="embedded"` renders a plain compact view (no view toggle, no
   page-size selector, no pagination footer, all rows) for panels/detail sections.
 - **i18n**: no hard-coded user-facing strings — every label is a `UiText` routed

package/src/dataview/index.ts

@@ -24,6 +24,7 @@ export type {
   ViewStateRepository,
   DataViewColumn,
   DataViewColumnMeta,
+  DataViewDensity,
   DataViewMobileSlot,
   DataViewRowAction,
   DataViewBatchAction,

package/src/dataview/internal.tsx

@@ -53,6 +53,7 @@ export function DataViewMenu({
   trigger,
   triggerLabel,
   align = "end",
+  defaultOpen,
   children,
 }: {
   /** Trigger content (an icon or a label). */
@@ -60,11 +61,13 @@ export function DataViewMenu({
   /** Accessible name of the trigger button. */
   triggerLabel: string;
   align?: "start" | "end";
+  /** Open on mount — threaded to `Menu`, which has carried this since the overlays moved. */
+  defaultOpen?: boolean;
   /** Panel content; render-prop so items can close the menu after acting. */
   children: (close: () => void) => ReactNode;
 }) {
   return (
-    <Menu trigger={trigger} triggerLabel={triggerLabel} align={align}>
+    <Menu trigger={trigger} triggerLabel={triggerLabel} align={align} defaultOpen={defaultOpen}>
       {({ close }) => children(() => close(false))}
     </Menu>
   );

package/src/dataview/types.ts

@@ -94,6 +94,19 @@ export function emptyDataViewState(): DataViewState {
 /** Slot a column occupies in the responsive card layout. */
 export type DataViewMobileSlot = "title" | "subtitle" | "status" | "date";
 
+/**
+ * How tightly a view packs its cells.
+ *
+ * Geometry, not colour: the contract publishes the live density tokens at their
+ * comfortable values plus explicit compact counterparts, and the react-core sheet
+ * re-scopes the live ones under `[data-density="compact"]`. So this is one attribute
+ * stamped on a subtree root, and every rule reading a live token follows by
+ * custom-property inheritance — including the control heights `Button`, `Input` and
+ * `Select` already read, which is why a compact DataView also gets compact controls
+ * without either component knowing about the other.
+ */
+export type DataViewDensity = "comfortable" | "compact";
+
 /** Typed column meta the DataView-specific features read. */
 export interface DataViewColumnMeta {
   /** Human-readable name used in the column-settings menu (falls back to the header). */

package/src/feedback.test.tsx

@@ -82,6 +82,32 @@ describe("ConfirmDialog", () => {
     expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
   });
 
+  it("links the consequence text to the dialog, and only when there is one", () => {
+    const { rerender } = render(
+      <ConfirmDialog
+        open
+        onOpenChange={() => {}}
+        onConfirm={() => {}}
+        title="Delete this link?"
+        description="Its mappings and its run history are removed with it."
+      />,
+    );
+    // A modal announces its name and its description on open. Unlinked body copy is reached
+    // only by manual exploration — the wrong ergonomics for the one screen whose whole job is
+    // telling someone what a destructive action will do.
+    const dialog = screen.getByRole("dialog");
+    const describedBy = dialog.getAttribute("aria-describedby");
+    expect(describedBy).not.toBeNull();
+    expect(document.getElementById(describedBy!)?.textContent).toBe(
+      "Its mappings and its run history are removed with it.",
+    );
+    // No description means no attribute, rather than an idref pointing at nothing.
+    rerender(
+      <ConfirmDialog open onOpenChange={() => {}} onConfirm={() => {}} title="Delete this link?" />,
+    );
+    expect(screen.getByRole("dialog")).not.toHaveAttribute("aria-describedby");
+  });
+
   it("confirms and cancels through the labelled buttons", () => {
     const onConfirm = vi.fn();
     const onOpenChange = vi.fn();

package/src/files.test.tsx

@@ -71,6 +71,24 @@ describe("FileUpload", () => {
     await waitFor(() => expect(onUploaded).toHaveBeenCalledWith(STORED));
   });
 
+  it("hides the picker input with the hidden attribute, not an inline style", () => {
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <FileUpload />
+      </TerpProvider>,
+    );
+    // The visible control is the button; this input exists only so a programmatic click can
+    // open the native dialog. `hidden` is the platform's own way to say that, and it keeps the
+    // file free of a style object that would read as unmigrated styling.
+    const input = document.querySelector('input[type="file"]') as HTMLInputElement;
+    expect(input).not.toBeNull();
+    expect(input.hidden).toBe(true);
+    expect(input.getAttribute("style")).toBeNull();
+    // Belt and braces, kept deliberately: both survive an author rule that resurrects the box.
+    expect(input).toHaveAttribute("aria-hidden", "true");
+    expect(input.tabIndex).toBe(-1);
+  });
+
   it("reports a failed upload through onError", async () => {
     stubFetch(async (request) => {
       if (request.url.endsWith("/api/v1/files/") && request.method === "POST") {

package/src/files.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useRef, useState } from "react";
-import type { ChangeEvent, CSSProperties } from "react";
+import type { ChangeEvent } from "react";
 
 import { useTerpClient } from "./TerpProvider";
 import { Button } from "./ui/Button";
@@ -107,8 +107,6 @@ export function useFileDownload(): (file: Pick<FileMeta, "id" | "filename">) =>
   );
 }
 
-const hiddenInputStyle: CSSProperties = { display: "none" };
-
 export interface FileUploadProps {
   /** Called with the stored metadata after a successful upload. */
   onUploaded?: (file: FileMeta) => void;
@@ -152,11 +150,22 @@ export function FileUpload({ onUploaded, onError, label, accept, disabled }: Fil
 
   return (
     <>
+      {/* The platform attribute, not an inline display:none.
+
+          This input is the file picker's plumbing: the visible control is the Button below,
+          and this element exists only so `.click()` can open the native dialog. So it is not
+          a styled surface at all, and the alternatives both misdescribe it — giving it a
+          marker and a `display: none` rule would put a component with no visual design into
+          the sheet, and keeping the inline object would leave the one declaration in the file
+          looking like styling that had not been migrated yet. `hidden` is what HTML provides
+          for "not relevant", and a programmatic click still opens the dialog. The
+          `aria-hidden` and `tabIndex` become redundant beside it and are kept anyway: they
+          cost nothing and they survive an author rule that resurrects the box. */}
       <input
         ref={inputRef}
         type="file"
         accept={accept}
-        style={hiddenInputStyle}
+        hidden
         onChange={(event) => void onChange(event)}
         aria-hidden="true"
         tabIndex={-1}

package/src/icons.test.tsx

@@ -11,7 +11,10 @@ describe("NavIcon", () => {
     const { container } = render(<NavIcon name="users" label="Users" />);
     const slot = container.querySelector('[data-terp="nav-icon"]');
     const svg = container.querySelector("svg");
-    expect(slot).toHaveStyle({ width: "1.25rem", height: "1.25rem", flex: "0 0 1.25rem" });
+    // The rail slot's fixed 1.25rem box is a sheet rule now (ADR 0094); what this test
+    // owns is that the named glyph resolved and stayed decorative.
+    expect(slot).not.toBeNull();
+    expect(slot?.getAttribute("style")).toBeNull();
     expect(svg).not.toBeNull();
     expect(svg).toHaveAttribute("aria-hidden", "true");
   });
@@ -19,11 +22,12 @@ describe("NavIcon", () => {
   it("falls back to the label's initial for an unknown or missing name", () => {
     const { container } = render(<NavIcon name="no-such-glyph" label="widgets" />);
     expect(screen.getByText("W")).toBeInTheDocument();
-    expect(container.querySelector('[data-terp="nav-icon"]')).toHaveStyle({
-      width: "1.25rem",
-      height: "1.25rem",
-      flex: "0 0 1.25rem",
-    });
+    // The fallback tile is its own marker, so the rail can style "an initial in a tile"
+    // separately from "a glyph" — which is the distinction a theme cares about.
+    expect(
+      container.querySelector('[data-terp="nav-icon-fallback"]'),
+      "the initial renders in the fallback tile",
+    ).not.toBeNull();
     render(<NavIcon label="records" />);
     expect(screen.getByText("R")).toBeInTheDocument();
   });

package/src/icons.tsx

@@ -1,4 +1,8 @@
-import type { CSSProperties, ReactNode } from "react";
+import type { ReactNode } from "react";
+
+import { injectTerpStyles } from "./styles";
+
+injectTerpStyles();
 
 /**
  * The dependency-free icon layer: a small set of inline SVG glyphs the shell's
@@ -431,31 +435,6 @@ export const ICON_GLYPHS: Record<string, ReactNode> = {
   ),
 };
 
-const navIconStyle: CSSProperties = {
-  display: "inline-flex",
-  alignItems: "center",
-  justifyContent: "center",
-  width: "1.25rem",
-  height: "1.25rem",
-  flex: "0 0 1.25rem",
-  fontSize: "1rem",
-  lineHeight: 1,
-};
-
-const fallbackStyle: CSSProperties = {
-  display: "inline-flex",
-  alignItems: "center",
-  justifyContent: "center",
-  width: "100%",
-  height: "100%",
-  borderRadius: "var(--radius-sm, 4px)",
-  background: "var(--color-brand-primary-soft, var(--color-neutral-200))",
-  color: "var(--color-brand-primary, var(--color-neutral-700))",
-  fontSize: "0.7em",
-  fontWeight: "var(--font-weight-medium)" as CSSProperties["fontWeight"],
-  lineHeight: 1,
-};
-
 export interface NavIconProps {
   /** Glyph name (a `NavItem.icon` value); unknown / missing falls back to the initial. */
   name?: string;
@@ -470,9 +449,9 @@ export interface NavIconProps {
 export function NavIcon({ name, label }: NavIconProps) {
   const glyph = name !== undefined ? ICON_GLYPHS[name] : undefined;
   return (
-    <span aria-hidden="true" data-terp="nav-icon" style={navIconStyle}>
+    <span aria-hidden="true" data-terp="nav-icon">
       {glyph ?? (
-        <span style={fallbackStyle}>
+        <span data-terp="nav-icon-fallback">
           {(label[0] ?? "?").toUpperCase()}
         </span>
       )}
@@ -511,15 +490,8 @@ export function Icon({ name, size = "1em", title }: IconProps) {
       aria-hidden={labelled ? undefined : true}
       role={labelled ? "img" : undefined}
       aria-label={labelled ? title : undefined}
-      style={{
-        display: "inline-flex",
-        alignItems: "center",
-        justifyContent: "center",
-        width: px,
-        height: px,
-        lineHeight: 1,
-        color: "inherit",
-      }}
+      data-terp="icon"
+      style={{ width: px, height: px }}
     >
       {glyph}
     </span>

package/src/index.ts

@@ -30,9 +30,6 @@ export type { RequireAuthProps } from "./RequireAuth";
 export { visibleNav } from "./nav";
 export {
   AppShell,
-  NAV_LINK_STYLE,
-  NAV_LINK_COLLAPSED_STYLE,
-  NAV_LINK_ACTIVE_STYLE,
   SIDEBAR_STORAGE_KEY,
 } from "./AppShell";
 export type {

package/src/layout.test.tsx

@@ -7,7 +7,7 @@ import { DetailList, Stack } from "./layout";
 afterEach(cleanup);
 
 describe("Stack", () => {
-  it("renders a flex column with a token gap by default", () => {
+  it("names a column at the default gap, with no inline styling", () => {
     render(
       <Stack data-testid="stack">
         <span>a</span>
@@ -16,24 +16,39 @@ describe("Stack", () => {
     );
     const el = screen.getByTestId("stack");
     expect(el.tagName).toBe("DIV");
-    expect(el.style.display).toBe("flex");
-    expect(el.style.flexDirection).toBe("column");
-    expect(el.style.gap).toBe("var(--space-2)");
+    expect(el).toHaveAttribute("data-direction", "column");
+    expect(el).toHaveAttribute("data-gap", "2");
+    expect(el).not.toHaveAttribute("data-wrap");
+    expect(el.getAttribute("style")).toBeNull();
   });
 
-  it("renders the requested element with direction, gap, alignment and wrap", () => {
+  it("renders the requested element and names direction, gap and wrap", () => {
     render(
-      <Stack data-testid="row" as="section" direction="row" gap={4} align="center" justify="space-between" wrap>
+      <Stack data-testid="row" as="section" direction="row" gap={4} wrap>
         <span>a</span>
       </Stack>,
     );
     const el = screen.getByTestId("row");
     expect(el.tagName).toBe("SECTION");
-    expect(el.style.flexDirection).toBe("row");
-    expect(el.style.gap).toBe("var(--space-4)");
+    expect(el).toHaveAttribute("data-direction", "row");
+    expect(el).toHaveAttribute("data-gap", "4");
+    expect(el).toHaveAttribute("data-wrap", "true");
+    expect(el.getAttribute("style")).toBeNull();
+  });
+
+  it("keeps alignment inline, because it is an open set of CSS keywords", () => {
+    // align/justify accept any alignment keyword, so they cannot become a rule per value
+    // without inventing a vocabulary CSS already has (ADR 0094). They stay inline, and
+    // the geometry attributes stay attributes — the two halves of the same element.
+    render(
+      <Stack data-testid="aligned" align="center" justify="space-between">
+        <span>a</span>
+      </Stack>,
+    );
+    const el = screen.getByTestId("aligned");
     expect(el.style.alignItems).toBe("center");
     expect(el.style.justifyContent).toBe("space-between");
-    expect(el.style.flexWrap).toBe("wrap");
+    expect(el.style.display).toBe("");
   });
 
   it("works as a form (submit handler fires)", () => {

package/src/layout.tsx

@@ -38,16 +38,27 @@ export function Stack({
   wrap = false,
   ...rest
 }: StackProps) {
-  const style: CSSProperties = {
-    display: "flex",
-    flexDirection: direction,
-    gap: `var(--space-${gap})`,
-    margin: 0,
-    ...(align !== undefined ? { alignItems: align } : undefined),
-    ...(justify !== undefined ? { justifyContent: justify } : undefined),
-    ...(wrap ? { flexWrap: "wrap" } : undefined),
-  };
-  return <Component {...rest} data-terp="stack" style={style} />;
+  // `direction`, `gap` and `wrap` are closed sets, so they are attributes the sheet keys
+  // on. `align` and `justify` take any alignment keyword CSS accepts, so they stay inline
+  // rather than turning an open vocabulary into a rule per value (ADR 0094). Undefined on
+  // both means no style attribute at all.
+  const alignment: CSSProperties | undefined =
+    align === undefined && justify === undefined
+      ? undefined
+      : {
+          ...(align !== undefined ? { alignItems: align } : undefined),
+          ...(justify !== undefined ? { justifyContent: justify } : undefined),
+        };
+  return (
+    <Component
+      {...rest}
+      data-terp="stack"
+      data-direction={direction}
+      data-gap={String(gap)}
+      data-wrap={wrap ? "true" : undefined}
+      style={alignment}
+    />
+  );
 }
 
 export interface DetailItem {
@@ -62,14 +73,6 @@ export interface DetailListProps extends Omit<HTMLAttributes<HTMLDListElement>,
   items: readonly DetailItem[];
 }
 
-const detailListStyle: CSSProperties = {
-  margin: 0,
-  display: "grid",
-  gap: "var(--space-1)",
-};
-const detailTermStyle: CSSProperties = { display: "inline", fontWeight: "var(--font-weight-medium)" };
-const detailValueStyle: CSSProperties = { display: "inline", margin: 0 };
-
 /**
  * Token-styled label/value pairs as a semantic `<dl>` — record metadata on a detail page,
  * an expanded row's summary. Centralizes the "Label: value" pattern so modules never
@@ -78,11 +81,11 @@ const detailValueStyle: CSSProperties = { display: "inline", margin: 0 };
 export function DetailList({ items, ...rest }: DetailListProps) {
   const text = useUiText();
   return (
-    <dl {...rest} data-terp="detail-list" style={detailListStyle}>
+    <dl {...rest} data-terp="detail-list">
       {items.map((item, index) => (
         <div key={index}>
-          <dt style={detailTermStyle}>{text(item.label)}: </dt>
-          <dd style={detailValueStyle}>{item.value}</dd>
+          <dt data-terp="detail-list-term">{text(item.label)}: </dt>
+          <dd data-terp="detail-list-value">{item.value}</dd>
         </div>
       ))}
     </dl>