@oprt/react 0.0.0-stage → 0.2.0

package/dist/BulkActionBar/BulkActionBar.js

@@ -0,0 +1,145 @@
+"use client";
+
+// src/BulkActionBar/BulkActionBar.tsx
+import { forwardRef, useId } from "react";
+import { cva } from "class-variance-authority";
+import clsx from "clsx";
+import { Button } from "../Button/Button.js";
+import { DescriptionList } from "../DescriptionList/DescriptionList.js";
+import { formatUtcTimestamp } from "../_internal/timestamp.js";
+import { useActionFocus } from "../_internal/useActionFocus.js";
+import { copySelection, idsError, scopeLabels, selectionError } from "./selection.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var barStyles = cva(
+  "flex min-w-0 flex-col gap-2u border border-oprt-border bg-oprt-surface-1 p-2u font-sans text-oprt-base text-oprt-text outline-hidden focus-visible:shadow-oprt-focus"
+);
+var BulkActionBar = forwardRef(
+  ({
+    label,
+    selection,
+    visibleIds,
+    actions,
+    onAction,
+    onClearSelection,
+    disabled = false,
+    headingLevel = 3,
+    className
+  }, ref) => {
+    const id = useId();
+    const focus = useActionFocus(ref);
+    const Heading = `h${headingLevel}`;
+    const invalidSelection = selectionError(selection);
+    const invalidVisible = idsError(visibleIds);
+    const invalidActions = idsError(actions.map((action) => action.id)) || (actions.some((action) => typeof action.label !== "string" || !action.label.trim()) ? "Action labels are required." : null);
+    const error = invalidSelection ? `Invalid selection: ${invalidSelection}` : invalidVisible ? `Invalid visible IDs: ${invalidVisible}` : invalidActions ? `Invalid actions: ${invalidActions}` : null;
+    const visible = new Set(visibleIds);
+    const outside = invalidSelection || invalidVisible ? 0 : selection.ids.filter((item) => !visible.has(item)).length;
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ...focus,
+        role: "region",
+        "aria-label": label,
+        tabIndex: -1,
+        className: clsx(barStyles(), className),
+        children: [
+          /* @__PURE__ */ jsx(Heading, { className: "m-0 min-w-0 oprt-wrap-anywhere text-oprt-base font-medium uppercase tracking-oprt-sm", children: label }),
+          error && /* @__PURE__ */ jsx("p", { className: "m-0 min-w-0 oprt-wrap-anywhere text-oprt-error", children: error }),
+          !invalidSelection && /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsxs("p", { className: "m-0 min-w-0 oprt-wrap-anywhere", children: [
+              selection.ids.length,
+              " equipment \xB7 ",
+              scopeLabels[selection.scope]
+            ] }),
+            !invalidVisible && /* @__PURE__ */ jsxs("p", { className: "m-0 min-w-0 oprt-wrap-anywhere text-oprt-text-dim", children: [
+              outside,
+              " selected ",
+              outside === 1 ? "ID" : "IDs",
+              " outside the visible page."
+            ] }),
+            /* @__PURE__ */ jsx(
+              DescriptionList,
+              {
+                layout: "details",
+                items: [
+                  {
+                    id: "source",
+                    label: "Source",
+                    value: `${selection.sourceId} \xB7 ${selection.sourceRevision}`,
+                    mono: true
+                  },
+                  {
+                    id: "filters",
+                    label: "Filters",
+                    value: selection.filterDescription || "No filters"
+                  },
+                  {
+                    // DC-4: the capture time in UTC to the second; the exact instant stays in dateTime.
+                    id: "captured",
+                    label: "Captured",
+                    value: /* @__PURE__ */ jsx("time", { dateTime: new Date(selection.capturedAt).toISOString(), children: formatUtcTimestamp(selection.capturedAt) }),
+                    mono: true
+                  }
+                ]
+              }
+            )
+          ] }),
+          /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-start gap-2u", children: [
+            actions.map((action, index) => {
+              const reason = action.disabled && action.disabledReason ? action.disabledReason : null;
+              return /* @__PURE__ */ jsxs(
+                "div",
+                {
+                  className: "flex min-w-0 flex-col gap-1u",
+                  children: [
+                    /* @__PURE__ */ jsx(
+                      Button,
+                      {
+                        className: "max-w-full oprt-wrap-anywhere",
+                        size: "sm",
+                        variant: action.danger ? "danger" : "secondary",
+                        disabled: disabled || !!error || selection.ids.length === 0 || action.disabled,
+                        "aria-describedby": reason ? `${id}-reason-${index}` : void 0,
+                        onClick: () => {
+                          if (!disabled && !error && selection.ids.length > 0 && !action.disabled)
+                            onAction(action.id, copySelection(selection));
+                        },
+                        children: action.label
+                      }
+                    ),
+                    reason && /* @__PURE__ */ jsx(
+                      "p",
+                      {
+                        id: `${id}-reason-${index}`,
+                        className: "m-0 min-w-0 oprt-wrap-anywhere text-oprt-text-dim",
+                        children: reason
+                      }
+                    )
+                  ]
+                },
+                invalidActions ? index : action.id
+              );
+            }),
+            onClearSelection && /* @__PURE__ */ jsx(
+              Button,
+              {
+                className: "max-w-full oprt-wrap-anywhere",
+                size: "sm",
+                variant: "tertiary",
+                disabled,
+                onClick: () => {
+                  if (!disabled) onClearSelection();
+                },
+                children: "Clear selection"
+              }
+            )
+          ] })
+        ]
+      }
+    );
+  }
+);
+BulkActionBar.displayName = "BulkActionBar";
+export {
+  BulkActionBar
+};

