@nexub/react 6.0.0 → 6.1.0

package/accessibility.json

@@ -1,5 +1,5 @@
 {
-  "version": "6.0.0",
+  "version": "6.1.0",
   "standard": "WCAG 2.2 Level AA",
   "method": {
     "automated": "axe-core rules tagged wcag2a, wcag2aa, wcag21a, wcag21aa and wcag22aa, run on every Storybook story in light and dark, and on open popups (menus, listboxes, dialogs), on every pull request; a new violation fails the build.",
@@ -410,6 +410,15 @@
       "keyboard": [],
       "screenReader": []
     },
+    {
+      "slug": "fieldset",
+      "name": "Fieldset",
+      "package": "@nexub/react",
+      "automated": "pass",
+      "exceptions": [],
+      "keyboard": [],
+      "screenReader": []
+    },
     {
       "slug": "filter-builder",
       "name": "Filter Builder",
@@ -459,6 +468,17 @@
       "keyboard": [],
       "screenReader": []
     },
+    {
+      "slug": "form",
+      "name": "Form",
+      "package": "@nexub/react",
+      "automated": "pass",
+      "exceptions": [],
+      "keyboard": [
+        "Enter: Submits from any text field; the first invalid field takes focus."
+      ],
+      "screenReader": []
+    },
     {
       "slug": "funnel",
       "name": "Funnel",
@@ -546,6 +566,19 @@
       "keyboard": [],
       "screenReader": []
     },
+    {
+      "slug": "inline-edit",
+      "name": "Inline Edit",
+      "package": "@nexub/react",
+      "automated": "pass",
+      "exceptions": [],
+      "keyboard": [
+        "Enter / Space: On the text: starts editing.",
+        "Enter: In the input: saves.",
+        "Escape: Reverts and returns focus to the text."
+      ],
+      "screenReader": []
+    },
     {
       "slug": "input",
       "name": "Input",

package/dist/components/Fieldset/Fieldset.d.ts

@@ -0,0 +1,11 @@
+import * as React from 'react';
+export interface FieldsetProps extends React.FieldsetHTMLAttributes<HTMLFieldSetElement> {
+    /** The group's name, read before each field inside it. */
+    legend: React.ReactNode;
+    description?: React.ReactNode;
+}
+/**
+ * Groups related fields under a heading (`<fieldset>` + `<legend>`). `disabled`
+ * disables every control inside it, natively.
+ */
+export declare const Fieldset: React.ForwardRefExoticComponent<FieldsetProps & React.RefAttributes<HTMLFieldSetElement>>;

package/dist/components/Fieldset/Fieldset.js

@@ -0,0 +1,23 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../../utils/cn.js";
+const Fieldset = React.forwardRef(function Fieldset2({ legend, description, className, children, ...props }, ref) {
+  const descriptionId = React.useId();
+  return /* @__PURE__ */ jsxs(
+    "fieldset",
+    {
+      ref,
+      "aria-describedby": description ? descriptionId : void 0,
+      className: cn("m-0 flex min-w-0 flex-col gap-4 border-0 p-0", className),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx("legend", { className: "mb-1 p-0 text-title-sm font-semibold text-[var(--color-on-surface)]", children: legend }),
+        description && /* @__PURE__ */ jsx("p", { id: descriptionId, className: "text-body-sm text-[var(--color-on-surface-muted)]", children: description }),
+        children
+      ]
+    }
+  );
+});
+export {
+  Fieldset
+};

package/dist/components/Fieldset/index.d.ts

@@ -0,0 +1,2 @@
+export { Fieldset } from './Fieldset.js';
+export type { FieldsetProps } from './Fieldset.js';

package/dist/components/Fieldset/index.js

@@ -0,0 +1,4 @@
+import { Fieldset } from "./Fieldset.js";
+export {
+  Fieldset
+};

package/dist/components/Form/Form.d.ts

@@ -0,0 +1,33 @@
+import * as React from 'react';
+export interface FormErrorItem {
+    /** The field's `name`. */
+    name: string;
+    /** The field's DOM id, or its name when it has none (ErrorSummary link target). */
+    id: string;
+    message: string;
+}
+export type FormErrors = Record<string, string>;
+export interface FormContextValue {
+    errors: FormErrors;
+    submitting: boolean;
+}
+/** Errors and submitting state of the closest `Form`, or null outside one. */
+export declare function useForm(): FormContextValue | null;
+export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, 'onSubmit' | 'onInvalid'> {
+    /**
+     * Extra checks after the browser's own (`required`, `type`, `pattern`, `min`…).
+     * Return `{ fieldName: message }`; empty values mean valid. Plug zod or any
+     * schema library in here.
+     */
+    validate?: (data: FormData) => Record<string, string | null | undefined | false> | void;
+    /** Called with the form data only when every field is valid. A promise sets `submitting`. */
+    onSubmit?: (data: FormData, event: React.FormEvent<HTMLFormElement>) => void | Promise<unknown>;
+    /** Called after a failed submit, in field order; pass the list to ErrorSummary. */
+    onInvalidSubmit?: (errors: FormErrorItem[]) => void;
+}
+/**
+ * A `<form>` that validates on submit with the browser's constraint validation
+ * plus your `validate`, shows the messages through FormField, and focuses the
+ * first invalid field. A field's error clears as soon as it is edited.
+ */
+export declare const Form: React.ForwardRefExoticComponent<FormProps & React.RefAttributes<HTMLFormElement>>;

package/dist/components/Form/Form.js

@@ -0,0 +1,79 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../../utils/cn.js";
+const FormContext = React.createContext(null);
+function useForm() {
+  return React.useContext(FormContext);
+}
+const isControl = (el) => "validity" in el && "name" in el && Boolean(el.name);
+const Form = React.forwardRef(function Form2({ validate, onSubmit, onInvalidSubmit, onInput, className, children, ...props }, ref) {
+  const [errors, setErrors] = React.useState({});
+  const [submitting, setSubmitting] = React.useState(false);
+  const handleSubmit = async (event) => {
+    event.preventDefault();
+    if (submitting) return;
+    const form = event.currentTarget;
+    const data = new FormData(form);
+    const controls = Array.from(form.elements).filter(isControl).filter((el) => !el.disabled);
+    const next = {};
+    for (const el of controls) {
+      if (!el.validity.valid && !next[el.name]) next[el.name] = el.validationMessage;
+    }
+    for (const [name, message] of Object.entries(validate?.(data) ?? {})) {
+      if (message && !next[name]) next[name] = message;
+    }
+    setErrors(next);
+    if (Object.keys(next).length) {
+      const seen = /* @__PURE__ */ new Set();
+      const items = [];
+      for (const el of controls) {
+        if (next[el.name] && !seen.has(el.name)) {
+          seen.add(el.name);
+          items.push({ name: el.name, id: el.id || el.name, message: next[el.name] });
+        }
+      }
+      for (const name of Object.keys(next)) {
+        if (!seen.has(name)) items.push({ name, id: name, message: next[name] });
+      }
+      onInvalidSubmit?.(items);
+      const first = controls.find((el) => next[el.name] && el.type !== "hidden");
+      first?.focus();
+      return;
+    }
+    const result = onSubmit?.(data, event);
+    if (result instanceof Promise) {
+      setSubmitting(true);
+      try {
+        await result;
+      } finally {
+        setSubmitting(false);
+      }
+    }
+  };
+  const handleInput = (event) => {
+    onInput?.(event);
+    const name = event.target.name;
+    if (name && errors[name]) {
+      setErrors(({ [name]: _cleared, ...rest }) => rest);
+    }
+  };
+  const value = React.useMemo(() => ({ errors, submitting }), [errors, submitting]);
+  return /* @__PURE__ */ jsx(FormContext.Provider, { value, children: /* @__PURE__ */ jsx(
+    "form",
+    {
+      ref,
+      noValidate: true,
+      "aria-busy": submitting || void 0,
+      className: cn("flex flex-col gap-5", className),
+      onSubmit: handleSubmit,
+      onInput: handleInput,
+      ...props,
+      children
+    }
+  ) });
+});
+export {
+  Form,
+  useForm
+};

package/dist/components/Form/index.d.ts

@@ -0,0 +1,2 @@
+export { Form, useForm } from './Form.js';
+export type { FormProps, FormErrorItem, FormErrors, FormContextValue } from './Form.js';

package/dist/components/Form/index.js

@@ -0,0 +1,5 @@
+import { Form, useForm } from "./Form.js";
+export {
+  Form,
+  useForm
+};

package/dist/components/FormField/FormField.d.ts

@@ -10,6 +10,8 @@ export interface FormFieldContextValue {
     disabled?: boolean;
     descriptionId: string;
     errorId: string;
+    /** The message from the enclosing Form for this field's `name`. */
+    formError?: string;
 }
 export interface FormFieldRootProps extends React.HTMLAttributes<HTMLDivElement> {
     id?: string;

package/dist/components/FormField/FormField.js

@@ -5,6 +5,7 @@ import { cn } from "../../utils/cn.js";
 import { Label } from "../Label/Label.js";
 import { HelperText } from "../HelperText/HelperText.js";
 import { FormError } from "../FormError/FormError.js";
+import { useForm } from "../Form/Form.js";
 const FormFieldContext = React.createContext(null);
 function useFormField() {
   const ctx = React.useContext(FormFieldContext);
@@ -13,9 +14,12 @@ function useFormField() {
   }
   return ctx;
 }
-const Root = React.forwardRef(function Root2({ id: idProp, name, invalid, required, disabled, className, children, ...props }, ref) {
+const Root = React.forwardRef(function Root2({ id: idProp, name, invalid: invalidProp, required, disabled, className, children, ...props }, ref) {
   const generatedId = React.useId();
   const id = idProp ?? generatedId;
+  const form = useForm();
+  const formError = name ? form?.errors[name] : void 0;
+  const invalid = invalidProp ?? (formError ? true : void 0);
   const value = React.useMemo(
     () => ({
       id,
@@ -24,9 +28,10 @@ const Root = React.forwardRef(function Root2({ id: idProp, name, invalid, requir
       required,
       disabled,
       descriptionId: `${id}-description`,
-      errorId: `${id}-error`
+      errorId: `${id}-error`,
+      formError
     }),
-    [id, name, invalid, required, disabled]
+    [id, name, invalid, required, disabled, formError]
   );
   return /* @__PURE__ */ jsx(FormFieldContext.Provider, { value, children: /* @__PURE__ */ jsx("div", { ref, className: cn("flex flex-col gap-1.5", className), ...props, children }) });
 });
@@ -79,9 +84,9 @@ function FieldError({
   children,
   ...props
 }) {
-  const { errorId, invalid } = useFormField();
+  const { errorId, invalid, formError } = useFormField();
   if (!invalid) return null;
-  return /* @__PURE__ */ jsx(FormError, { id: errorId, className, ...props, children });
+  return /* @__PURE__ */ jsx(FormError, { id: errorId, className, ...props, children: children ?? formError });
 }
 FieldError.displayName = "FormField.Error";
 const FormField = { Root, Label: FieldLabel, Control, Description, Error: FieldError };

package/dist/components/InlineEdit/InlineEdit.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+export interface InlineEditProps {
+    value: string;
+    /**
+     * Called with the new text on Enter or blur (only when it changed). Return a
+     * promise to keep the field open and busy until it settles; a rejection keeps
+     * it open and marks it invalid so the person can retry or press Escape.
+     */
+    onSave: (value: string) => void | Promise<unknown>;
+    /** Names the field: the input's label and "Edit ‹label›" on the button. */
+    label: string;
+    /** Shown when `value` is empty. */
+    placeholder?: string;
+    disabled?: boolean;
+    className?: string;
+}
+/**
+ * Text that turns into an input on click. Enter or blur saves, Escape reverts,
+ * and focus returns to the text afterwards.
+ */
+export declare function InlineEdit({ value, onSave, label, placeholder, disabled, className, }: InlineEditProps): React.JSX.Element;

package/dist/components/InlineEdit/InlineEdit.js

@@ -0,0 +1,103 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../../utils/cn.js";
+import { Input } from "../Input/Input.js";
+import { useNexubMessages } from "../NexubProvider/NexubProvider.js";
+function InlineEdit({
+  value,
+  onSave,
+  label,
+  placeholder,
+  disabled,
+  className
+}) {
+  const t = useNexubMessages();
+  const [editing, setEditing] = React.useState(false);
+  const [draft, setDraft] = React.useState(value);
+  const [saving, setSaving] = React.useState(false);
+  const [failed, setFailed] = React.useState(false);
+  const buttonRef = React.useRef(null);
+  const returnFocus = React.useRef(false);
+  React.useEffect(() => {
+    if (!editing && returnFocus.current) {
+      returnFocus.current = false;
+      buttonRef.current?.focus();
+    }
+  }, [editing]);
+  const close = (refocus) => {
+    returnFocus.current = refocus;
+    setFailed(false);
+    setEditing(false);
+  };
+  const save = async (refocus) => {
+    if (saving) return;
+    if (draft === value) return close(refocus);
+    const result = onSave(draft);
+    if (!(result instanceof Promise)) return close(refocus);
+    setSaving(true);
+    try {
+      await result;
+      close(refocus);
+    } catch {
+      setFailed(true);
+    } finally {
+      setSaving(false);
+    }
+  };
+  if (editing) {
+    return /* @__PURE__ */ jsx(
+      Input,
+      {
+        autoFocus: true,
+        "aria-label": label,
+        value: draft,
+        invalid: failed,
+        "aria-busy": saving || void 0,
+        readOnly: saving,
+        wrapperClassName: className,
+        onChange: (e) => {
+          setDraft(e.target.value);
+          setFailed(false);
+        },
+        onKeyDown: (e) => {
+          if (e.key === "Enter") {
+            e.preventDefault();
+            void save(true);
+          } else if (e.key === "Escape") {
+            e.preventDefault();
+            e.stopPropagation();
+            close(true);
+          }
+        },
+        onBlur: () => {
+          if (!failed) void save(false);
+        }
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      ref: buttonRef,
+      type: "button",
+      disabled,
+      "aria-label": `${t.editField(label)}, ${value || placeholder || ""}`,
+      onClick: () => {
+        setDraft(value);
+        setEditing(true);
+      },
+      className: cn(
+        "-mx-2 inline-flex min-h-control-sm max-w-full items-center rounded-shape-control px-2 text-start",
+        "text-body-md text-[var(--color-on-surface)] hover:bg-[var(--color-surface-container-high)]",
+        "disabled:cursor-not-allowed disabled:hover:bg-transparent",
+        !value && "text-[var(--color-on-surface-muted)]",
+        className
+      ),
+      children: /* @__PURE__ */ jsx("span", { className: "truncate", children: value || placeholder })
+    }
+  );
+}
+export {
+  InlineEdit
+};

package/dist/components/InlineEdit/index.d.ts

@@ -0,0 +1,2 @@
+export { InlineEdit } from './InlineEdit.js';
+export type { InlineEditProps } from './InlineEdit.js';

package/dist/components/InlineEdit/index.js

@@ -0,0 +1,4 @@
+import { InlineEdit } from "./InlineEdit.js";
+export {
+  InlineEdit
+};

package/dist/hooks/useUnsavedChanges.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Asks the browser to confirm before the page unloads (reload, close, external
+ * link) while `dirty` is true. In-app navigation belongs to your router: block
+ * it there with the same flag.
+ */
+export declare function useUnsavedChanges(dirty: boolean): void;

package/dist/hooks/useUnsavedChanges.js

@@ -0,0 +1,15 @@
+"use client";
+import { useEffect } from "react";
+function useUnsavedChanges(dirty) {
+  useEffect(() => {
+    if (!dirty) return;
+    const onBeforeUnload = (event) => {
+      event.preventDefault();
+    };
+    window.addEventListener("beforeunload", onBeforeUnload);
+    return () => window.removeEventListener("beforeunload", onBeforeUnload);
+  }, [dirty]);
+}
+export {
+  useUnsavedChanges
+};

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { useDisclosure } from './hooks/useDisclosure.js';
 export { useIsomorphicLayoutEffect } from './hooks/useIsomorphicLayoutEffect.js';
 export { useMediaQuery } from './hooks/useMediaQuery.js';
 export { useMergedRefs } from './hooks/useMergedRefs.js';
+export { useUnsavedChanges } from './hooks/useUnsavedChanges.js';
 export { usePointerSheen } from './hooks/usePointerSheen.js';
 export { PromptInput } from './components/PromptInput/index.js';
 export type { PromptInputProps, PromptInputMessages, PromptInputStatus } from './components/PromptInput/index.js';
@@ -213,6 +214,12 @@ export type { ErrorStateProps } from './components/ErrorState/index.js';
 export { FileUpload, fileAccepted } from './components/FileUpload/index.js';
 export type { FileUploadRootProps, FileUploadItemProps, FileRejection } from './components/FileUpload/index.js';
 export { OTPInput } from './components/OTPInput/index.js';
+export { Form, useForm } from './components/Form/index.js';
+export type { FormProps, FormErrorItem, FormErrors, FormContextValue } from './components/Form/index.js';
+export { Fieldset } from './components/Fieldset/index.js';
+export type { FieldsetProps } from './components/Fieldset/index.js';
+export { InlineEdit } from './components/InlineEdit/index.js';
+export type { InlineEditProps } from './components/InlineEdit/index.js';
 export type { OTPInputProps } from './components/OTPInput/index.js';
 export { DatePicker } from './components/DatePicker/index.js';
 export type { DatePickerProps } from './components/DatePicker/index.js';

package/dist/index.js

@@ -6,6 +6,7 @@ import { useDisclosure } from "./hooks/useDisclosure.js";
 import { useIsomorphicLayoutEffect } from "./hooks/useIsomorphicLayoutEffect.js";
 import { useMediaQuery } from "./hooks/useMediaQuery.js";
 import { useMergedRefs } from "./hooks/useMergedRefs.js";
+import { useUnsavedChanges } from "./hooks/useUnsavedChanges.js";
 import { usePointerSheen } from "./hooks/usePointerSheen.js";
 import { PromptInput } from "./components/PromptInput/index.js";
 import { ThinkingIndicator } from "./components/ThinkingIndicator/index.js";
@@ -120,6 +121,9 @@ import { EmptyState, EmptyStatePreset } from "./components/EmptyState/index.js";
 import { ErrorState } from "./components/ErrorState/index.js";
 import { FileUpload, fileAccepted } from "./components/FileUpload/index.js";
 import { OTPInput } from "./components/OTPInput/index.js";
+import { Form, useForm } from "./components/Form/index.js";
+import { Fieldset } from "./components/Fieldset/index.js";
+import { InlineEdit } from "./components/InlineEdit/index.js";
 import { DatePicker } from "./components/DatePicker/index.js";
 import { DateRangePicker } from "./components/DateRangePicker/index.js";
 import { todayIn } from "./components/DateRangePicker/index.js";
@@ -175,6 +179,7 @@ export {
   ErrorState,
   EyebrowChip,
   Fade,
+  Fieldset,
   FileUpload,
   FilterBuilder,
   FilterChip,
@@ -182,6 +187,7 @@ export {
   Flex,
   Float,
   FloatingInput,
+  Form,
   FormError,
   FormField,
   Funnel,
@@ -193,6 +199,7 @@ export {
   HelperText,
   HoverCard,
   IconButton,
+  InlineEdit,
   Input,
   Kbd,
   KeyboardShortcut,
@@ -312,6 +319,7 @@ export {
   transitionName,
   useControllableState,
   useDisclosure,
+  useForm,
   useIsomorphicLayoutEffect,
   useLocale,
   useMediaQuery,
@@ -321,5 +329,6 @@ export {
   usePrefersReducedMotion,
   useScopedSeed,
   useTheme,
-  useToastStore
+  useToastStore,
+  useUnsavedChanges
 };