@oprt/react 0.0.0-stage → 0.1.0

package/dist/NumberInput/NumberInput.js

@@ -0,0 +1,210 @@
+"use client";
+
+// src/NumberInput/NumberInput.tsx
+import { forwardRef, useEffect, useRef, useState } from "react";
+import { cva } from "class-variance-authority";
+import clsx from "clsx";
+import { useMergedRefs } from "../_internal/mergeRefs.js";
+import { joinIds, usePartIds } from "../_internal/fieldIds.js";
+import { FORCED_FOCUS_WITHIN, FORCED_NO_RESTING_OUTLINE } from "../_internal/controlStyles.js";
+import { devValidate } from "../_internal/devValidate.js";
+import { NumberInputManifest } from "./NumberInput.manifest.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var styles = cva(
+  // Disabled looks like DC-9's disabled buttons (coordinator ruling on DC-B04-2, NumberInput-R1):
+  // dim text, the control outline and a muted fill; CoordinateInput's axes inherit it.
+  "flex min-w-0 items-center gap-1u border bg-oprt-surface-2 px-2u focus-within:shadow-oprt-focus has-[input:disabled]:cursor-not-allowed has-[input:disabled]:bg-oprt-surface-3 has-[input:disabled]:border-oprt-border-control",
+  {
+    variants: {
+      invalid: {
+        true: "border-oprt-error",
+        // The control outline (design call DC-3).
+        false: "border-oprt-border-control focus-within:border-oprt-border-focus"
+      },
+      // The height is a minimum: a long unit wraps in its own column beside the number and the
+      // field grows taller (coordinator ruling on DC-B04-3, NumberInput-R3), while a one-line field
+      // keeps exactly its token height; sm caps the number's 24px line inside its 2px of border.
+      size: {
+        // Capped at sm, so centered with auto margins rather than stretched (see Input).
+        sm: "min-h-oprt-sm [&_input]:my-auto [&_input]:max-h-[calc(var(--oprt-height-sm)-2px)]",
+        md: "min-h-oprt-md",
+        lg: "min-h-oprt-lg"
+      }
+    },
+    defaultVariants: { invalid: false, size: "md" }
+  }
+);
+function validate(text, unit, min, max, step, required) {
+  if (!unit.trim()) return "A unit is required.";
+  if (min !== void 0 && !Number.isFinite(min) || max !== void 0 && !Number.isFinite(max) || min !== void 0 && max !== void 0 && min > max)
+    return "Invalid numeric range.";
+  if (step !== "any" && (!Number.isFinite(step) || step <= 0))
+    return "Step must be a positive finite number.";
+  if (text.trim() === "") return required ? "A value is required." : null;
+  if (!/^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(text.trim()) || !Number.isFinite(Number(text)))
+    return "Enter a finite number.";
+  const number = Number(text);
+  if (min !== void 0 && number < min) return `Enter a value of at least ${min} ${unit}.`;
+  if (max !== void 0 && number > max) return `Enter a value of at most ${max} ${unit}.`;
+  if (step !== "any") {
+    const steps = (number - (min ?? 0)) / step;
+    if (Math.abs(steps - Math.round(steps)) > 1e-7)
+      return `Use increments of ${step} ${unit} from ${min ?? 0}.`;
+  }
+  return null;
+}
+function plainDecimal(value) {
+  return value.toLocaleString("en-US", { useGrouping: false, maximumFractionDigits: 20 });
+}
+var NumberInput = forwardRef((allProps, ref) => {
+  const {
+    label,
+    unit,
+    value,
+    defaultValue = null,
+    onValueChange,
+    onValidationChange,
+    min,
+    max,
+    step = "any",
+    size = "md",
+    description,
+    error,
+    required = false,
+    disabled = false,
+    readOnly = false,
+    className,
+    id,
+    onBlur,
+    onKeyDown,
+    "aria-describedby": describedBy,
+    ...props
+  } = allProps;
+  if (process.env.NODE_ENV !== "production") {
+    devValidate("NumberInput", NumberInputManifest.NumberInput.props, { ...allProps });
+  }
+  const labelRef = useRef(null);
+  const ids = usePartIds(["unit", "description", "error", "unknown"], {
+    id,
+    readRendered: () => labelRef.current?.htmlFor
+  });
+  const inputId = ids.base;
+  const inputRef = useRef(null);
+  const mergedRef = useMergedRefs(inputRef, ref);
+  const [local, setLocal] = useState(defaultValue);
+  const numeric = value === void 0 ? local : value;
+  const [draft, setDraft] = useState(null);
+  const text = draft && Object.is(draft.base, numeric) ? draft.text : numeric === null ? "" : String(numeric);
+  const validation = error || validate(text, unit, min, max, step, required);
+  const validationRef = useRef(onValidationChange);
+  validationRef.current = onValidationChange;
+  useEffect(() => {
+    inputRef.current?.setCustomValidity(validation ?? "");
+    validationRef.current?.(validation ?? null);
+  }, [validation]);
+  const commit = (next) => {
+    if (value === void 0) setLocal(next);
+    onValueChange?.(next);
+  };
+  const descriptions = joinIds(
+    describedBy,
+    ids.unit,
+    description && ids.description,
+    validation ? ids.error : text === "" && ids.unknown
+  );
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: clsx(
+        "flex min-w-0 flex-col gap-1u font-sans text-oprt-base normal-case text-oprt-text",
+        className
+      ),
+      children: [
+        /* @__PURE__ */ jsx(
+          "label",
+          {
+            ref: labelRef,
+            htmlFor: inputId,
+            className: "m-0 min-w-0 oprt-wrap-anywhere text-oprt-base font-medium text-oprt-text",
+            children: label
+          }
+        ),
+        /* @__PURE__ */ jsxs("div", { className: clsx(styles({ size, invalid: Boolean(validation) }), FORCED_FOCUS_WITHIN), children: [
+          /* @__PURE__ */ jsx(
+            "input",
+            {
+              ...props,
+              ref: mergedRef,
+              id: inputId,
+              type: "text",
+              role: "spinbutton",
+              inputMode: "decimal",
+              value: text,
+              disabled,
+              readOnly,
+              required,
+              "aria-valuemin": min,
+              "aria-valuemax": max,
+              "aria-valuenow": text !== "" && !validation ? plainDecimal(Number(text)) : void 0,
+              "aria-valuetext": validation ? `Invalid: ${text}` : text === "" ? "Unknown" : `${text} ${unit}`,
+              "aria-invalid": Boolean(validation) || void 0,
+              "aria-describedby": descriptions,
+              className: clsx(
+                "min-w-[min(calc(10ch_+_10_*_var(--oprt-tracking-md)_+_2px),100%)] flex-1 self-stretch border-0 bg-transparent font-mono text-oprt-md font-medium tabular-nums text-oprt-text outline-hidden disabled:cursor-not-allowed disabled:text-oprt-text-dim",
+                FORCED_NO_RESTING_OUTLINE
+              ),
+              onChange: (event) => {
+                if (disabled || readOnly) return;
+                const nextText = event.target.value;
+                const invalid = validate(nextText, unit, min, max, step, required);
+                const next = nextText.trim() === "" ? null : Number(nextText);
+                setDraft({ text: nextText, base: value === void 0 && !invalid ? next : numeric });
+                if (!invalid) commit(next);
+              },
+              onBlur: (event) => {
+                if (!validation) setDraft(null);
+                onBlur?.(event);
+              },
+              onKeyDown: (event) => {
+                onKeyDown?.(event);
+                if (event.defaultPrevented || disabled || readOnly) return;
+                let next;
+                if (event.key === "ArrowUp" || event.key === "ArrowDown") {
+                  const delta = step === "any" ? 1 : step;
+                  const base = text.trim() !== "" && Number.isFinite(Number(text)) ? Number(text) : min ?? 0;
+                  next = Number((base + (event.key === "ArrowUp" ? delta : -delta)).toPrecision(14));
+                } else if (event.key === "Home" && min !== void 0) next = min;
+                else if (event.key === "End" && max !== void 0) next = max;
+                if (next === void 0) return;
+                event.preventDefault();
+                next = Math.min(max ?? Infinity, Math.max(min ?? -Infinity, next));
+                if (validate(String(next), unit, min, max, step, required)) return;
+                setDraft(null);
+                commit(next);
+              }
+            }
+          ),
+          /* @__PURE__ */ jsx("span", { id: ids.unit, className: "min-w-0 oprt-wrap-anywhere font-mono text-oprt-text-dim", children: unit || "Unit missing" })
+        ] }),
+        description && /* @__PURE__ */ jsx("p", { id: ids.description, className: "m-0 min-w-0 oprt-wrap-anywhere text-oprt-text-dim", children: description }),
+        validation ? (
+          // A caller's error is an alert, as in a Field (MultiSelect-R2); the field's own
+          // as-you-type message stays a description, so typing raises no alert per keystroke.
+          /* @__PURE__ */ jsx(
+            "p",
+            {
+              id: ids.error,
+              ...error ? { role: "alert" } : {},
+              className: "m-0 min-w-0 oprt-wrap-anywhere text-oprt-error",
+              children: validation
+            }
+          )
+        ) : text === "" && /* @__PURE__ */ jsx("p", { id: ids.unknown, className: "m-0 text-oprt-text-dim", children: "Unknown" })
+      ]
+    }
+  );
+});
+NumberInput.displayName = "NumberInput";
+export {
+  NumberInput
+};