package/dist/BulkActionBar/BulkActionBar.manifest.js

@@ -0,0 +1,46 @@
+// src/BulkActionBar/BulkActionBar.manifest.ts
+var BulkActionBarManifest = {
+  BulkActionBar: {
+    description: "Displays an explicit equipment selection snapshot, off-page count, source and filter context, with controlled bulk action requests.",
+    props: {
+      label: { type: "string", required: true },
+      selection: {
+        type: "node",
+        required: true,
+        description: "BulkSelectionSnapshot: {id,scope:'visible'|'selected'|'all-matching',ids:readonly string[],sourceId,sourceRevision,filterDescription,capturedAt:number}. IDs must be unique and nonempty. The application resolves all matching IDs before supplying them."
+      },
+      visibleIds: {
+        type: "array",
+        required: true,
+        description: "Unique current visible-page IDs, used to explain retained selection outside that page."
+      },
+      actions: {
+        type: "array",
+        required: true,
+        description: "BulkAction[]: unique id, label, optional disabled, disabledReason and danger. A disabledReason shows under its action, as the action's description, only while the action is disabled."
+      },
+      onAction: {
+        type: "function",
+        required: true,
+        description: "(actionId, snapshot) => void. Receives an independent frozen copy, including its frozen IDs. Confirmation and authority checks belong to the application."
+      },
+      onClearSelection: {
+        type: "function",
+        description: "Requests clearing selection without changing it locally. Available to recover from malformed snapshots."
+      },
+      disabled: { type: "boolean", default: false },
+      headingLevel: {
+        type: "number",
+        default: 3,
+        description: "Label heading level: 2, 3, 4, 5, or 6. Choose it for the hosting surface's heading hierarchy."
+      },
+      className: { type: "string" }
+    },
+    composable_with: ["DataGrid", "ConfirmDialog", "BulkResults", "JobStatus", "DescriptionList"],
+    never_inside: ["Button"],
+    example: '<BulkActionBar label="Equipment actions" selection={snapshot} visibleIds={pageIds} actions={[{id:"flag",label:"Flag for inspection"}]} onAction={reviewAction} />'
+  }
+};
+export {
+  BulkActionBarManifest
+};

package/dist/BulkActionBar/index.js

@@ -0,0 +1,9 @@
+// src/BulkActionBar/index.ts
+import {
+  BulkActionBar
+} from "./BulkActionBar.js";
+import { BulkActionBarManifest } from "./BulkActionBar.manifest.js";
+export {
+  BulkActionBar,
+  BulkActionBarManifest
+};

package/dist/BulkActionBar/selection.js

