@terpjs/react-core 0.6.1 → 0.8.0

package/src/HubPage.tsx

@@ -1,4 +1,4 @@
-import type { CSSProperties, ReactNode } from "react";
+import type { ReactNode } from "react";
 import { useEffect, useRef, useState } from "react";
 
 import { Page } from "./Page";
@@ -19,22 +19,15 @@ export type HubPageProps = Omit<
   parents?: PageProps["breadcrumbs"];
 };
 
-const gridStyle: CSSProperties = {
-  display: "grid",
-  gridTemplateColumns: "repeat(auto-fit, minmax(min(16rem, 100%), 1fr))",
-  gridAutoRows: "1fr",
-  gap: "var(--space-4)",
-  alignItems: "stretch",
-  listStyle: "none",
-  margin: 0,
-  padding: 0,
-};
-
 /**
  * The landing / hub page archetype: a `Page` whose body is a responsive grid of
  * {@link HubCard} links into the sub-areas of a domain. Use it as a module index that
  * adds discovery value (each card can carry a live `stat`, making the hub a lightweight
  * dashboard) — never as a mandatory speed-bump in front of a single frequently-used list.
+ *
+ * It renders no inline styles: the grid and every part of a card take their geometry from
+ * the injected react-core sheet, matched on the `data-terp` markers stamped below
+ * (ADR 0094).
  */
 export function HubPage({ children, parents, breadcrumbs, ...page }: HubPageProps) {
   // The runtime half of the slot-typed layout contract control (ADR 0079) for the hub
@@ -61,7 +54,7 @@ export function HubPage({ children, parents, breadcrumbs, ...page }: HubPageProp
   }
   return (
     <Page {...page} breadcrumbs={parents ?? breadcrumbs}>
-      <ul ref={gridRef} style={gridStyle}>
+      <ul ref={gridRef} data-terp="hubpage-grid">
         {children}
       </ul>
     </Page>
@@ -89,86 +82,23 @@ export interface HubCardProps {
   renderLink?: RenderHubCardLink;
 }
 
-const cardStyle: CSSProperties = {
-  height: "100%",
-  minHeight: 0,
-};
-
-const cardBodyStyle: CSSProperties = {
-  display: "grid",
-  gridTemplateRows: "auto minmax(3rem, 1fr) auto",
-  gap: "var(--space-2)",
-  height: "100%",
-  minHeight: "10rem",
-  padding: "var(--space-4)",
-  border: "1px solid var(--color-neutral-200)",
-  borderRadius: "var(--radius-lg)",
-  background: "var(--color-neutral-0)",
-  color: "var(--color-neutral-900)",
-  boxSizing: "border-box",
-};
-
-const cardTitleRowStyle: CSSProperties = {
-  margin: 0,
-  display: "flex",
-  alignItems: "center",
-  gap: "var(--space-3)",
-};
-
-const iconTileStyle: CSSProperties = {
-  display: "inline-flex",
-  alignItems: "center",
-  justifyContent: "center",
-  width: "2.25rem",
-  height: "2.25rem",
-  flexShrink: 0,
-  borderRadius: "var(--radius-md)",
-  background: "var(--color-brand-primary-soft)",
-  color: "var(--color-brand-primary)",
-};
-
-const titleTextStyle: CSSProperties = {
-  color: "var(--color-neutral-900)",
-  fontSize: "var(--font-size-base)",
-  fontWeight: "var(--font-weight-semibold)" as CSSProperties["fontWeight"],
-  transition: "color 150ms ease",
-};
-
-const descriptionStyle: CSSProperties = {
-  margin: 0,
-  color: "var(--color-neutral-600)",
-  fontSize: "var(--font-size-sm)",
-  lineHeight: 1.5,
-};
-
-const emptyDescriptionStyle: CSSProperties = { ...descriptionStyle, visibility: "hidden" };
-
-const statStyle: CSSProperties = {
-  color: "var(--color-neutral-900)",
-  fontSize: "var(--font-size-sm)",
-  fontWeight: "var(--font-weight-semibold)" as CSSProperties["fontWeight"],
-};
-const emptyStatStyle: CSSProperties = { ...statStyle, visibility: "hidden" };
-
-const linkStyle: CSSProperties = {
-  textDecoration: "none",
-  color: "inherit",
-  display: "block",
-  height: "100%",
-  minHeight: 0,
-};
-
 const anchorRenderLink: RenderHubCardLink = ({ to, children }) => (
-  <a href={to} data-terp="hubcard-link" style={linkStyle}>
+  <a href={to} data-terp="hubcard-link">
     {children}
   </a>
 );
 
 /**
- * A single navigable card inside a {@link HubPage}: icon + title, a short description of
+ * A single navigable card inside a {@link HubPage}: icon + title, a short explanation of
  * the area, and an optional live `stat`. The whole card is one link, rendered through
  * `renderLink` so the hub stays router-agnostic — defaulting to the surrounding router's
  * `Link`, and to a plain anchor only outside a Terp router.
+ *
+ * The description and stat rows always render, carrying a non-breaking space when the prop
+ * is absent, so a card's three grid rows keep their heights and a bare card stays flush
+ * with a full one in the same row. `data-empty` is what hides the placeholder — an
+ * attribute rather than a second style object, because "is this row a placeholder" is a
+ * fact about the element that a rule can read.
  */
 export function HubCard({
   to,
@@ -184,27 +114,26 @@ export function HubCard({
     (navLink === null
       ? anchorRenderLink
       : ({ to: href, children }: { to: string; children: ReactNode }) => (
-          <span data-terp="hubcard-link" style={linkStyle}>
-            {navLink({ to: href, children })}
-          </span>
+          <span data-terp="hubcard-link">{navLink({ to: href, children })}</span>
         ));
   const resolve = useUiText();
   return (
-    <li data-terp="hubcard" style={cardStyle}>
+    <li data-terp="hubcard">
       {renderCardLink({
         to,
         children: (
-          <span data-terp="hubcard-body" style={cardBodyStyle}>
-            <span style={cardTitleRowStyle}>
-              {icon !== undefined && <span style={iconTileStyle}>{icon}</span>}
-              <strong data-terp="hubcard-title" style={titleTextStyle}>
-                {resolve(title)}
-              </strong>
+          <span data-terp="hubcard-body">
+            <span data-terp="hubcard-heading">
+              {icon !== undefined && <span data-terp="hubcard-icon">{icon}</span>}
+              <strong data-terp="hubcard-title">{resolve(title)}</strong>
             </span>
-            <span data-terp="hubcard-description" style={description === undefined ? emptyDescriptionStyle : descriptionStyle}>
+            <span
+              data-terp="hubcard-description"
+              data-empty={description === undefined ? "true" : undefined}
+            >
               {description === undefined ? " " : resolve(description)}
             </span>
-            <span data-terp="hubcard-stat" style={stat === undefined ? emptyStatStyle : statStyle}>
+            <span data-terp="hubcard-stat" data-empty={stat === undefined ? "true" : undefined}>
               {stat ?? " "}
             </span>
           </span>
@@ -213,4 +142,3 @@ export function HubCard({
     </li>
   );
 }
-

package/src/LoadingState.tsx

@@ -1,5 +1,3 @@
-import type { CSSProperties } from "react";
-
 import { injectTerpStyles } from "./styles";
 import { useStrings, useUiText } from "./uiText";
 import type { UiText } from "./uiText";
@@ -23,13 +21,7 @@ export function InlineSpinner({ size = 16 }: InlineSpinnerProps) {
     <span
       aria-hidden="true"
       data-terp="spinner-ring"
-      style={{
-        display: "inline-block",
-        verticalAlign: "middle",
-        width: size,
-        height: size,
-        lineHeight: 0,
-      }}
+      style={{ width: size, height: size }}
     >
       <svg
         aria-hidden="true"
@@ -37,7 +29,6 @@ export function InlineSpinner({ size = 16 }: InlineSpinnerProps) {
         height={size}
         viewBox="0 0 24 24"
         fill="none"
-        style={{ display: "block" }}
       >
         <circle
           cx="12"
@@ -63,18 +54,6 @@ export interface LoadingStateProps {
   label?: UiText;
 }
 
-const wrapStyle: CSSProperties = {
-  display: "flex",
-  alignItems: "center",
-  justifyContent: "center",
-  gap: "var(--space-2)",
-  padding: "var(--space-6)",
-  color: "var(--color-neutral-500)",
-  fontSize: "var(--font-size-sm)",
-};
-
-const spinnerColorStyle: CSSProperties = { color: "var(--color-brand-primary)" };
-
 /**
  * Standard inline loading indicator: a spinner plus a short label, announced
  * as a `status` live region. Use it when a query is pending and the page shell
@@ -85,8 +64,8 @@ export function LoadingState({ label }: LoadingStateProps) {
   const strings = useStrings();
   const resolve = useUiText();
   return (
-    <div role="status" data-terp="loading-state" style={wrapStyle}>
-      <span style={spinnerColorStyle}>
+    <div role="status" data-terp="loading-state">
+      <span data-terp="loading-state-spinner">
         <InlineSpinner size={20} />
       </span>
       <span>{resolve(label ?? strings.loading)}</span>

package/src/ModuleNav.tsx

@@ -41,7 +41,7 @@ const linkStyle: CSSProperties = {
 
 const activeLinkStyle: CSSProperties = {
   color: "var(--color-neutral-900)",
-  borderBottomColor: "var(--color-brand-primary)",
+  borderBottomColor: "var(--color-fg-accent)",
 };
 
 /**

package/src/PageActions.tsx

@@ -1,9 +1,12 @@
-import type { CSSProperties, ReactNode } from "react";
+import type { ReactNode } from "react";
 
+import { injectTerpStyles } from "./styles";
 import { Menu, MenuItem } from "./ui/Menu";
 import { useStrings } from "./uiText";
 import type { UiText } from "./uiText";
 
+injectTerpStyles();
+
 export interface OverflowAction {
   /** Display label for the menu item. */
   label: UiText;
@@ -25,14 +28,6 @@ export interface PageActionsProps {
   className?: string;
 }
 
-const clusterStyle: CSSProperties = {
-  display: "flex",
-  flexWrap: "wrap",
-  alignItems: "center",
-  justifyContent: "flex-end",
-  gap: "var(--space-2)",
-};
-
 /** Standard right-aligned action cluster for page headers. */
 export function PageActions({ primary, secondary, overflow, className }: PageActionsProps) {
   const strings = useStrings();
@@ -43,7 +38,7 @@ export function PageActions({ primary, secondary, overflow, className }: PageAct
   }
 
   return (
-    <div className={className} style={clusterStyle}>
+    <div className={className} data-terp="page-actions">
       {hasOverflow && (
         <Menu trigger="⋯" triggerLabel={strings.moreActions}>
           {({ close }) => (

package/src/UserMenu.test.tsx

@@ -121,13 +121,20 @@ describe("UserMenu", () => {
     const trigger = await screen.findByRole("button", { name: "Account menu" });
     expect(screen.getByText("JD")).toBeInTheDocument();
     expect(screen.queryByText("jane.doe@example.com")).not.toBeInTheDocument();
-    expect(trigger.style.width).toBe("100%");
-    expect(trigger.style.boxSizing).toBe("border-box");
-    expect(trigger.style.justifyContent).toBe("center");
-    expect(trigger.style.padding).toBe("0px");
-    // The identity still surfaces inside the opened panel.
+    // The collapsed geometry is a sheet rule now (ADR 0094), so what this asserts is the
+    // attribute the rule keys on and the absence of the inline object it replaced. The
+    // variant sits on the component's ROOT rather than on the trigger, because the root is
+    // what UserMenu names — the trigger is reached by descending from it.
+    const root = trigger.closest('[data-terp="user-menu"]');
+    expect(root).not.toBeNull();
+    expect(root).toHaveAttribute("data-variant", "collapsed");
+    expect(trigger).toHaveAttribute("data-terp", "menu-trigger");
+    expect(trigger.getAttribute("style")).toBeNull();
+    // The identity still surfaces inside the opened panel, whose geometry is keyed on the
+    // owner attribute — the panel is portalled out, so nothing else could reach it.
     fireEvent.click(trigger);
     expect(screen.getByText("jane.doe@example.com")).toBeInTheDocument();
+    expect(screen.getByRole("menu").parentElement).toHaveAttribute("data-owner", "user-menu");
   });
 
   it("signs out via the menu (revokes the token server-side)", async () => {

package/src/UserMenu.tsx

@@ -1,11 +1,11 @@
-import type { CSSProperties } from "react";
-
 import { Icon } from "./icons";
+import { injectTerpStyles } from "./styles";
 import { useAuth } from "./TerpProvider";
 import { Menu, MenuItem } from "./ui/Menu";
-import { CONTROL_TEXT_STYLE } from "./ui/controlStyles";
 import { useStrings } from "./uiText";
 
+injectTerpStyles();
+
 /** Initials for the avatar: the first letters of the email's local-part words. */
 export function userInitials(email: string): string {
   const local = email.split("@")[0] ?? "";
@@ -14,65 +14,22 @@ export function userInitials(email: string): string {
   return initials.join("") || "?";
 }
 
-const triggerStyle: CSSProperties = {
-  ...CONTROL_TEXT_STYLE,
-  display: "flex",
-  alignItems: "center",
-  justifyContent: "flex-start",
-  gap: "var(--space-2)",
-  width: "100%",
-  boxSizing: "border-box",
-  padding: "var(--space-2)",
-  textAlign: "left",
-  color: "var(--color-neutral-900)",
-  background: "transparent",
-  border: "1px solid transparent",
-  borderRadius: "var(--radius-md)",
-  cursor: "pointer",
-};
-
-const collapsedTriggerStyle: CSSProperties = {
-  justifyContent: "center",
-  gap: 0,
-  padding: 0,
-};
-
-const avatarStyle: CSSProperties = {
-  display: "inline-flex",
-  alignItems: "center",
-  justifyContent: "center",
-  width: "2rem",
-  height: "2rem",
-  flexShrink: 0,
-  borderRadius: "var(--radius-full)",
-  background: "var(--color-brand-primary)",
-  color: "var(--color-brand-primary-contrast)",
-  fontSize: "var(--font-size-sm)",
-  fontWeight: "var(--font-weight-medium)" as CSSProperties["fontWeight"],
-};
-
-const identityStyle: CSSProperties = { display: "grid", minWidth: 0, fontSize: "var(--font-size-sm)" };
-const emailStyle: CSSProperties = { overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" };
-const roleStyle: CSSProperties = { color: "var(--color-neutral-600)" };
-const panelIdentityStyle: CSSProperties = {
-  display: "grid",
-  gap: "var(--space-1)",
-  padding: "var(--space-2)",
-  marginBottom: "var(--space-1)",
-  borderBottom: "1px solid var(--color-neutral-200)",
-  fontSize: "var(--font-size-sm)",
-  overflowWrap: "anywhere",
-};
-
 export interface UserMenuProps {
   /** Icon-rail mode: show only the avatar on the trigger (the shell's collapsed state). */
   collapsed?: boolean;
   /** Opens the settings / profile page; rendered as the menu's first item when provided. */
   onSettings?: () => void;
+  /**
+   * Open the panel on mount (uncontrolled), the shape every other disclosure in the package
+   * takes. It is also the only way to render the panel deterministically, and the panel is
+   * where this component's own geometry lives — so without it those rules ship unpainted by
+   * either visual lane, which is the state the calendar was in for two stages.
+   */
+  defaultOpen?: boolean;
 }
 
 /** The signed-in user's account menu. */
-export function UserMenu({ collapsed = false, onSettings }: UserMenuProps = {}) {
+export function UserMenu({ collapsed = false, onSettings, defaultOpen }: UserMenuProps = {}) {
   const auth = useAuth();
   const strings = useStrings();
   const user = auth.currentUser();
@@ -82,11 +39,11 @@ export function UserMenu({ collapsed = false, onSettings }: UserMenuProps = {})
 
   const trigger = (
     <>
-      <span aria-hidden="true" style={avatarStyle}>{userInitials(user.email)}</span>
+      <span aria-hidden="true" data-terp="user-menu-avatar">{userInitials(user.email)}</span>
       {!collapsed && (
-        <span style={identityStyle}>
-          <span style={emailStyle}>{user.email}</span>
-          <span style={roleStyle}>{user.role_name}</span>
+        <span data-terp="user-menu-identity">
+          <span data-terp="user-menu-email">{user.email}</span>
+          <span data-terp="user-menu-role">{user.role_name}</span>
         </span>
       )}
     </>
@@ -98,14 +55,28 @@ export function UserMenu({ collapsed = false, onSettings }: UserMenuProps = {})
       triggerLabel={strings.accountMenu}
       placement="top"
       align="start"
-      triggerStyle={collapsed ? { ...triggerStyle, ...collapsedTriggerStyle } : triggerStyle}
-      panelStyle={{ minWidth: "14rem", padding: "var(--space-2)" }}
+      defaultOpen={defaultOpen}
+      // This component's rendered root is Menu's popover wrapper — it adds no element of its
+      // own — so it names that root through Menu. The icon-rail mode is a variant of the same
+      // component rather than a different one, so it is data-variant on the same marker; and
+      // the trigger and the panel are then reachable from the sheet, which is what let both
+      // `triggerStyle` and `panelStyle` be deleted. The panel needs the owner attribute
+      // Popover stamps for it: it is portalled to document.body, so no descendant selector
+      // from this side of the tree could ever reach it.
+      data-terp="user-menu"
+      data-variant={collapsed ? "collapsed" : undefined}
+      data-owner="user-menu"
     >
       {({ close }) => (
         <>
-          <div style={panelIdentityStyle}>
+          {/* role="group": a role="menu" may own only menuitem / menuitemradio /
+              menuitemcheckbox / group / separator, and this identity block is a plain div —
+              so in menu mode assistive tech had no valid reason to reach it. A group needs no
+              accessible name to be valid and has no default presentation, so this is an ARIA
+              correction with no visual and no new UI string. */}
+          <div role="group" data-terp="user-menu-header">
             <span>{user.email}</span>
-            <span style={roleStyle}>{user.role_name}</span>
+            <span data-terp="user-menu-role">{user.role_name}</span>
           </div>
           {onSettings !== undefined && (
             <MenuItem

package/src/dataview/DataView.test.tsx

@@ -83,6 +83,32 @@ describe("DataView states", () => {
     const untinted = screen.getByText("Broken printer").closest("tr");
     expect(untinted).not.toHaveAttribute("data-tone");
   });
+
+  it("claims data-clickable only when a row click is wired up", async () => {
+    // The other half of a sheet rule no visual lane can see. The row marker is stamped
+    // unconditionally — it has to be, or a toned row that is not clickable carries data-tone on
+    // an element no selector reaches — so what separates a row Enter will open from a row that
+    // merely contains a focusable checkbox is this attribute alone. The sheet's focus-within
+    // tint is keyed on it, and styles.test.ts pins that end.
+    const { unmount } = render(
+      <DataView repository={inMemoryRepo()} columns={COLUMNS} enableSelection />,
+    );
+    const inert = (await screen.findByText("VPN access")).closest("tr");
+    expect(inert).toHaveAttribute("data-terp", "dataview-row");
+    expect(inert).not.toHaveAttribute("data-clickable");
+    unmount();
+
+    render(
+      <DataView
+        repository={inMemoryRepo()}
+        columns={COLUMNS}
+        getRowLabel={(t) => t.title}
+        onRowClick={() => {}}
+      />,
+    );
+    const clickable = (await screen.findByText("VPN access")).closest("tr");
+    expect(clickable).toHaveAttribute("data-clickable", "true");
+  });
 });
 
 describe("DataView server-side mode", () => {
@@ -365,20 +391,40 @@ describe("DataView search and view options", () => {
     expect(await screen.findByText("Broken printer")).toBeInTheDocument();
   });
 
-  it("hides and reorders columns from the view-options menu", async () => {
+  it("hides and reorders columns from the view-options panel", async () => {
     render(<DataView repository={inMemoryRepo()} columns={COLUMNS} />);
     await screen.findByText("Broken printer");
 
     fireEvent.click(screen.getByRole("button", { name: "View options" }));
-    const menu = screen.getByRole("menu");
-    fireEvent.click(within(menu).getByRole("checkbox", { name: "Status" }));
+    // A group labelled by its own heading, not a menu. That is the fix for a critical
+    // aria-required-children violation: role="menu" may own only menuitem-family children,
+    // and this panel's content is a heading plus labelled checkboxes plus paired reorder
+    // buttons — a form. The guard below is the regression test for it, because the violation
+    // was invisible for as long as nothing rendered the panel open.
+    const panel = screen.getByRole("group", { name: "Columns" });
+    expect(screen.queryByRole("menu")).not.toBeInTheDocument();
+    fireEvent.click(within(panel).getByRole("checkbox", { name: "Status" }));
     expect(screen.queryByRole("columnheader", { name: /Status/ })).not.toBeInTheDocument();
 
-    fireEvent.click(within(menu).getByRole("checkbox", { name: "Status" }));
-    fireEvent.click(within(menu).getByRole("button", { name: "Move up: Status" }));
+    fireEvent.click(within(panel).getByRole("checkbox", { name: "Status" }));
+    fireEvent.click(within(panel).getByRole("button", { name: "Move up: Status" }));
     const headers = screen.getAllByRole("columnheader").map((th) => th.textContent);
     expect(headers[0]).toContain("Status");
   });
+
+  it("names the view-options trigger from its visible label, not an override", async () => {
+    // The trigger used to take its accessible name from an aria-label the menu primitive
+    // applied, which is the shape that hides a visible label from assistive tech when the two
+    // drift. It is now named by its own content, so the announced name IS the rendered one.
+    render(<DataView repository={inMemoryRepo()} columns={COLUMNS} />);
+    await screen.findByText("Broken printer");
+    const trigger = screen.getByRole("button", { name: "View options" });
+    expect(trigger).not.toHaveAttribute("aria-label");
+    expect(trigger).toHaveTextContent("View options");
+    // A disclosure, so this is the whole contract: expanded state plus the panel it controls.
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    expect(trigger).not.toHaveAttribute("aria-haspopup");
+  });
 });
 
 describe("DataView embedded variant", () => {
@@ -404,3 +450,61 @@ describe("DataView embedded variant", () => {
     expect(document.querySelector('[data-terp="dataview-toolbar"]')).not.toBeInTheDocument();
   });
 });
+
+describe("DataView search scope", () => {
+  // Nothing rendered this branch before the search-scope specimen existed: the control is
+  // behind `search.trim() !== ""`, and every other test and specimen starts with an empty box.
+  // That is how a control shipped announcing itself as a toggle button whose state is also its
+  // label.
+  const scopedRepo = (): DataViewRepository<Ticket> => ({
+    query: async () => ({ rows: TICKETS, totalCount: TICKETS.length }),
+    getRowId: (ticket) => ticket.id,
+    capabilities: { serverSide: true, search: true, searchScope: true },
+  });
+
+  it("swaps the label rather than claiming to be a toggle button", async () => {
+    const onBroadenedChange = vi.fn();
+    const { rerender } = render(
+      <DataView
+        repository={scopedRepo()}
+        columns={COLUMNS}
+        searchScope={{
+          broadened: false,
+          onBroadenedChange,
+          label: "Search everything",
+          broadenedLabel: "Searching everything",
+        }}
+      />,
+    );
+    await screen.findByText("Broken printer");
+    // The control needs a search term, so type one.
+    fireEvent.change(screen.getByRole("searchbox"), { target: { value: "printer" } });
+    const narrow = await screen.findByRole("button", { name: "Search everything" });
+    // The state is the label. Encoding it a second time in aria-pressed announces it twice
+    // and lets the two disagree, because both labels are caller-supplied.
+    expect(narrow).not.toHaveAttribute("aria-pressed");
+    fireEvent.click(narrow);
+    expect(onBroadenedChange).toHaveBeenCalledWith(true);
+
+    rerender(
+      <DataView
+        repository={scopedRepo()}
+        columns={COLUMNS}
+        searchScope={{
+          broadened: true,
+          onBroadenedChange,
+          label: "Search everything",
+          broadenedLabel: "Searching everything",
+        }}
+      />,
+    );
+    const broad = await screen.findByRole("button", { name: "Searching everything" });
+    expect(broad).not.toHaveAttribute("aria-pressed");
+    // And the attribute is now this component's alone on the two layout toggles, which is the
+    // enumeration the shared icon-button hover guard is safe by.
+    expect(document.querySelectorAll("[aria-pressed]")).toHaveLength(2);
+    for (const toggle of document.querySelectorAll("[aria-pressed]")) {
+      expect(toggle.getAttribute("data-terp")).toBe("iconbutton");
+    }
+  });
+});