package/dist/NumberInput/NumberInput.manifest.js

@@ -0,0 +1,56 @@
+// src/NumberInput/NumberInput.manifest.ts
+var NumberInputManifest = {
+  NumberInput: {
+    description: "Numeric entry with an explicit unit, keyboard stepping, range and step validation, and unknown-value state.",
+    props: {
+      label: { type: "string", required: true },
+      unit: {
+        type: "string",
+        required: true,
+        description: "Visible and described unit such as m, kn or \xB0. Empty units are invalid; no conversion is performed."
+      },
+      value: {
+        type: "number",
+        description: "Controlled number or null for unknown. Invalid drafts stay visible and never emit NaN or out-of-range values."
+      },
+      defaultValue: {
+        type: "number",
+        description: "Initial uncontrolled number, or null (the default)."
+      },
+      onValueChange: {
+        type: "function",
+        description: "(value: number | null) => void. Emits valid numeric edits or null when cleared. Does not emit invalid drafts."
+      },
+      onValidationChange: {
+        type: "function",
+        description: "(error: string | null) => void. Reports draft and supplied-value validation; use this to block application submission while a draft is invalid."
+      },
+      min: { type: "number" },
+      max: { type: "number" },
+      step: {
+        type: "string",
+        default: "any",
+        description: "Positive number or 'any'. Numeric steps validate from min (or zero); Arrow keys use 1 for 'any'."
+      },
+      size: { type: "enum", values: ["sm", "md", "lg"], default: "md" },
+      disabled: { type: "boolean", default: false },
+      readOnly: { type: "boolean", default: false },
+      required: { type: "boolean", default: false },
+      description: { type: "string" },
+      error: {
+        type: "string",
+        description: "Caller-supplied validation error, displayed before built-in validation."
+      },
+      name: {
+        type: "string",
+        description: "Native form field name. Constraint validation blocks invalid numeric drafts."
+      }
+    },
+    composable_with: ["Card", "CoordinateInput"],
+    never_inside: ["Button"],
+    example: '<NumberInput label="Altitude" unit="m" value={altitude} onValueChange={setAltitude} min={0} max={20000} step={10} />'
+  }
+};
+export {
+  NumberInputManifest
+};