@@ -0,0 +1,44 @@
+// src/BulkActionBar/selection.ts
+import { isValidTimestamp } from "../_internal/timestamp.js";
+function idsError(ids) {
+  if (!Array.isArray(ids) || ids.some((id) => typeof id !== "string" || !id.trim()))
+    return "IDs must be nonempty strings.";
+  if (new Set(ids).size !== ids.length) return "IDs must be unique.";
+  return null;
+}
+function selectionError(selection) {
+  if (!selection || !["visible", "selected", "all-matching"].includes(selection.scope))
+    return "Invalid selection scope.";
+  const invalidIds = idsError(selection.ids);
+  if (invalidIds) return invalidIds;
+  if ([selection.id, selection.sourceId, selection.sourceRevision].some(
+    (value) => typeof value !== "string" || !value.trim()
+  ))
+    return "A snapshot ID, source ID, and source revision are required.";
+  if (typeof selection.filterDescription !== "string") return "A filter description is required.";
+  if (!isValidTimestamp(selection.capturedAt, { integer: true }))
+    return "Snapshot capture time must be valid epoch milliseconds.";
+  return null;
+}
+var scopeLabels = {
+  visible: "Visible rows",
+  selected: "Selected IDs",
+  "all-matching": "All matching results"
+};
+function copySelection(selection) {
+  return Object.freeze({
+    id: selection.id,
+    scope: selection.scope,
+    ids: Object.freeze([...selection.ids]),
+    sourceId: selection.sourceId,
+    sourceRevision: selection.sourceRevision,
+    filterDescription: selection.filterDescription,
+    capturedAt: selection.capturedAt
+  });
+}
+export {
+  copySelection,
+  idsError,
+  scopeLabels,
+  selectionError
+};

package/dist/BulkResults/BulkResults.js

