@oprt/react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OPERATOR contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# @oprt/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React components for operational interfaces: command, control and industrial software. Part of
+the [OPERATOR design system](https://oprt.dev).
+
+75 component families, from Button and DataGrid to OperationalStatus, Inspector and MapControls,
+with interactive behavior from React Aria. Every component is dark, square-cornered and keyboard
+operable, and spells its status out instead of relying on color alone, so dense, fast-changing
+screens stay readable.
+
+## Install
+
+```sh
+pnpm add @oprt/react @oprt/tokens
+pnpm add -D @oprt/tailwind tailwindcss@^4.3.3
+```
+
+React 18 or later and React DOM are peer dependencies. The components are styled with Tailwind
+CSS 4 and the OPERATOR plugin. Set Tailwind up the way your framework does, then add the plugin
+and the components to the stylesheet where Tailwind is imported:
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@plugin "@oprt/tailwind";
+/* The components ship as compiled JavaScript, which Tailwind does not scan on its own. The path is
+   relative to this file; without it the components render unstyled. */
+@source "../node_modules/@oprt/react/dist";
+```
+
+Import the tokens once at the application root, before that stylesheet:
+
+```ts
+import "@oprt/tokens";
+import "./globals.css";
+```
+
+Load the tokens from JavaScript or a `<link>`, not with an `@import` inside the Tailwind
+stylesheet: the Tailwind CLI inlines an imported file without rewriting its font URLs, and the
+bundled fonts would not load. Inside Tailwind Typography's `prose`, wrap components in an element
+with the `not-prose` class.
+
+## Use
+
+```tsx
+import { Badge, Button, Field, Input } from "@oprt/react";
+
+export function Handover() {
+  return (
+    <form>
+      <Field label="Callsign" required>
+        <Input placeholder="RAVEN 2" />
+      </Field>
+      <Badge variant="warning">Stale</Badge>
+      <Button type="submit">Acknowledge</Button>
+    </form>
+  );
+}
+```
+
+Every component's page at [oprt.dev/docs/components](https://oprt.dev/docs/components) shows its
+variants live, with its props, its accessibility behavior and its manifest entry. Six complete
+working screens are at [oprt.dev](https://oprt.dev).
+
+## What's included
+
+- **Actions and inputs:** Button, ButtonGroup, CopyButton, Field, Input, Textarea, NumberInput,
+  CoordinateInput, Checkbox, RadioGroup, Toggle, Slider, Select, ComboBox, MultiSelect, TagGroup,
+  InlineEdit, FormSection, FormErrorSummary
+- **Dates and times:** Calendar, DatePicker, DateRangePicker, DateTimePicker, TimeField, TimeRange
+- **Data:** DataTable, DataGrid, Chart, Sparkline, StatCard, EventTimeline, DescriptionList,
+  FilterBar, PropertyFilter
+- **Status and feedback:** Badge, Alert, Toast, Progress, Skeleton, OperationalStatus,
+  ActionStatus, JobStatus, CollectionState
+- **Bulk work and files:** BulkActionBar, BulkResults, FileUpload, UploadQueue, AttachmentPreview
+- **Layout and navigation:** AppShell, Sidebar, SplitPane, Tabs, Breadcrumb, Toolbar, Collapsible,
+  TreeView, Card, Divider, Link, Avatar
+- **Overlays and inspection:** Dialog, ConfirmDialog, Popover, Tooltip, DropdownMenu, ContextMenu,
+  CommandPalette, Inspector, EntityPreview
+- **Maps and media:** MapControls, LayerControl, MapLegend, MapScale, MediaFrame, PlaybackControls
+
+Motion is tactile and quick. Turn it off for one component with `motion="none"`; the system's
+reduced-motion setting turns it off everywhere.
+
+## Server Components and bundle size
+
+Each module is its own file, and only the modules that need the browser are marked
+`"use client"`. An app pays only for what it imports, and a Server Component can import the
+manifest entries and data helpers from the package root. ES modules and CommonJS are both
+included.
+
+## For coding agents
+
+Each family exports its manifest entry (`ButtonManifest`, `DataGridManifest` and so on). In
+development, an invalid option value logs a structured `INVALID_PROP_VALUE` error with the valid
+values and a suggestion; production builds leave it out. For the whole contract, give an agent
+[`@oprt/manifest`](https://www.npmjs.com/package/@oprt/manifest)'s `components.json`,
+or use [`@oprt/cli`](https://www.npmjs.com/package/@oprt/cli) to write the agent's
+instructions and check its code. See [oprt.dev/docs/agents](https://oprt.dev/docs/agents).
+
+To own the code instead of installing it, the CLI copies any component, with everything it
+depends on, into your project: `npx @oprt/cli add button`.
+
+## License
+
+MIT. The OPERATOR fonts in `@oprt/tokens` are under the SIL Open Font License 1.1.

package/dist/ActionStatus/ActionStatus.js

@@ -0,0 +1,104 @@
+"use client";
+
+// src/ActionStatus/ActionStatus.tsx
+import { forwardRef } 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 { useActionFocus } from "../_internal/useActionFocus.js";
+import { devValidate } from "../_internal/devValidate.js";
+import { ActionStatusManifest } from "./ActionStatus.manifest.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var statusStyles = cva(
+  "flex min-w-0 flex-col gap-2u border border-oprt-border p-2u font-sans text-oprt-base normal-case text-oprt-text outline-hidden focus-visible:shadow-oprt-focus"
+);
+var variants = {
+  submitted: "info",
+  accepted: "info",
+  rejected: "error",
+  "in-progress": "info",
+  complete: "success",
+  partial: "warning",
+  failed: "error",
+  timeout: "warning",
+  queued: "info",
+  running: "info",
+  "cancel-requested": "info",
+  canceled: "neutral"
+};
+function ActionStatusLine({
+  state,
+  label,
+  message,
+  requestId,
+  children
+}) {
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      role: "status",
+      "aria-live": "polite",
+      "aria-atomic": "true",
+      className: "flex min-w-0 flex-col gap-1u",
+      children: [
+        /* @__PURE__ */ jsx("span", { className: "min-w-0 oprt-wrap-anywhere font-medium uppercase tracking-oprt-caps", children: label }),
+        /* @__PURE__ */ jsx("div", { children: /* @__PURE__ */ jsx(Badge, { variant: variants[state], indicator: "dot", children: state }) }),
+        requestId && /* @__PURE__ */ jsxs("span", { className: "min-w-0 oprt-wrap-anywhere font-mono", children: [
+          "Request: ",
+          requestId
+        ] }),
+        message && /* @__PURE__ */ jsx("p", { className: "m-0 min-w-0 oprt-wrap-anywhere", children: message }),
+        children
+      ]
+    }
+  );
+}
+var ActionStatus = forwardRef((allProps, ref) => {
+  const {
+    state,
+    label,
+    message,
+    requestId,
+    onRetry,
+    onCancel,
+    retryLabel = "Retry",
+    cancelLabel = "Cancel",
+    disabled = false,
+    className,
+    onFocusCapture,
+    onBlurCapture,
+    ...props
+  } = allProps;
+  const focus = useActionFocus(ref, { onFocusCapture, onBlurCapture });
+  if (process.env.NODE_ENV !== "production") {
+    devValidate("ActionStatus", ActionStatusManifest.ActionStatus.props, { ...allProps });
+  }
+  return (
+    // The result is a group named by its label, so the place focus moves to is announced by name,
+    // as JobStatus's region is. A role or name the caller gives wins.
+    /* @__PURE__ */ jsxs(
+      "div",
+      {
+        tabIndex: -1,
+        role: "group",
+        "aria-label": label,
+        ...props,
+        ...focus,
+        className: clsx(statusStyles(), className),
+        children: [
+          /* @__PURE__ */ jsx(ActionStatusLine, { state, label, message, requestId }),
+          (onRetry || onCancel) && /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap gap-1u", children: [
+            onRetry && /* @__PURE__ */ jsx(Button, { variant: "secondary", size: "sm", disabled, onClick: onRetry, children: retryLabel }),
+            onCancel && /* @__PURE__ */ jsx(Button, { variant: "tertiary", size: "sm", disabled, onClick: onCancel, children: cancelLabel })
+          ] })
+        ]
+      }
+    )
+  );
+});
+ActionStatus.displayName = "ActionStatus";
+export {
+  ActionStatus,
+  ActionStatusLine
+};

package/dist/ActionStatus/ActionStatus.manifest.js

@@ -0,0 +1,64 @@
+// src/ActionStatus/ActionStatus.manifest.ts
+var ActionStatusManifest = {
+  ActionStatus: {
+    description: "Stateless authoritative action outcome display with optional application-supported recovery callbacks. When the focused recovery is withdrawn or disabled, focus moves to the result, a group named by its label. Long text wraps.",
+    props: {
+      state: {
+        type: "enum",
+        values: [
+          "submitted",
+          "accepted",
+          "rejected",
+          "in-progress",
+          "complete",
+          "partial",
+          "failed",
+          "timeout",
+          "queued",
+          "running",
+          "cancel-requested",
+          "canceled"
+        ],
+        required: true,
+        description: "Authoritative application-supplied lifecycle state. Timeout does not imply rejection or completion. A cancel request does not establish cancellation; a supplied complete result can still follow cancel-requested."
+      },
+      label: {
+        type: "string",
+        required: true
+      },
+      message: {
+        type: "string"
+      },
+      requestId: {
+        type: "string"
+      },
+      onRetry: {
+        type: "function",
+        description: "Render Retry only when retry is supported. Does not change state."
+      },
+      onCancel: {
+        type: "function",
+        description: "Render Cancel only when cancellation is supported. Does not change state."
+      },
+      retryLabel: {
+        type: "string",
+        default: "Retry"
+      },
+      cancelLabel: {
+        type: "string",
+        default: "Cancel"
+      },
+      disabled: {
+        type: "boolean",
+        default: false,
+        description: "Disables recovery actions without hiding supplied outcomes."
+      }
+    },
+    composable_with: ["Inspector", "Alert", "AppShell"],
+    never_inside: ["Button"],
+    example: '<ActionStatus state={result.state} label="Refresh source" message={result.message} requestId={result.id} onRetry={canRetry ? retry : undefined} />'
+  }
+};
+export {
+  ActionStatusManifest
+};

package/dist/ActionStatus/index.js

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

package/dist/Alert/Alert.js

@@ -0,0 +1,86 @@
+"use client";
+
+// src/Alert/Alert.tsx
+import { Info, CheckCircle, AlertTriangle, XCircle, X } from "@oprt/icons";
+import { cva } from "class-variance-authority";
+import { forwardRef } from "react";
+import clsx from "clsx";
+import { AlertManifest } from "./Alert.manifest.js";
+import { devValidate } from "../_internal/devValidate.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var ICONS = {
+  info: Info,
+  success: CheckCircle,
+  warning: AlertTriangle,
+  error: XCircle
+};
+var containerStyles = cva(
+  "flex gap-2u px-3u py-2u bg-oprt-surface-1 border border-oprt-border border-l-2 font-sans",
+  {
+    variants: {
+      variant: {
+        info: "border-l-oprt-info",
+        success: "border-l-oprt-success",
+        warning: "border-l-oprt-warning",
+        error: "border-l-oprt-error"
+      }
+    }
+  }
+);
+var accentStyles = cva("", {
+  variants: {
+    variant: {
+      info: "text-oprt-info",
+      success: "text-oprt-success",
+      warning: "text-oprt-warning",
+      error: "text-oprt-error"
+    }
+  }
+});
+var Alert = forwardRef((allProps, ref) => {
+  const {
+    className,
+    variant,
+    title,
+    dismissible = false,
+    onDismiss,
+    children,
+    ...props
+  } = allProps;
+  const role = variant === "error" || variant === "warning" ? "alert" : "status";
+  const Icon = ICONS[variant];
+  const hasBody = children != null && typeof children !== "boolean" && children !== "";
+  if (process.env.NODE_ENV !== "production") {
+    devValidate("Alert", AlertManifest.Alert.props, allProps);
+  }
+  return /* @__PURE__ */ jsxs("div", { ref, role, className: clsx(containerStyles({ variant }), className), ...props, children: [
+    /* @__PURE__ */ jsx("span", { "aria-hidden": "true", className: clsx("shrink-0", accentStyles({ variant })), children: /* @__PURE__ */ jsx(Icon, { size: 16 }) }),
+    /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-1u oprt-wrap-anywhere", children: [
+      title && /* @__PURE__ */ jsx(
+        "p",
+        {
+          className: clsx(
+            "m-0 text-oprt-sm uppercase tracking-oprt-sm",
+            accentStyles({ variant })
+          ),
+          children: title
+        }
+      ),
+      hasBody && /* @__PURE__ */ jsx("div", { className: "text-oprt-base normal-case text-oprt-text", children })
+    ] }),
+    dismissible && /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        "aria-label": "Dismiss",
+        onClick: onDismiss,
+        className: "inline-flex items-center justify-center shrink-0 h-oprt-sm w-3u border border-transparent text-oprt-text-dim transition-colors duration-oprt-fast hover:text-oprt-text focus-visible:border-oprt-border-focus focus-visible:shadow-oprt-focus focus-visible:outline-hidden",
+        children: /* @__PURE__ */ jsx(X, { size: 12 })
+      }
+    )
+  ] });
+});
+Alert.displayName = "Alert";
+export {
+  Alert
+};

package/dist/Alert/Alert.manifest.js

@@ -0,0 +1,36 @@
+// src/Alert/Alert.manifest.ts
+var AlertManifest = {
+  Alert: {
+    description: "Inline status message with a severity icon, semantic left-edge accent, optional title, and optional dismiss control.",
+    props: {
+      variant: {
+        type: "enum",
+        values: ["info", "success", "warning", "error"],
+        required: true,
+        description: "Severity. Drives icon, accent color, and ARIA role (error/warning = alert, info/success = status)."
+      },
+      title: {
+        type: "string",
+        description: "Optional uppercase heading shown above the description."
+      },
+      dismissible: {
+        type: "boolean",
+        default: false,
+        description: "Render a trailing Dismiss button that calls onDismiss."
+      },
+      onDismiss: {
+        type: "function",
+        description: "Called when the Dismiss button is activated."
+      }
+    },
+    slots: {
+      children: { type: "any", required: false }
+    },
+    composable_with: ["Card", "CardBody"],
+    never_inside: ["Alert", "Button", "Badge"],
+    example: '<Alert variant="error" title="LINK LOST">Telemetry stream dropped.</Alert>'
+  }
+};
+export {
+  AlertManifest
+};

package/dist/Alert/index.js

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

package/dist/AppShell/AppShell.js

@@ -0,0 +1,103 @@
+"use client";
+
+// src/AppShell/AppShell.tsx
+import { forwardRef, useId } from "react";
+import { cva } from "class-variance-authority";
+import clsx from "clsx";
+import { Badge } from "../Badge/Badge.js";
+import { devValidate } from "../_internal/devValidate.js";
+import { InsideNavigationLandmarkProvider } from "../_internal/navigationLandmark.js";
+import { formatUtcTimestamp, isValidTimestamp } from "../_internal/timestamp.js";
+import { AppShellManifest } from "./AppShell.manifest.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var shellStyles = cva(
+  "@container flex w-full min-w-0 flex-col border border-oprt-border bg-oprt-surface-1 font-sans text-oprt-base normal-case text-oprt-text"
+);
+var connectionVariants = {
+  connected: "success",
+  connecting: "warning",
+  reconnecting: "warning",
+  offline: "warning",
+  unknown: "neutral"
+};
+function connectionVariant(connection) {
+  return Object.prototype.hasOwnProperty.call(connectionVariants, connection) ? connectionVariants[connection] : "neutral";
+}
+var AppShell = forwardRef(
+  ({
+    title = "Workspace",
+    identity,
+    mode = "live",
+    connection = "unknown",
+    time,
+    markings,
+    navigation,
+    toolbar,
+    footer,
+    children,
+    className,
+    ...props
+  }, ref) => {
+    const id = useId();
+    if (process.env.NODE_ENV !== "production") {
+      devValidate("AppShell", AppShellManifest.AppShell.props, { mode, connection });
+    }
+    const shown = isValidTimestamp(time) ? formatUtcTimestamp(time) : null;
+    const isoTime = isValidTimestamp(time) ? new Date(time).toISOString() : null;
+    const split = shown?.indexOf(" ") ?? -1;
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ...props,
+        ref,
+        role: "region",
+        "aria-labelledby": id,
+        className: clsx(shellStyles(), className),
+        children: [
+          markings && /* @__PURE__ */ jsx("div", { className: "border-b border-oprt-border bg-oprt-surface-2 px-2u py-1u text-center font-medium uppercase tracking-oprt-caps oprt-wrap-anywhere", children: markings }),
+          /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-center justify-between gap-2u border-b border-oprt-border p-2u", children: [
+            /* @__PURE__ */ jsx(
+              "h2",
+              {
+                id,
+                className: "m-0 min-w-0 text-oprt-md font-medium uppercase tracking-oprt-caps oprt-wrap-anywhere",
+                children: title
+              }
+            ),
+            /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-2u", children: [
+              /* @__PURE__ */ jsx("span", { className: "min-w-0 normal-case oprt-wrap-anywhere", children: identity }),
+              /* @__PURE__ */ jsx(Badge, { variant: mode === "live" ? "info" : "neutral", indicator: "dot", children: mode }),
+              /* @__PURE__ */ jsx(Badge, { variant: connectionVariant(connection), indicator: "dot", children: connection }),
+              isoTime && shown ? (
+                // The date and the time wrap apart; neither breaks inside, so "UTC" stays with the
+                // time.
+                /* @__PURE__ */ jsxs("time", { className: "font-mono", dateTime: isoTime, children: [
+                  /* @__PURE__ */ jsx("span", { className: "whitespace-nowrap", children: shown.slice(0, split) }),
+                  " ",
+                  /* @__PURE__ */ jsx("span", { className: "whitespace-nowrap", children: shown.slice(split + 1) })
+                ] })
+              ) : /* @__PURE__ */ jsx("span", { children: "Time unknown" })
+            ] })
+          ] }),
+          toolbar && /* @__PURE__ */ jsx("div", { className: "border-b border-oprt-border p-2u", children: toolbar }),
+          /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 flex-col @oprt-lg:flex-row", children: [
+            navigation && /* @__PURE__ */ jsx(
+              "nav",
+              {
+                "aria-label": `${title} navigation`,
+                className: "min-w-0 max-h-40u overflow-y-auto border-b border-oprt-border p-2u @oprt-lg:max-h-none @oprt-lg:basis-1/4 @oprt-lg:overflow-visible @oprt-lg:border-b-0 @oprt-lg:border-r",
+                children: /* @__PURE__ */ jsx(InsideNavigationLandmarkProvider, { value: true, children: navigation })
+              }
+            ),
+            /* @__PURE__ */ jsx("div", { className: "min-w-0 flex-1 break-words p-2u", children })
+          ] }),
+          footer && /* @__PURE__ */ jsx("div", { className: "min-w-0 break-words border-t border-oprt-border p-2u", children: footer })
+        ]
+      }
+    );
+  }
+);
+AppShell.displayName = "AppShell";
+export {
+  AppShell
+};

package/dist/AppShell/AppShell.manifest.js

@@ -0,0 +1,66 @@
+// src/AppShell/AppShell.manifest.ts
+var AppShellManifest = {
+  AppShell: {
+    description: "In-page operational workspace with explicit identity, mode, connection, UTC reference time, and caller-supplied markings.",
+    props: {
+      identity: {
+        type: "string",
+        required: true,
+        description: "Application-supplied user or role identity; displayed verbatim."
+      },
+      title: {
+        type: "string",
+        default: "Workspace"
+      },
+      mode: {
+        type: "enum",
+        values: ["live", "paused", "replay", "training"],
+        default: "live",
+        description: "Presentation context. Does not connect to services or freeze data itself."
+      },
+      connection: {
+        type: "enum",
+        values: ["connected", "connecting", "reconnecting", "offline", "unknown"],
+        default: "unknown"
+      },
+      time: {
+        type: "number",
+        description: "Supplied reference time in epoch milliseconds, shown as YYYY-MM-DD HH:MM:SS UTC. Missing, null or invalid renders Time unknown; no running clock."
+      },
+      markings: {
+        type: "node",
+        description: "Caller-supplied policy/training markings. No classification is inferred."
+      },
+      navigation: {
+        type: "node",
+        description: `Navigation slot, usually a Sidebar, before the content in reading order. Beside the content when the shell is at least 640px wide (the shell's own width, not the window's); above it when narrower, capped at about eight rows and scrolling inside its named navigation landmark. The slot is the one navigation landmark, named from the title ("<title> navigation"); a Sidebar inside it adds no landmark of its own.`
+      },
+      toolbar: {
+        type: "node",
+        description: "Toolbar slot under the header; it grows with a toolbar that wraps onto more rows."
+      },
+      footer: {
+        type: "node"
+      }
+    },
+    slots: {
+      children: {
+        type: "ReactNode",
+        required: true
+      }
+    },
+    composable_with: [
+      "Sidebar",
+      "Inspector",
+      "TreeView",
+      "OperationalStatus",
+      "TimeRange",
+      "DataGrid"
+    ],
+    never_inside: ["Button"],
+    example: '<AppShell identity="Exercise analyst" mode="training" connection="offline" markings="EXERCISE" time={referenceTime}><DataGrid columns={columns} data={rows} getRowId={(row) => row.id} /></AppShell>'
+  }
+};
+export {
+  AppShellManifest
+};

package/dist/AppShell/index.js

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