package/dist/NumberInput/index.js

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

package/dist/OperationalStatus/OperationalStatus.js

@@ -0,0 +1,89 @@
+"use client";
+
+// src/OperationalStatus/OperationalStatus.tsx
+import { forwardRef, useId } from "react";
+import { cva } from "class-variance-authority";
+import clsx from "clsx";
+import { Badge } from "../Badge/Badge.js";
+import { DescriptionList } from "../DescriptionList/DescriptionList.js";
+import { devValidate } from "../_internal/devValidate.js";
+import { formatUtcTimestamp, isValidTimestamp } from "../_internal/timestamp.js";
+import { OperationalStatusManifest } from "./OperationalStatus.manifest.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var statusStyles = cva(
+  "flex min-w-0 flex-col gap-1u font-sans text-oprt-base normal-case tracking-normal text-oprt-text"
+);
+var variants = {
+  current: "success",
+  stale: "warning",
+  partial: "warning",
+  unavailable: "error",
+  unknown: "neutral"
+};
+var OperationalStatus = forwardRef(
+  (allProps, ref) => {
+    const { state = "unknown", source, updatedAt, detail, className, ...props } = allProps;
+    const qualityId = `${useId()}-quality`;
+    if (process.env.NODE_ENV !== "production") {
+      devValidate("OperationalStatus", OperationalStatusManifest.OperationalStatus.props, {
+        ...allProps
+      });
+    }
+    const shown = isValidTimestamp(updatedAt) ? formatUtcTimestamp(updatedAt) : null;
+    const isoTime = isValidTimestamp(updatedAt) ? new Date(updatedAt).toISOString() : null;
+    const split = shown?.indexOf(" ") ?? -1;
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        role: "group",
+        "aria-labelledby": qualityId,
+        ...props,
+        ref,
+        className: clsx(statusStyles(), className),
+        children: [
+          /* @__PURE__ */ jsx(
+            DescriptionList,
+            {
+              layout: "details",
+              items: [
+                {
+                  id: "quality",
+                  label: /* @__PURE__ */ jsx("span", { id: qualityId, children: "Data quality" }),
+                  value: /* @__PURE__ */ jsx(
+                    Badge,
+                    {
+                      appearance: "text",
+                      size: "md",
+                      variant: variants[state],
+                      className: "ml-auto tracking-oprt-sm",
+                      children: state
+                    }
+                  )
+                },
+                { id: "source", label: "Source", value: source || "Unknown" },
+                {
+                  id: "updated",
+                  label: "Updated",
+                  value: isoTime && shown ? (
+                    // The date and the time wrap apart; neither breaks inside, so "UTC" stays with
+                    // the time.
+                    /* @__PURE__ */ jsxs("time", { dateTime: isoTime, className: "font-mono", children: [
+                      /* @__PURE__ */ jsx("span", { className: "whitespace-nowrap", children: shown.slice(0, split) }),
+                      " ",
+                      /* @__PURE__ */ jsx("span", { className: "whitespace-nowrap", children: shown.slice(split + 1) })
+                    ] })
+                  ) : "Time unknown"
+                }
+              ]
+            }
+          ),
+          detail && /* @__PURE__ */ jsx("p", { className: "m-0 mt-1u oprt-wrap-anywhere text-oprt-text-dim", children: detail })
+        ]
+      }
+    );
+  }
+);
+OperationalStatus.displayName = "OperationalStatus";
+export {
+  OperationalStatus
+};