@@ -0,0 +1,269 @@
+"use client";
+
+// src/BulkResults/BulkResults.tsx
+import { forwardRef, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
+import { cva } from "class-variance-authority";
+import clsx from "clsx";
+import { Badge } from "../Badge/Badge.js";
+import { Button } from "../Button/Button.js";
+import { DescriptionList } from "../DescriptionList/DescriptionList.js";
+import { idsError, scopeLabels, selectionError } from "../BulkActionBar/selection.js";
+import { PageControls } from "../DataGrid/PageControls.js";
+import { useScrollsSideways } from "../DataTable/useScrollsSideways.js";
+import { useIsomorphicLayoutEffect } from "../_internal/useIsomorphicLayoutEffect.js";
+import { useRestoreFocusOnRemoval } from "../_internal/useRestoreFocusOnRemoval.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var resultStyles = cva(
+  "flex min-w-0 flex-col gap-2u font-sans text-oprt-base text-oprt-text outline-hidden focus-visible:shadow-oprt-focus"
+);
+var variants = {
+  queued: "info",
+  running: "info",
+  succeeded: "success",
+  failed: "error",
+  canceled: "neutral",
+  skipped: "neutral"
+};
+var NO_IDS = [];
+var DEFAULT_PAGE_SIZE = 100;
+var COLUMNS = [
+  { heading: "Equipment", width: "min-w-16u" },
+  { heading: "Outcome", width: "min-w-12u" },
+  { heading: "Details", width: "min-w-16u" },
+  { heading: "Actions", width: "" }
+];
+var BulkResults = forwardRef(
+  ({
+    label,
+    selection,
+    items,
+    pendingRetryIds = NO_IDS,
+    onRetryRequest,
+    disabled = false,
+    pageSize = DEFAULT_PAGE_SIZE,
+    headingLevel = 3,
+    className
+  }, ref) => {
+    const Heading = `h${headingLevel}`;
+    const root = useRef(null);
+    useImperativeHandle(ref, () => root.current, []);
+    const [box, scrolls] = useScrollsSideways();
+    const rows = useRef(/* @__PURE__ */ new Map());
+    const invalidSelection = selectionError(selection);
+    const selected = new Set(invalidSelection ? [] : selection.ids);
+    const invalidResults = idsError(items.map((item) => item.id)) || (items.some((item) => !selected.has(item.id)) ? "A result ID is outside the selection snapshot." : null) || (items.some(
+      (item) => !Object.hasOwn(variants, item.state) || typeof item.label !== "string" || !item.label.trim() || item.message !== void 0 && typeof item.message !== "string"
+    ) ? "Every result needs a valid state, label, and message." : null);
+    const invalidRetries = idsError(pendingRetryIds) || (pendingRetryIds.some((item) => !selected.has(item)) ? "A pending retry ID is outside the selection snapshot." : null);
+    const resultMap = new Map((invalidResults ? [] : items).map((item) => [item.id, item]));
+    const pending = useMemo(() => new Set(pendingRetryIds), [pendingRetryIds]);
+    const missing = invalidSelection ? 0 : selection.ids.filter((item) => !resultMap.has(item)).length;
+    const succeeded = invalidResults ? 0 : items.filter((item) => item.state === "succeeded").length;
+    const ids = invalidSelection ? NO_IDS : selection.ids;
+    const size = Number.isFinite(pageSize) && pageSize >= 1 ? Math.floor(pageSize) : DEFAULT_PAGE_SIZE;
+    const pageCount = Math.max(1, Math.ceil(ids.length / size));
+    const [paging, setPaging] = useState({ snapshot: selection.id, page: 1 });
+    const requestedPage = paging.snapshot === selection.id ? paging.page : 1;
+    const page = Math.min(pageCount, Math.max(1, requestedPage));
+    const pageIds = ids.length > size ? ids.slice((page - 1) * size, page * size) : ids;
+    const restoreFocus = useRestoreFocusOnRemoval(root, {
+      track: (element) => {
+        for (const [itemId, row] of rows.current)
+          if (row.contains(element)) return { itemId, index: pageIds.indexOf(itemId) };
+        return { itemId: null, index: -1 };
+      },
+      findTarget: ({ itemId, index }) => {
+        const own = itemId === null ? void 0 : rows.current.get(itemId);
+        if (own) return own.querySelector("th");
+        const nextId = index >= 0 ? pageIds[Math.min(index, pageIds.length - 1)] : void 0;
+        const next = nextId === void 0 ? void 0 : rows.current.get(nextId);
+        return next?.querySelector("button:not(:disabled)") ?? next?.querySelector("th") ?? root.current;
+      }
+    });
+    const [spoken, setSpoken] = useState("");
+    const announced = useRef(new Set(invalidRetries ? [] : pendingRetryIds));
+    const latest = useRef({ results: resultMap, pending: pendingRetryIds });
+    useIsomorphicLayoutEffect(() => {
+      latest.current = { results: resultMap, pending: pendingRetryIds };
+    });
+    const pendingKey = JSON.stringify(pendingRetryIds);
+    useEffect(() => {
+      const current = invalidRetries ? [] : latest.current.pending;
+      for (const itemId of [...announced.current])
+        if (!current.includes(itemId)) announced.current.delete(itemId);
+      const added = current.filter((itemId) => !announced.current.has(itemId));
+      const label2 = (itemId) => latest.current.results.get(itemId)?.label ?? itemId;
+      const text = added.length === 0 ? "" : added.length === 1 ? `Retry request pending for ${label2(added[0])}. Awaiting an application update.` : `Retry requests pending for ${added.length} items. Awaiting an application update.`;
+      let second = 0;
+      const first = requestAnimationFrame(() => {
+        setSpoken("");
+        second = requestAnimationFrame(() => {
+          setSpoken(text);
+          for (const itemId of added) announced.current.add(itemId);
+        });
+      });
+      return () => {
+        cancelAnimationFrame(first);
+        cancelAnimationFrame(second);
+      };
+    }, [pendingKey, invalidRetries]);
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref: root,
+        role: "region",
+        "aria-label": label,
+        tabIndex: -1,
+        className: clsx(resultStyles(), className),
+        onFocusCapture: restoreFocus.onFocusCapture,
+        onBlurCapture: restoreFocus.onBlurCapture,
+        children: [
+          /* @__PURE__ */ jsx(Heading, { className: "m-0 min-w-0 oprt-wrap-anywhere text-oprt-base font-medium uppercase tracking-oprt-sm", children: label }),
+          /* @__PURE__ */ jsx("p", { "aria-live": "polite", "aria-atomic": "true", className: "sr-only m-0", children: spoken }),
+          invalidSelection ? /* @__PURE__ */ jsxs("p", { className: "m-0 min-w-0 oprt-wrap-anywhere text-oprt-error", children: [
+            "Invalid selection: ",
+            invalidSelection
+          ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsxs("p", { className: "m-0 min-w-0 oprt-wrap-anywhere", children: [
+              scopeLabels[selection.scope],
+              " \xB7 ",
+              selection.ids.length,
+              " requested \xB7 ",
+              succeeded,
+              " ",
+              "succeeded \xB7 ",
+              missing,
+              " not reported"
+            ] }),
+            /* @__PURE__ */ jsx(
+              DescriptionList,
+              {
+                layout: "details",
+                items: [
+                  {
+                    id: "source",
+                    label: "Source",
+                    value: `${selection.sourceId} \xB7 ${selection.sourceRevision}`,
+                    mono: true
+                  },
+                  {
+                    id: "filters",
+                    label: "Filters",
+                    value: selection.filterDescription || "No filters"
+                  }
+                ]
+              }
+            ),
+            invalidResults && /* @__PURE__ */ jsxs("p", { className: "m-0 min-w-0 oprt-wrap-anywhere text-oprt-error", children: [
+              "Invalid results: ",
+              invalidResults,
+              " Outcomes are withheld until corrected."
+            ] }),
+            invalidRetries && /* @__PURE__ */ jsxs("p", { className: "m-0 min-w-0 oprt-wrap-anywhere text-oprt-error", children: [
+              "Invalid retry requests: ",
+              invalidRetries
+            ] }),
+            selection.ids.length === 0 ? /* @__PURE__ */ jsx("p", { className: "m-0", children: "No equipment was requested." }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+              /* @__PURE__ */ jsx(
+                "div",
+                {
+                  ref: box,
+                  className: clsx(
+                    "min-w-0 max-w-full overflow-x-auto",
+                    scrolls && "border border-transparent focus-visible:outline-hidden focus-visible:border-oprt-border-focus focus-visible:shadow-oprt-focus"
+                  ),
+                  ...scrolls ? { role: "region", "aria-label": `${label} scroll viewport`, tabIndex: 0 } : {},
+                  children: /* @__PURE__ */ jsxs("table", { "aria-label": label, className: "m-0 w-full border-collapse", children: [
+                    /* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsx("tr", { children: COLUMNS.map(({ heading, width }) => /* @__PURE__ */ jsx(
+                      "th",
+                      {
+                        scope: "col",
+                        className: clsx(
+                          "border-b border-oprt-border px-1u py-2u text-left font-medium uppercase tracking-oprt-sm",
+                          width
+                        ),
+                        children: heading
+                      },
+                      heading
+                    )) }) }),
+                    /* @__PURE__ */ jsx("tbody", { children: pageIds.map((itemId) => {
+                      const item = resultMap.get(itemId);
+                      const isPending = pending.has(itemId);
+                      const retryable = !invalidResults && !invalidRetries && item?.state === "failed" && item.retryable === true && !!onRetryRequest;
+                      return /* @__PURE__ */ jsxs(
+                        "tr",
+                        {
+                          ref: (node) => {
+                            if (node) rows.current.set(itemId, node);
+                            else rows.current.delete(itemId);
+                          },
+                          className: "border-b border-oprt-border",
+                          children: [
+                            /* @__PURE__ */ jsxs(
+                              "th",
+                              {
+                                scope: "row",
+                                tabIndex: -1,
+                                className: "min-w-0 px-1u py-2u text-left align-top font-medium oprt-wrap-anywhere outline-hidden focus-visible:shadow-oprt-focus",
+                                children: [
+                                  item?.label ?? itemId,
+                                  item && /* @__PURE__ */ jsx("span", { className: "block oprt-wrap-anywhere font-mono text-oprt-text-dim", children: itemId })
+                                ]
+                              }
+                            ),
+                            /* @__PURE__ */ jsx("td", { className: "px-1u py-2u align-top", children: /* @__PURE__ */ jsx(
+                              Badge,
+                              {
+                                appearance: "text",
+                                indicator: "none",
+                                variant: item ? variants[item.state] : "neutral",
+                                children: item?.state ?? "Not reported"
+                              }
+                            ) }),
+                            /* @__PURE__ */ jsxs("td", { className: "min-w-0 px-1u py-2u align-top oprt-wrap-anywhere", children: [
+                              item?.message ?? "\u2014",
+                              isPending && /* @__PURE__ */ jsx("p", { className: "m-0", children: "Retry requested; awaiting an application update." })
+                            ] }),
+                            /* @__PURE__ */ jsx("td", { className: "px-1u py-2u align-top", children: retryable && /* @__PURE__ */ jsx(
+                              Button,
+                              {
+                                size: "sm",
+                                variant: "secondary",
+                                className: "max-w-full",
+                                "aria-label": `Retry ${item.label}`,
+                                disabled: disabled || isPending,
+                                onClick: () => {
+                                  if (!disabled && !isPending && retryable)
+                                    onRetryRequest?.(itemId);
+                                },
+                                children: "Retry"
+                              }
+                            ) })
+                          ]
+                        },
+                        itemId
+                      );
+                    }) })
+                  ] })
+                }
+              ),
+              ids.length > size && /* @__PURE__ */ jsx(
+                PageControls,
+                {
+                  page,
+                  pageCount,
+                  disabled: false,
+                  onPageChange: (next) => setPaging({ snapshot: selection.id, page: next })
+                }
+              )
+            ] })
+          ] })
+        ]
+      }
+    );
+  }
+);
+BulkResults.displayName = "BulkResults";
+export {
+  BulkResults
+};

