@oprt/react 0.0.0-stage → 0.2.0

package/dist/ContextMenu/ContextMenu.js

@@ -0,0 +1,192 @@
+"use client";
+
+// src/ContextMenu/ContextMenu.tsx
+import {
+  forwardRef,
+  useEffect,
+  useRef,
+  useState
+} from "react";
+import { Keyboard, Menu, MenuItem, MenuTrigger, Pressable, Text } from "react-aria-components";
+import { usePress } from "react-aria";
+import { cva } from "class-variance-authority";
+import clsx from "clsx";
+import { Button } from "../Button/Button.js";
+import { useHydrationRoot } from "../_internal/hydration.js";
+import { composeMotionHandlers, MotionContext, useMotion } from "../_internal/motion.js";
+import { MotionPopover } from "../_internal/MotionPopover.js";
+import {
+  DESTRUCTIVE_ACTION,
+  MENU_EMPTY,
+  MENU_ITEM_DESCRIPTION,
+  MENU_ITEM_LABEL,
+  MENU_ITEM_SHORTCUT,
+  MENU_ITEM_TEXT,
+  MENU_OFFSET,
+  MENU_SURFACE,
+  menuItemStyles,
+  SCREEN_MARGIN
+} from "../_internal/overlay.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var surfaceStyles = cva(
+  "min-h-3u min-w-0 border border-transparent outline-hidden focus-visible:border-oprt-border-focus focus-visible:shadow-oprt-focus"
+);
+function isMac() {
+  if (typeof navigator === "undefined") return false;
+  const platform = navigator.userAgentData?.platform || navigator.platform;
+  return /^mac/i.test(platform) && !(navigator.maxTouchPoints > 1);
+}
+function ContextSurface({
+  label,
+  disabled,
+  children
+}) {
+  const surfaceRef = useRef(null);
+  const { pressProps } = usePress({ ref: surfaceRef, isDisabled: disabled });
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: surfaceRef,
+      id: pressProps.id,
+      role: "group",
+      "aria-label": label,
+      tabIndex: disabled ? -1 : 0,
+      className: surfaceStyles(),
+      onContextMenu: disabled ? void 0 : (event) => {
+        event.currentTarget.focus({ preventScroll: true });
+        pressProps.onContextMenu?.(event);
+      },
+      onKeyDown: (event) => {
+        if (disabled || event.target !== event.currentTarget || event.defaultPrevented) return;
+        const contextKey = event.key === "ContextMenu" || event.shiftKey && event.key === "F10";
+        const macShortcut = event.ctrlKey && !event.metaKey && !event.altKey && event.key === "Enter" && isMac();
+        if (!contextKey && !macShortcut) return;
+        event.preventDefault();
+        const target = event.currentTarget;
+        const rect = target.getBoundingClientRect();
+        target.dispatchEvent(
+          new MouseEvent("contextmenu", {
+            bubbles: true,
+            cancelable: true,
+            button: 2,
+            clientX: rect.left,
+            clientY: rect.bottom
+          })
+        );
+      },
+      children
+    }
+  );
+}
+var ContextMenu = forwardRef(
+  ({
+    label,
+    items,
+    onAction,
+    disabled = false,
+    emptyMessage = "No actions available",
+    children,
+    className,
+    ...props
+  }, ref) => {
+    const [open, setOpen] = useState(null);
+    const hydration = useHydrationRoot();
+    const motionState = useMotion("auto", "ContextMenu");
+    useEffect(() => {
+      if (disabled) setOpen(null);
+    }, [disabled]);
+    const menu = () => /* @__PURE__ */ jsx(
+      MotionPopover,
+      {
+        motionState,
+        offset: MENU_OFFSET,
+        containerPadding: SCREEN_MARGIN,
+        placement: "bottom start",
+        className: MENU_SURFACE,
+        children: /* @__PURE__ */ jsx(
+          Menu,
+          {
+            "aria-label": `${label} actions`,
+            "aria-labelledby": "",
+            className: "outline-hidden",
+            items,
+            renderEmptyState: () => /* @__PURE__ */ jsx("div", { className: MENU_EMPTY, children: emptyMessage }),
+            onAction: (key) => {
+              const item = items.find((candidate) => candidate.id === key);
+              if (!disabled && item && !item.disabled) onAction(item.id);
+            },
+            children: (item) => /* @__PURE__ */ jsxs(
+              MenuItem,
+              {
+                id: item.id,
+                textValue: item.label,
+                isDisabled: item.disabled ?? false,
+                className: menuItemStyles({ danger: item.danger ?? false }),
+                children: [
+                  /* @__PURE__ */ jsxs("span", { className: MENU_ITEM_TEXT, children: [
+                    /* @__PURE__ */ jsx(Text, { slot: "label", className: MENU_ITEM_LABEL, children: item.label }),
+                    item.danger && /* @__PURE__ */ jsx(Text, { slot: "description", className: MENU_ITEM_DESCRIPTION, children: DESTRUCTIVE_ACTION })
+                  ] }),
+                  item.shortcut && /* @__PURE__ */ jsx(Keyboard, { className: MENU_ITEM_SHORTCUT, children: item.shortcut })
+                ]
+              }
+            )
+          }
+        )
+      }
+    );
+    return /* @__PURE__ */ jsx(MotionContext.Provider, { value: motionState.mode, children: /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ...props,
+        ...composeMotionHandlers(motionState.props, props),
+        ...hydration.probeProps,
+        ref,
+        className: clsx(
+          "flex min-w-0 flex-wrap items-center gap-1u font-sans text-oprt-base normal-case tracking-normal text-oprt-text",
+          className
+        ),
+        children: [
+          /* @__PURE__ */ jsxs(
+            MenuTrigger,
+            {
+              trigger: "contextMenu",
+              isOpen: !disabled && open === "surface",
+              onOpenChange: (next) => setOpen(next && !disabled ? "surface" : null),
+              children: [
+                /* @__PURE__ */ jsx(ContextSurface, { label, disabled, children }),
+                menu()
+              ]
+            },
+            `${hydration.key}-surface`
+          ),
+          /* @__PURE__ */ jsxs(
+            MenuTrigger,
+            {
+              isOpen: !disabled && open === "button",
+              onOpenChange: (next) => setOpen(next && !disabled ? "button" : null),
+              children: [
+                /* @__PURE__ */ jsx(Pressable, { isDisabled: disabled, children: /* @__PURE__ */ jsx(
+                  Button,
+                  {
+                    variant: "secondary",
+                    size: "sm",
+                    disabled,
+                    "aria-label": `${label} actions`,
+                    children: "Actions"
+                  }
+                ) }),
+                menu()
+              ]
+            },
+            `${hydration.key}-button`
+          )
+        ]
+      }
+    ) });
+  }
+);
+ContextMenu.displayName = "ContextMenu";
+export {
+  ContextMenu
+};