package/dist/OperationalStatus/OperationalStatus.manifest.js

@@ -0,0 +1,39 @@
+// src/OperationalStatus/OperationalStatus.manifest.ts
+var OperationalStatusManifest = {
+  OperationalStatus: {
+    description: "Application-asserted data quality, source, and UTC update time in shared label/value detail rows.",
+    props: {
+      state: {
+        type: "enum",
+        values: ["current", "stale", "partial", "unavailable", "unknown"],
+        default: "unknown",
+        description: "Application assertion rendered as a text-only badge; never inferred from connection or the wall clock."
+      },
+      source: {
+        type: "string",
+        description: "Provenance label; defaults to Unknown."
+      },
+      updatedAt: {
+        type: "number",
+        description: "Epoch milliseconds, including zero. Shown as UTC to the second, 'YYYY-MM-DD HH:MM:SS UTC', with the date and the time wrapping separately; the machine-readable time element keeps the exact instant. Null, missing, or invalid renders Time unknown in the Updated row."
+      },
+      detail: {
+        type: "string",
+        description: "Missing coverage, stale threshold, quality, or last-known context."
+      }
+    },
+    composable_with: [
+      "AppShell",
+      "Inspector",
+      "DataGrid",
+      "EntityPreview",
+      "DescriptionList",
+      "Badge"
+    ],
+    never_inside: ["Button"],
+    example: '<OperationalStatus state="partial" source="Supplied report" updatedAt={lastReport} detail="One source has not reported." />'
+  }
+};
+export {
+  OperationalStatusManifest
+};

package/dist/OperationalStatus/index.js

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