package/dist/BulkResults/BulkResults.manifest.js

@@ -0,0 +1,45 @@
+// src/BulkResults/BulkResults.manifest.ts
+var BulkResultsManifest = {
+  BulkResults: {
+    description: "Named per-equipment result table in selection order. Missing IDs remain Not reported; malformed result coverage is visible and never counted as success.",
+    props: {
+      label: { type: "string", required: true },
+      selection: {
+        type: "node",
+        required: true,
+        description: "BulkSelectionSnapshot for the exact original request. IDs must be unique and nonempty."
+      },
+      items: {
+        type: "array",
+        required: true,
+        description: "BulkItemResult[]: {id,label,state:'queued'|'running'|'succeeded'|'failed'|'canceled'|'skipped',message?,retryable?}. Only snapshot IDs are accepted, once each."
+      },
+      pendingRetryIds: {
+        type: "array",
+        description: "Known unique IDs with a supplied pending retry request. Their actions remain disabled and previous results remain visible."
+      },
+      onRetryRequest: {
+        type: "function",
+        description: "(id) => void. Offered only for explicitly retryable failed items. Calling it does not change supplied outcomes."
+      },
+      disabled: { type: "boolean", default: false },
+      pageSize: {
+        type: "number",
+        default: 100,
+        description: "Rows per page. A request with more IDs than this is shown a page at a time, in selection order, with PREVIOUS PAGE and NEXT PAGE; the summary still counts every ID. Invalid or less-than-one values use 100; fractional values round down."
+      },
+      headingLevel: {
+        type: "number",
+        default: 3,
+        description: "Label heading level: 2, 3, 4, 5, or 6. Choose it for the hosting surface's heading hierarchy."
+      },
+      className: { type: "string" }
+    },
+    composable_with: ["JobStatus", "BulkActionBar", "Badge", "Button", "DescriptionList"],
+    never_inside: ["Button"],
+    example: '<BulkResults label="Inspection results" selection={snapshot} items={results} pendingRetryIds={pendingIds} onRetryRequest={reviewRetry} />'
+  }
+};
+export {
+  BulkResultsManifest
+};

package/dist/BulkResults/index.js

@@ -0,0 +1,7 @@
+// src/BulkResults/index.ts
+import { BulkResults } from "./BulkResults.js";
+import { BulkResultsManifest } from "./BulkResults.manifest.js";
+export {
+  BulkResults,
+  BulkResultsManifest
+};