@jcsoftdev/ui 0.1.4 → 0.1.6

package/src/charts/gauge-chart/gauge-chart.tsx

@@ -41,7 +41,7 @@ export interface GaugeChartProps {
   variant?: "semi" | "three-quarter";
   /** Filled arc (`progress`) or a pointer over the bands (`needle`). */
   mode?: "progress" | "needle";
-  /** Colored bands. With `progress` they sit behind the arc and the arc takes the color of the band it is in. */
+  /** Colored bands. With `progress` the track stays neutral, the arc takes the color of the band it is in, and a band shows only while hovered or focused. */
   ranges?: readonly GaugeRange[];
   height?: number | "fill";
   /** Width / height ratio; sizes the drawing from the container width when `height` is not "fill". */
@@ -406,7 +406,7 @@ function GaugePlot({
           </defs>
         ) : null}
 
-        {bands.length === 0 ? (
+        {bands.length === 0 || !needle ? (
           <path
             d={arcLine(cx, cy, mid, a0 + capAngle, a1 - capAngle)}
             fill="none"
@@ -414,7 +414,8 @@ function GaugePlot({
             strokeLinecap={roundedCaps ? "round" : "butt"}
             style={{ stroke: "var(--chart-grid)" }}
           />
-        ) : (
+        ) : null}
+        {bands.length > 0 ? (
           <g mask={roundedCaps ? `url(#${uid}-track)` : undefined}>
             {bandPaths.map((path, index) => {
               const item = bands[index];
@@ -426,15 +427,18 @@ function GaugePlot({
                   d={path}
                   width={band}
                   color={rangeColor(item)}
-                  opacity={needle ? 0.92 : 0.26}
-                  dimmed={focused != null && focused !== index}
+                  // In progress mode the bands behind the arc would show as a
+                  // patchwork of tints next to it, so they stay invisible hit areas
+                  // and only appear while explored.
+                  opacity={needle ? 0.92 : focused === index ? 0.32 : 0}
+                  dimmed={needle && focused != null && focused !== index}
                   onEnter={(event) => nav.hover(index, event)}
                   onLeave={nav.leave}
                 />
               );
             })}
           </g>
-        )}
+        ) : null}
 
         {!needle && fraction > 0 ? (
           <path

package/src/containers/banner/banner.tsx

@@ -1,36 +1,39 @@
 import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { statusIcon } from "../../atoms/internal/status-icons.js";
 import { cn } from "../../utils/cn.js";
 
 export type BannerTone = "info" | "success" | "warning" | "danger";
 
 const toneClasses: Record<BannerTone, string> = {
-  info: "bg-accent-soft",
+  info: "bg-info-soft",
   success: "bg-success-soft",
   warning: "bg-warning-soft",
   danger: "bg-danger-soft",
 };
 
 const toneIconClasses: Record<BannerTone, string> = {
-  info: "text-accent-ink",
+  info: "text-info",
   success: "text-success",
   warning: "text-warning",
   danger: "text-danger",
 };
 
 /**
- * `info`/`success` are non-urgent notices (`role=status`, polite live region).
- * `warning`/`danger` need attention (`role=alert`, assertive live region).
+ * Only `danger` interrupts (`role=alert`, assertive live region); every other tone is a polite
+ * `role=status` notice.
  */
 const toneRole: Record<BannerTone, "status" | "alert"> = {
   info: "status",
   success: "status",
-  warning: "alert",
+  warning: "status",
   danger: "alert",
 };
 
-export interface BannerProps extends Omit<ComponentPropsWithoutRef<"div">, "role"> {
+export interface BannerProps extends Omit<ComponentPropsWithoutRef<"div">, "role" | "title"> {
   tone?: BannerTone;
-  /** Decorative icon on the left; marked `aria-hidden`. */
+  /** Bold first line above the content. */
+  title?: ReactNode;
+  /** Decorative icon on the left; marked `aria-hidden`. Defaults to a glyph for the tone; `null` hides it. */
   icon?: ReactNode;
   /** Actions on the right, e.g. a retry button. */
   action?: ReactNode;
@@ -38,12 +41,14 @@ export interface BannerProps extends Omit<ComponentPropsWithoutRef<"div">, "role
 
 export function Banner({
   tone = "info",
+  title,
   icon,
   action,
   className,
   children,
   ...props
 }: BannerProps) {
+  const resolvedIcon = icon === undefined ? statusIcon(tone) : icon;
   return (
     <div
       role={toneRole[tone]}
@@ -54,12 +59,15 @@ export function Banner({
       )}
       {...props}
     >
-      {icon ? (
+      {resolvedIcon ? (
         <span aria-hidden="true" className={cn("mt-0.5 shrink-0", toneIconClasses[tone])}>
-          {icon}
+          {resolvedIcon}
         </span>
       ) : null}
-      <div className="min-w-0 flex-[1_1_14rem] break-words">{children}</div>
+      <div className="min-w-0 flex-[1_1_14rem] break-words">
+        {title ? <p className="font-semibold">{title}</p> : null}
+        {children}
+      </div>
       {action ? (
         <div className="ml-auto flex shrink-0 flex-wrap items-center gap-1.5">{action}</div>
       ) : null}

package/src/containers/confirm-action/confirm-action.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+import { useEffect, useId, useRef, useState } from "react";
+import { Button, type ButtonVariant } from "../../atoms/button/button.js";
+import { useUiStrings } from "../../i18n/index.js";
+import { cn } from "../../utils/cn.js";
+import { Banner } from "../banner/banner.js";
+import { type ConfirmResult, runConfirm } from "./model.js";
+
+export interface ConfirmActionProps {
+  /** Trigger label, a verb in the user's words ("Cancel order"). */
+  label: string;
+  /** What will happen, said plainly, shown before the user commits. */
+  consequence: string;
+  /** Label of the destructive button. Defaults to the localized "Confirm". */
+  confirmLabel?: string;
+  cancelLabel?: string;
+  /** Runs on confirm. Return `{ ok: false, error }` or throw to keep the step open with a message. */
+  onConfirm: () => Promise<ConfirmResult> | Promise<void>;
+  triggerVariant?: ButtonVariant;
+  className?: string;
+}
+
+/** Inline two-step confirmation for a destructive action; no modal, no lost context. */
+export function ConfirmAction({
+  label,
+  consequence,
+  confirmLabel,
+  cancelLabel,
+  onConfirm,
+  triggerVariant = "secondary",
+  className,
+}: ConfirmActionProps) {
+  const strings = useUiStrings();
+  const consequenceId = useId();
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const wasConfirming = useRef(false);
+  const [confirming, setConfirming] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [failure, setFailure] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (wasConfirming.current && !confirming) triggerRef.current?.focus();
+    wasConfirming.current = confirming;
+  }, [confirming]);
+
+  async function confirm(): Promise<void> {
+    setBusy(true);
+    setFailure(null);
+    const outcome = await runConfirm(onConfirm, strings.actionFailed);
+    setBusy(false);
+    if (outcome.status === "failed") setFailure(outcome.message);
+    else setConfirming(false);
+  }
+
+  if (!confirming) {
+    return (
+      <div className={cn("flex flex-col gap-2", className)}>
+        {failure === null ? null : <Banner tone="danger">{failure}</Banner>}
+        <Button ref={triggerRef} variant={triggerVariant} onClick={() => setConfirming(true)}>
+          {label}
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <fieldset
+      aria-describedby={consequenceId}
+      className={cn("m-0 flex min-w-0 flex-col gap-3 border-0 p-0", className)}
+    >
+      <legend className="sr-only">{label}</legend>
+      <p id={consequenceId} className="text-body text-ink">
+        {consequence}
+      </p>
+      {failure === null ? null : <Banner tone="danger">{failure}</Banner>}
+      <div className="flex flex-wrap gap-2">
+        <Button
+          variant="danger"
+          loading={busy}
+          loadingLabel={strings.processing}
+          onClick={() => void confirm()}
+        >
+          {confirmLabel ?? strings.confirm}
+        </Button>
+        <Button variant="secondary" disabled={busy} autoFocus onClick={() => setConfirming(false)}>
+          {cancelLabel ?? strings.cancel}
+        </Button>
+      </div>
+    </fieldset>
+  );
+}

package/src/containers/confirm-action/index.ts

@@ -0,0 +1,2 @@
+export * from "./confirm-action.js";
+export type { ConfirmResult } from "./model.js";

package/src/containers/confirm-action/model.ts

@@ -0,0 +1,17 @@
+export type ConfirmResult = { ok: true } | { ok: false; error: string };
+
+export type ConfirmOutcome = { status: "done" } | { status: "failed"; message: string };
+
+/** Runs the confirmed action and folds a returned failure or a thrown error into one outcome. */
+export async function runConfirm(
+  onConfirm: () => Promise<ConfirmResult> | Promise<void>,
+  fallbackMessage: string,
+): Promise<ConfirmOutcome> {
+  try {
+    const result = (await onConfirm()) as ConfirmResult | undefined;
+    if (result !== undefined && !result.ok) return { status: "failed", message: result.error };
+    return { status: "done" };
+  } catch {
+    return { status: "failed", message: fallbackMessage };
+  }
+}

package/src/containers/index.ts

@@ -5,6 +5,7 @@ export * from "./carousel/index.js";
 export * from "./cell/index.js";
 export * from "./cols/index.js";
 export * from "./comment/index.js";
+export * from "./confirm-action/index.js";
 export * from "./data-grid/index.js";
 export * from "./description-list/index.js";
 export * from "./facts/index.js";
@@ -18,6 +19,7 @@ export * from "./kpi/index.js";
 export * from "./kpi-group/index.js";
 export * from "./page-header/index.js";
 export * from "./resizable/index.js";
+export * from "./responsive-list/index.js";
 export * from "./scrolly/index.js";
 export * from "./settings-layout/index.js";
 export * from "./settings-row/index.js";

package/src/containers/responsive-list/index.ts

@@ -0,0 +1 @@
+export * from "./responsive-list.js";

package/src/containers/responsive-list/responsive-list.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { useUiStrings } from "../../i18n/index.js";
+import { cn } from "../../utils/cn.js";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeaderCell,
+  TableRow,
+} from "../table/table.js";
+
+export interface ResponsiveListColumn<T> {
+  key: string;
+  header: string;
+  cell: (item: T) => ReactNode;
+  /** Title of the stacked card. Defaults to the first column. */
+  primary?: boolean;
+  align?: "start" | "end";
+}
+
+export interface ResponsiveListProps<T> {
+  /** Accessible name of the table and of the card list. */
+  caption: string;
+  items: readonly T[];
+  columns: readonly ResponsiveListColumn<T>[];
+  rowKey: (item: T) => string;
+  /** Per-row actions: a last table column, and a footer row on each card. */
+  renderActions?: (item: T) => ReactNode;
+  /** Header of the actions column. Defaults to the localized "Actions". */
+  actionsHeader?: string;
+  rowClassName?: (item: T) => string | undefined;
+  className?: string;
+}
+
+/** A table from `md` up and a stack of cards below it, from one column definition. */
+export function ResponsiveList<T>({
+  caption,
+  items,
+  columns,
+  rowKey,
+  renderActions,
+  actionsHeader,
+  rowClassName,
+  className,
+}: ResponsiveListProps<T>) {
+  const strings = useUiStrings();
+  const primary = columns.find((column) => column.primary) ?? columns[0];
+  const details = columns.filter((column) => column !== primary);
+
+  return (
+    <div className={cn("min-w-0", className)}>
+      <div className="hidden rounded-card border-card shadow-card surface-card md:block">
+        <Table>
+          <caption className="sr-only">{caption}</caption>
+          <TableHead>
+            <TableRow className="hover:bg-transparent">
+              {columns.map((column) => (
+                <TableHeaderCell key={column.key} scope="col" alignRight={column.align === "end"}>
+                  {column.header}
+                </TableHeaderCell>
+              ))}
+              {renderActions ? (
+                <TableHeaderCell scope="col" alignRight>
+                  {actionsHeader ?? strings.actions}
+                </TableHeaderCell>
+              ) : null}
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {items.map((item) => (
+              <TableRow
+                key={rowKey(item)}
+                data-row-key={rowKey(item)}
+                className={rowClassName?.(item)}
+              >
+                {columns.map((column) => (
+                  <TableCell key={column.key} alignRight={column.align === "end"}>
+                    {column.cell(item)}
+                  </TableCell>
+                ))}
+                {renderActions ? (
+                  <TableCell alignRight>
+                    <div className="flex flex-wrap justify-end gap-2">{renderActions(item)}</div>
+                  </TableCell>
+                ) : null}
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </div>
+      <ul aria-label={caption} className="m-0 flex list-none flex-col gap-density p-0 md:hidden">
+        {items.map((item) => (
+          <li
+            key={rowKey(item)}
+            data-row-key={rowKey(item)}
+            className={cn(
+              "flex min-w-0 flex-col gap-3 rounded-card border-card p-card shadow-card surface-card",
+              rowClassName?.(item),
+            )}
+          >
+            <div className="min-w-0 font-semibold text-[15px] text-ink [overflow-wrap:anywhere]">
+              {primary?.cell(item)}
+            </div>
+            {details.length > 0 ? (
+              <dl className="m-0 flex flex-col gap-2">
+                {details.map((column) => (
+                  <div key={column.key} className="flex items-baseline justify-between gap-4">
+                    <dt className="shrink-0 text-ink-3 text-meta">{column.header}</dt>
+                    <dd className="m-0 min-w-0 text-right text-body text-ink [overflow-wrap:anywhere]">
+                      {column.cell(item)}
+                    </dd>
+                  </div>
+                ))}
+              </dl>
+            ) : null}
+            {renderActions ? (
+              <div className="flex flex-wrap gap-2">{renderActions(item)}</div>
+            ) : null}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

package/src/forms/field/field.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { cloneElement, isValidElement, type ReactElement, useId } from "react";
+import { useUiStrings } from "../../i18n/index.js";
 import { cn } from "../../utils/cn.js";
 import { Label } from "../label/index.js";
 
@@ -13,13 +14,17 @@ interface ControlProps {
 export interface FieldProps {
   label: string;
   hint?: string;
-  error?: string;
+  /** Message under the control; `null` and `undefined` mean no error. */
+  error?: string | null;
+  /** Marks the field as optional by appending the localized marker to the label. */
+  optional?: boolean;
   id?: string;
   children: ReactElement<ControlProps>;
   className?: string;
 }
 
-export function Field({ label, hint, error, id, children, className }: FieldProps) {
+export function Field({ label, hint, error, optional, id, children, className }: FieldProps) {
+  const strings = useUiStrings();
   const generatedId = useId();
   const controlId = id ?? generatedId;
   const hintId = hint ? `${controlId}-hint` : undefined;
@@ -36,7 +41,10 @@ export function Field({ label, hint, error, id, children, className }: FieldProp
 
   return (
     <div className={cn("flex min-w-0 flex-col gap-1.25", className)}>
-      <Label htmlFor={controlId}>{label}</Label>
+      <Label htmlFor={controlId}>
+        {label}
+        {optional ? <span className="font-normal text-ink-3"> ({strings.optional})</span> : null}
+      </Label>
       {control}
       {hint ? (
         <p id={hintId} className="text-meta text-ink-3">

package/src/i18n/index.ts

@@ -0,0 +1,2 @@
+export * from "./strings.js";
+export * from "./ui-strings-provider.js";

package/src/i18n/strings.ts

@@ -0,0 +1,44 @@
+export interface UiStrings {
+  retry: string;
+  close: string;
+  loading: string;
+  optional: string;
+  cancel: string;
+  confirm: string;
+  processing: string;
+  correlationPrefix: string;
+  actionFailed: string;
+  somethingWrong: string;
+  actions: string;
+}
+
+export type UiLocale = "en" | "es";
+
+export const uiStrings = {
+  en: {
+    retry: "Retry",
+    close: "Close",
+    loading: "Loading",
+    optional: "optional",
+    cancel: "Cancel",
+    confirm: "Confirm",
+    processing: "Processing…",
+    correlationPrefix: "ID:",
+    actionFailed: "The action could not be completed. Try again.",
+    somethingWrong: "Something went wrong. Try again.",
+    actions: "Actions",
+  },
+  es: {
+    retry: "Reintentar",
+    close: "Cerrar",
+    loading: "Cargando",
+    optional: "opcional",
+    cancel: "Cancelar",
+    confirm: "Confirmar",
+    processing: "Procesando…",
+    correlationPrefix: "ID:",
+    actionFailed: "No se pudo completar la acción. Inténtalo de nuevo.",
+    somethingWrong: "Algo salió mal. Inténtalo de nuevo.",
+    actions: "Acciones",
+  },
+} as const satisfies Record<UiLocale, UiStrings>;

package/src/i18n/ui-strings-provider.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+import { createContext, type ReactNode, useContext, useMemo } from "react";
+import { type UiLocale, type UiStrings, uiStrings } from "./strings.js";
+
+const UiStringsContext = createContext<UiStrings>(uiStrings.en);
+
+export interface UiStringsProviderProps {
+  /** Preset to start from. Without it the provider keeps the strings of its parent (default `en`). */
+  locale?: UiLocale;
+  /** Overrides applied on top of the preset. */
+  strings?: Partial<UiStrings>;
+  children: ReactNode;
+}
+
+export function UiStringsProvider({ locale, strings, children }: UiStringsProviderProps) {
+  const parent = useContext(UiStringsContext);
+  const value = useMemo<UiStrings>(
+    () => ({ ...(locale ? uiStrings[locale] : parent), ...strings }),
+    [locale, strings, parent],
+  );
+  return <UiStringsContext.Provider value={value}>{children}</UiStringsContext.Provider>;
+}
+
+export function useUiStrings(): UiStrings {
+  return useContext(UiStringsContext);
+}

package/src/overlays/dialog/dialog.tsx

@@ -3,6 +3,7 @@
 import * as DialogPrimitive from "@radix-ui/react-dialog";
 import { X } from "lucide-react";
 import type { ComponentPropsWithoutRef, HTMLAttributes } from "react";
+import { useUiStrings } from "../../i18n/index.js";
 import { cn } from "../../utils/cn.js";
 import {
   PreviousFocusProvider,
@@ -56,7 +57,7 @@ export function DialogContent({
   className,
   width = "md",
   blocking = false,
-  closeLabel = "Close",
+  closeLabel,
   container,
   children,
   onEscapeKeyDown,
@@ -66,6 +67,7 @@ export function DialogContent({
   ...props
 }: DialogContentProps) {
   const previousFocusRef = usePreviousFocus();
+  const strings = useUiStrings();
   return (
     <DialogPrimitive.Portal container={container}>
       <DialogPrimitive.Overlay className="fixed inset-0 z-70 bg-scrim" />
@@ -96,8 +98,8 @@ export function DialogContent({
         {children}
         {!blocking && (
           <DialogPrimitive.Close
-            aria-label={closeLabel}
-            className="absolute top-3 right-3 rounded-event p-1 text-ink-3 hover:text-ink"
+            aria-label={closeLabel ?? strings.close}
+            className="absolute top-3 right-3 rounded-event p-1 text-ink-3 hover:text-ink in-data-[density=touch]:top-0.5 in-data-[density=touch]:right-0.5 in-data-[density=touch]:p-3.5"
           >
             <X aria-hidden="true" className="size-4" />
           </DialogPrimitive.Close>

package/src/overlays/drawer/drawer.tsx

@@ -3,6 +3,7 @@
 import * as DialogPrimitive from "@radix-ui/react-dialog";
 import { X } from "lucide-react";
 import type { ComponentPropsWithoutRef } from "react";
+import { useUiStrings } from "../../i18n/index.js";
 import { cn } from "../../utils/cn.js";
 import {
   PreviousFocusProvider,
@@ -44,7 +45,7 @@ export interface DrawerContentProps
 export function DrawerContent({
   className,
   blocking = false,
-  closeLabel = "Close",
+  closeLabel,
   children,
   onEscapeKeyDown,
   onPointerDownOutside,
@@ -53,6 +54,7 @@ export function DrawerContent({
   ...props
 }: DrawerContentProps) {
   const previousFocusRef = usePreviousFocus();
+  const strings = useUiStrings();
   return (
     <DialogPrimitive.Portal>
       <DialogPrimitive.Overlay className="fixed inset-0 z-70 bg-scrim" />
@@ -82,8 +84,8 @@ export function DrawerContent({
         {children}
         {!blocking && (
           <DialogPrimitive.Close
-            aria-label={closeLabel}
-            className="absolute top-3 right-3 rounded-event p-1 text-ink-3 hover:text-ink"
+            aria-label={closeLabel ?? strings.close}
+            className="absolute top-3 right-3 rounded-event p-1 text-ink-3 hover:text-ink in-data-[density=touch]:top-0.5 in-data-[density=touch]:right-0.5 in-data-[density=touch]:p-3.5"
           >
             <X aria-hidden="true" className="size-4" />
           </DialogPrimitive.Close>

package/src/states/error-state/error-state.tsx

@@ -1,10 +1,16 @@
 "use client";
 
-import type { ReactNode } from "react";
+import { isValidElement, type ReactNode } from "react";
+import { useUiStrings } from "../../i18n/index.js";
 import { cn } from "../../utils/cn.js";
 
 export interface ErrorStateProps {
-  message: ReactNode;
+  /** Short headline. Wins over `message` as the headline when both are given. */
+  title?: ReactNode;
+  /** Explanation under the headline, in plain language. */
+  description?: ReactNode;
+  /** Headline when `title` is absent (kept for source compatibility). */
+  message?: ReactNode;
   /** Correlation code for support; never a raw exception. */
   correlationId?: ReactNode;
   /** Prefix shown before the correlation id. */
@@ -15,13 +21,19 @@ export interface ErrorStateProps {
 }
 
 export function ErrorState({
+  title,
+  description,
   message,
   correlationId,
-  correlationLabel = "ID:",
+  correlationLabel,
   onRetry,
-  retryLabel = "Retry",
+  retryLabel,
   className,
 }: ErrorStateProps) {
+  const strings = useUiStrings();
+  const headline = displayable(title) ?? displayable(message) ?? strings.somethingWrong;
+  const detail =
+    displayable(description) ?? (title === undefined ? undefined : displayable(message));
   return (
     <div
       role="alert"
@@ -31,11 +43,14 @@ export function ErrorState({
       )}
     >
       <p className="max-w-full font-semibold text-[14px] text-ink [overflow-wrap:anywhere]">
-        {message}
+        {headline}
       </p>
+      {detail ? (
+        <p className="max-w-[42ch] text-[13px] text-ink-3 [overflow-wrap:anywhere]">{detail}</p>
+      ) : null}
       {correlationId ? (
         <p className="max-w-full text-[11.5px] text-ink-3 tabular-nums [overflow-wrap:anywhere]">
-          {correlationLabel} {correlationId}
+          {correlationLabel ?? strings.correlationPrefix} {correlationId}
         </p>
       ) : null}
       {onRetry ? (
@@ -44,9 +59,17 @@ export function ErrorState({
           onClick={onRetry}
           className="mt-2 inline-flex h-control-sm cursor-pointer items-center rounded-input border-control bg-surface-control px-3 font-semibold text-[13px] text-ink hover:bg-surface-2"
         >
-          {retryLabel}
+          {retryLabel ?? strings.retry}
         </button>
       ) : null}
     </div>
   );
 }
+
+/** Strings, numbers and elements render; an Error or any other object is never shown raw. */
+function displayable(value: ReactNode): ReactNode {
+  if (value === null || value === undefined || typeof value === "boolean") return undefined;
+  if (typeof value === "string" || typeof value === "number") return value;
+  if (isValidElement(value) || Array.isArray(value)) return value;
+  return undefined;
+}