package/dist/ContextMenu/ContextMenu.manifest.js

@@ -0,0 +1,41 @@
+// src/ContextMenu/ContextMenu.manifest.ts
+var ContextMenuManifest = {
+  ContextMenu: {
+    description: "Context actions with a focusable surface and an equivalent visible menu button.",
+    props: {
+      label: {
+        type: "string",
+        required: true,
+        description: "Names the surface; the visible button is named `${label} actions`."
+      },
+      items: {
+        type: "array",
+        required: true,
+        description: "Stable unique id and readable label, with optional shortcut text, disabled and danger flags."
+      },
+      onAction: {
+        type: "function",
+        required: true,
+        description: "Receives the selected item ID. Both activation paths use the same supplied actions."
+      },
+      disabled: {
+        type: "boolean",
+        default: false,
+        description: "Disables both menu activation paths without disabling supplied child content."
+      },
+      emptyMessage: {
+        type: "string",
+        default: "No actions available",
+        description: "Non-interactive row the menu shows when items is empty."
+      },
+      className: { type: "string" }
+    },
+    slots: { children: { type: "ReactNode", required: true } },
+    composable_with: ["InlineEdit", "DataGrid"],
+    never_inside: ["Button"],
+    example: '<ContextMenu label="Alpha relay" items={[{id: "inspect", label: "Inspect"}]} onAction={handleAction}>EQ-01</ContextMenu>'
+  }
+};
+export {
+  ContextMenuManifest
+};

package/dist/ContextMenu/index.js

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

package/dist/CoordinateInput/CoordinateInput.js

@@ -0,0 +1,141 @@
+"use client";
+
+// src/CoordinateInput/CoordinateInput.tsx
+import { forwardRef, useEffect, useRef, useState } from "react";
+import clsx from "clsx";
+import { NumberInput } from "../NumberInput/NumberInput.js";
+import { joinIds, usePartIds } from "../_internal/fieldIds.js";
+import { useMergedRefs } from "../_internal/mergeRefs.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var unknown = { latitude: null, longitude: null };
+var CoordinateInput = forwardRef(
+  ({
+    label = "Coordinates",
+    value,
+    defaultValue = unknown,
+    onValueChange,
+    onValidationChange,
+    description,
+    error,
+    latitudeName,
+    longitudeName,
+    disabled = false,
+    className,
+    "aria-describedby": describedBy,
+    ...props
+  }, ref) => {
+    const fieldset = useRef(null);
+    const fieldsetRef = useMergedRefs(fieldset, ref);
+    const ids = usePartIds(["status", "description", "error"], {
+      readRendered: () => fieldset.current?.getAttribute("data-oprt-ids")
+    });
+    const [local, setLocal] = useState(defaultValue);
+    const [invalidAxes, setInvalidAxes] = useState({ latitude: false, longitude: false });
+    const position = value ?? local;
+    const invalid = Boolean(error) || invalidAxes.latitude || invalidAxes.longitude || position.latitude !== null && (!Number.isFinite(position.latitude) || Math.abs(position.latitude) > 90) || position.longitude !== null && (!Number.isFinite(position.longitude) || Math.abs(position.longitude) > 180);
+    const validationRef = useRef(onValidationChange);
+    validationRef.current = onValidationChange;
+    useEffect(() => {
+      validationRef.current?.(invalid);
+    }, [invalid]);
+    const status = invalid ? "Position invalid" : position.latitude === null || position.longitude === null ? "Position unknown" : "Decimal degrees";
+    const change = (axis, next) => {
+      if (disabled) return;
+      const nextPosition = { ...position, [axis]: next };
+      if (value === void 0) setLocal(nextPosition);
+      onValueChange?.(nextPosition);
+    };
+    return /* @__PURE__ */ jsxs(
+      "fieldset",
+      {
+        ...props,
+        ref: fieldsetRef,
+        "data-oprt-ids": ids.base,
+        disabled,
+        "aria-invalid": invalid || void 0,
+        "aria-describedby": joinIds(
+          describedBy,
+          ids.status,
+          description && ids.description,
+          error && ids.error
+        ),
+        className: clsx(
+          "m-0 min-w-0 border p-2u font-sans text-oprt-base normal-case text-oprt-text",
+          invalid ? "border-oprt-error" : "border-oprt-border",
+          className
+        ),
+        children: [
+          /* @__PURE__ */ jsx("legend", { className: "min-w-0 px-1u oprt-wrap-anywhere text-oprt-base font-medium text-oprt-text", children: label }),
+          description && /* @__PURE__ */ jsx(
+            "p",
+            {
+              id: ids.description,
+              className: "m-0 mb-1u min-w-0 oprt-wrap-anywhere text-oprt-text-dim",
+              children: description
+            }
+          ),
+          /* @__PURE__ */ jsxs("div", { className: "grid grid-cols-[repeat(auto-fit,minmax(min(100%,12rem),1fr))] gap-2u", children: [
+            /* @__PURE__ */ jsx(
+              NumberInput,
+              {
+                label: "Latitude",
+                unit: "\xB0",
+                value: position.latitude,
+                onValueChange: (next) => change("latitude", next),
+                onValidationChange: (validation) => setInvalidAxes(
+                  (axes) => axes.latitude === Boolean(validation) ? axes : { ...axes, latitude: Boolean(validation) }
+                ),
+                min: -90,
+                max: 90,
+                disabled,
+                ...latitudeName !== void 0 ? { name: latitudeName } : {}
+              }
+            ),
+            /* @__PURE__ */ jsx(
+              NumberInput,
+              {
+                label: "Longitude",
+                unit: "\xB0",
+                value: position.longitude,
+                onValueChange: (next) => change("longitude", next),
+                onValidationChange: (validation) => setInvalidAxes(
+                  (axes) => axes.longitude === Boolean(validation) ? axes : { ...axes, longitude: Boolean(validation) }
+                ),
+                min: -180,
+                max: 180,
+                disabled,
+                ...longitudeName !== void 0 ? { name: longitudeName } : {}
+              }
+            )
+          ] }),
+          /* @__PURE__ */ jsx(
+            "p",
+            {
+              id: ids.status,
+              role: "status",
+              className: clsx(
+                "m-0 mt-1u min-w-0 oprt-wrap-anywhere",
+                invalid ? "text-oprt-error" : "text-oprt-text-dim"
+              ),
+              children: status
+            }
+          ),
+          error && // A caller's error is an alert, as in a Field (MultiSelect-R2).
+          /* @__PURE__ */ jsx(
+            "p",
+            {
+              id: ids.error,
+              role: "alert",
+              className: "m-0 mt-1u min-w-0 oprt-wrap-anywhere text-oprt-error",
+              children: error
+            }
+          )
+        ]
+      }
+    );
+  }
+);
+CoordinateInput.displayName = "CoordinateInput";
+export {
+  CoordinateInput
+};

package/dist/CoordinateInput/CoordinateInput.manifest.js

@@ -0,0 +1,36 @@
+// src/CoordinateInput/CoordinateInput.manifest.ts
+var CoordinateInputManifest = {
+  CoordinateInput: {
+    description: "Decimal-degree latitude and longitude fields with bounded validation and explicit unknown or invalid position states.",
+    props: {
+      label: { type: "string", default: "Coordinates" },
+      value: {
+        type: "node",
+        description: "Controlled { latitude: number | null, longitude: number | null }. Latitude is -90\u202690; longitude is -180\u2026180, inclusive. Null axes are unknown."
+      },
+      defaultValue: {
+        type: "node",
+        description: "Initial uncontrolled coordinates. Defaults to both axes null."
+      },
+      onValueChange: {
+        type: "function",
+        description: "(position: CoordinateValue) => void. Only valid axis edits or a cleared null axis are emitted; the other axis is preserved. Does not normalize or wrap out-of-range input."
+      },
+      onValidationChange: {
+        type: "function",
+        description: "(invalid: boolean) => void. Reports aggregate invalid state initially and on change, including local typed drafts, supplied values and error. Missing/null axes are unknown rather than invalid; callers separately require both axes before Go-to or submission."
+      },
+      disabled: { type: "boolean", default: false },
+      description: { type: "string" },
+      error: { type: "string" },
+      latitudeName: { type: "string", description: "Native form field name for latitude." },
+      longitudeName: { type: "string", description: "Native form field name for longitude." }
+    },
+    composable_with: ["Card", "NumberInput"],
+    never_inside: ["Button"],
+    example: '<CoordinateInput label="Observation position" value={position} onValueChange={setPosition} />'
+  }
+};
+export {
+  CoordinateInputManifest
+};

package/dist/CoordinateInput/index.js

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

package/dist/CopyButton/CopyButton.js

@@ -0,0 +1,129 @@
+"use client";
+
+// src/CopyButton/CopyButton.tsx
+import { forwardRef, useRef, useState } from "react";
+import { cva } from "class-variance-authority";
+import { Copy } from "@oprt/icons";
+import { Button } from "../Button/Button.js";
+import { CopyButtonManifest } from "./CopyButton.manifest.js";
+import { devValidate } from "../_internal/devValidate.js";
+import { useIsMounted } from "../_internal/useIsMounted.js";
+import { useIsomorphicLayoutEffect } from "../_internal/useIsomorphicLayoutEffect.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var copyStyles = cva("inline-flex min-w-0 flex-wrap items-center gap-1u");
+var iconSize = { sm: 12, md: 16, lg: 20 };
+var feedbackStyles = cva("min-w-0 break-words font-sans text-oprt-base normal-case", {
+  variants: {
+    state: {
+      pending: "text-oprt-text-dim",
+      success: "text-oprt-success",
+      error: "text-oprt-error"
+    }
+  }
+});
+var reportedLabels = /* @__PURE__ */ new Set();
+function reportLabelWithoutVisibleText(label) {
+  if (process.env.NODE_ENV === "production" || reportedLabels.has(label)) return;
+  reportedLabels.add(label);
+  console.error(
+    JSON.stringify(
+      {
+        component: "CopyButton",
+        error: "LABEL_OMITS_VISIBLE_TEXT",
+        prop: "label",
+        received: label,
+        suggestion: 'The button shows the word "Copy", so its label must contain it (WCAG 2.5.3, Label in Name). Start the label with it: "Copy equipment ID".'
+      },
+      null,
+      2
+    )
+  );
+}
+var CopyButton = forwardRef((allProps, ref) => {
+  const { value, label, onCopy, onCopyError, disabled = false, size = "md", className } = allProps;
+  const [pending, setPending] = useState(false);
+  if (!/copy/i.test(label)) reportLabelWithoutVisibleText(label);
+  const [feedback, setFeedback] = useState(null);
+  const pendingRef = useRef(false);
+  const isMounted = useIsMounted();
+  const context = useRef({ value, label, revision: 0 });
+  if (process.env.NODE_ENV !== "production") {
+    devValidate("CopyButton", CopyButtonManifest.CopyButton.props, { ...allProps });
+  }
+  useIsomorphicLayoutEffect(() => {
+    if (context.current.value !== value || context.current.label !== label) {
+      context.current = { value, label, revision: context.current.revision + 1 };
+      setFeedback(null);
+    }
+  }, [value, label]);
+  async function copy() {
+    if (disabled || pendingRef.current) return;
+    pendingRef.current = true;
+    setPending(true);
+    const request = { value, label, revision: context.current.revision };
+    setFeedback({ value, label, state: "pending" });
+    let outcome;
+    try {
+      const clipboard = navigator.clipboard;
+      if (typeof clipboard?.writeText !== "function") {
+        throw new Error("Clipboard writing is unavailable.");
+      }
+      await clipboard.writeText(request.value);
+      outcome = { state: "success" };
+    } catch (error) {
+      outcome = { state: "error", error };
+    }
+    pendingRef.current = false;
+    if (!isMounted()) return;
+    setPending(false);
+    if (context.current.revision !== request.revision || context.current.value !== request.value || context.current.label !== request.label)
+      return;
+    setFeedback({ value: request.value, label: request.label, state: outcome.state });
+    try {
+      if (outcome.state === "success") onCopy?.({ value: request.value });
+      else onCopyError?.({ value: request.value, error: outcome.error });
+    } catch {
+    }
+  }
+  const visibleFeedback = feedback?.value === value && feedback.label === label ? feedback : null;
+  return /* @__PURE__ */ jsxs("span", { className: copyStyles(), children: [
+    /* @__PURE__ */ jsxs(
+      Button,
+      {
+        ref,
+        variant: "tertiary",
+        size,
+        className,
+        "aria-label": label,
+        "aria-disabled": disabled || pending,
+        "aria-busy": pending,
+        disabled,
+        onClick: () => {
+          void copy();
+        },
+        children: [
+          /* @__PURE__ */ jsx(Copy, { "aria-hidden": "true", size: iconSize[size ?? "md"] }),
+          "Copy"
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsxs(
+      "span",
+      {
+        role: "status",
+        "aria-live": "polite",
+        "aria-atomic": "true",
+        className: feedbackStyles({ state: visibleFeedback?.state }),
+        children: [
+          visibleFeedback?.state === "pending" && `${visibleFeedback.label}: copying\u2026`,
+          visibleFeedback?.state === "success" && `${visibleFeedback.label}: copied`,
+          visibleFeedback?.state === "error" && `${visibleFeedback.label}: failed. Select the value and copy it manually.`
+        ]
+      }
+    )
+  ] });
+});
+CopyButton.displayName = "CopyButton";
+export {
+  CopyButton
+};

package/dist/CopyButton/CopyButton.manifest.js

@@ -0,0 +1,35 @@
+// src/CopyButton/CopyButton.manifest.ts
+var CopyButtonManifest = {
+  CopyButton: {
+    description: "Copies a supplied exact string with visible pending, success and failure feedback.",
+    props: {
+      value: {
+        type: "string",
+        required: true,
+        description: "Exact string to copy; whitespace and precision are preserved."
+      },
+      label: {
+        type: "string",
+        required: true,
+        description: 'Accessible action name identifying the value. It must contain "Copy", the word the button shows. Feedback reads this label, then the outcome: "Copy equipment ID: copied".'
+      },
+      size: { type: "enum", values: ["sm", "md", "lg"], default: "md" },
+      disabled: { type: "boolean", default: false },
+      className: { type: "string", description: "Classes applied to the native action button." },
+      onCopy: {
+        type: "function",
+        description: "Receives { value } after the requested write resolves. Suppressed after context changes or unmount."
+      },
+      onCopyError: {
+        type: "function",
+        description: "Receives { value, error } if writing fails or is unavailable. Suppressed after context changes or unmount."
+      }
+    },
+    composable_with: ["DescriptionList", "EntityPreview", "Popover", "Inspector", "Toolbar"],
+    never_inside: ["Button", "Link"],
+    example: '<CopyButton value={equipment.id} label="Copy equipment ID" size="sm" />'
+  }
+};
+export {
+  CopyButtonManifest
+};

package/dist/CopyButton/index.js

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