@eifi1/ui-kit 0.11.0 → 0.12.0

package/src/components/form-actions.tsx

@@ -0,0 +1,191 @@
+import { isValidElement } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+import { Button, Spinner, type ButtonVariant } from "./ui";
+
+/** The words {@link FormActions} renders on its own behalf — the `form` namespace. */
+export interface FormActionsLabels {
+  save: string;
+  cancel: string;
+}
+
+export const DEFAULT_FORM_ACTIONS_LABELS: FormActionsLabels = {
+  save: "Save",
+  cancel: "Cancel",
+};
+
+export type FormActionsAlign = "start" | "center" | "end" | "between";
+
+/**
+ * Where the row sits:
+ *  - `inline` (default): under the form's last field, `pt-4` above it.
+ *  - `sticky`: stuck to the bottom of the scrolling page or pane, on the surface
+ *    colour with a rule above, clear of the phone's home indicator — for a long form
+ *    whose Save should not be a scroll away.
+ *  - `dialog`: no spacing of its own, for a dialog's footer slot (DialogFrame,
+ *    FullBleedDialog's `footer`), which already pads and rules it.
+ */
+export type FormActionsPlacement = "inline" | "sticky" | "dialog";
+
+/** The start-side action of {@link FormActionsProps.destructive}, as data. */
+export interface FormActionsDestructive {
+  label: ReactNode;
+  onClick: () => void;
+  disabled?: boolean;
+  /** See Button's `disabledReason`. */
+  disabledReason?: ReactNode;
+}
+
+const ALIGN_CLASS: Record<FormActionsAlign, string> = {
+  start: "justify-start",
+  center: "justify-center",
+  end: "justify-end",
+  between: "justify-between",
+};
+
+const PLACEMENT_CLASS: Record<FormActionsPlacement, string> = {
+  inline: "pt-4",
+  sticky: "sticky bottom-0 z-10 border-t border-[var(--border)] bg-[var(--bg-surface)] pt-3",
+  dialog: "",
+};
+
+export interface FormActionsProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+  /** Called by Cancel. Omitted: no Cancel button (a form that only saves). */
+  onCancel?: () => void;
+  /**
+   * Given: the save button is `type="button"` and calls this — for a dialog or a row
+   * that saves from a handler. Omitted: it is `type="submit"` and submits the
+   * enclosing `<form>` (or the one named by {@link form}).
+   */
+  onSubmit?: () => void;
+  /** The save button's text. Default `form.save` from the provider, else "Save". */
+  submitLabel?: ReactNode;
+  /** The cancel button's text. Default `form.cancel` from the provider, else "Cancel". */
+  cancelLabel?: ReactNode;
+  /** The save button's text while `pending` ("Saving…"). Default: `submitLabel`. */
+  pendingLabel?: ReactNode;
+  /**
+   * The save is running: a spinner in the save button, `aria-busy` on it, and the
+   * button disabled, so a second click cannot send the form twice. Cancel stays
+   * usable.
+   */
+  pending?: boolean;
+  /** Disable save for a reason of the form's own (an unbalanced entry). */
+  submitDisabled?: boolean;
+  /** Why save is disabled — see Button's `disabledReason`. Keeps it focusable. */
+  submitDisabledReason?: ReactNode;
+  /** The save button's variant. Default `brand`; `danger` for a save that destroys
+   *  (kastlan's `destructive` flag on its own FormActions). */
+  submitVariant?: ButtonVariant;
+  /**
+   * A destructive action at the START of the row, apart from Save and Cancel — the
+   * "Delete" of an edit dialog. Pass `{ label, onClick }` for the kit's quiet danger
+   * button, or an element of your own (a {@link DangerConfirm}, say). With it the row
+   * is `between`-aligned unless `align` says otherwise.
+   */
+  destructive?: ReactNode | FormActionsDestructive;
+  /** Horizontal alignment. Default `end` (`between` with a `destructive` action). */
+  align?: FormActionsAlign;
+  /** See {@link FormActionsPlacement}. Default `inline`. */
+  placement?: FormActionsPlacement;
+  /** The `id` of the `<form>` the save button submits, when the row is rendered
+   *  outside it (a dialog's footer slot). */
+  form?: string;
+  /** Extra actions, placed before Cancel. */
+  children?: ReactNode;
+}
+
+function isDestructiveData(value: unknown): value is FormActionsDestructive {
+  return typeof value === "object" && value !== null && !isValidElement(value) && "onClick" in value;
+}
+
+/**
+ * The Save / Cancel row every form, wizard-step form and dialog ends in — kastlan's
+ * `FormActions`, with the labels from the provider, a pending state and a place for
+ * the destructive action.
+ *
+ * ```tsx
+ * <form onSubmit={form.handleSubmit(save)}>
+ *   …
+ *   <FormActions onCancel={close} pending={mutation.isPending} />
+ * </form>
+ * ```
+ *
+ * The spinner is the kit's {@link Spinner}, drawn inside the button with `label={null}`
+ * so the button's name stays its text; `aria-busy` is what says it is working.
+ */
+export function FormActions({
+  onCancel,
+  onSubmit,
+  submitLabel,
+  cancelLabel,
+  pendingLabel,
+  pending = false,
+  submitDisabled = false,
+  submitDisabledReason,
+  submitVariant = "brand",
+  destructive,
+  align,
+  placement = "inline",
+  form,
+  children,
+  className,
+  style,
+  ...rest
+}: FormActionsProps) {
+  const labels = useKitLabels("form", DEFAULT_FORM_ACTIONS_LABELS);
+  const hasDestructive = destructive !== undefined && destructive !== null && destructive !== false;
+  const justify = align ?? (hasDestructive ? "between" : "end");
+  const start = !hasDestructive ? null : isDestructiveData(destructive) ? (
+    <Button
+      type="button"
+      variant="ghost"
+      tone="danger"
+      onClick={destructive.onClick}
+      disabled={destructive.disabled}
+      disabledReason={destructive.disabledReason}
+    >
+      {destructive.label}
+    </Button>
+  ) : (
+    destructive
+  );
+  const saveLabel = submitLabel ?? labels.save;
+
+  return (
+    <div
+      data-slot="form-actions"
+      data-placement={placement}
+      {...rest}
+      style={
+        placement === "sticky"
+          ? { paddingBottom: "max(0.75rem, env(safe-area-inset-bottom))", ...style }
+          : style
+      }
+      className={cn("flex flex-wrap items-center gap-2", ALIGN_CLASS[justify], PLACEMENT_CLASS[placement], className)}
+    >
+      {start && <div className="me-auto flex items-center gap-2">{start}</div>}
+      <div className="flex flex-wrap items-center gap-2">
+        {children}
+        {onCancel && (
+          <Button type="button" variant="secondary" onClick={onCancel}>
+            {cancelLabel ?? labels.cancel}
+          </Button>
+        )}
+        <Button
+          type={onSubmit ? "button" : "submit"}
+          form={form}
+          onClick={onSubmit}
+          variant={submitVariant}
+          disabled={pending || submitDisabled}
+          disabledReason={pending ? undefined : submitDisabledReason}
+          aria-busy={pending || undefined}
+        >
+          {pending && <Spinner label={null} className="size-4" />}
+          {pending && pendingLabel !== undefined ? pendingLabel : saveLabel}
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/components/image-grid.tsx

@@ -0,0 +1,181 @@
+import { useState } from "react";
+import type { ComponentPropsWithoutRef, CSSProperties, ReactNode } from "react";
+import { FileText } from "lucide-react";
+
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+import type { AuthedFetcher } from "../hooks/use-authed-src";
+import { AuthedImage } from "./authed-image";
+import { Lightbox, imageItemKind } from "./lightbox";
+import type { ImageItem, LightboxLabels } from "./lightbox";
+
+export interface ImageGridLabels {
+  /** The list's accessible name. */
+  list: string;
+  /** An open button's name when an item's `alt` is empty: "Image 3 of 7". */
+  item: (index: number, count: number) => string;
+  /** The name of the group of per-image actions, given the image's name. */
+  actions: (name: string) => string;
+}
+
+export const DEFAULT_IMAGE_GRID_LABELS: ImageGridLabels = {
+  list: "Images",
+  item: (index, count) => `Image ${index} of ${count}`,
+  actions: (name) => `Actions for ${name}`,
+};
+
+export interface ImageGridProps extends Omit<ComponentPropsWithoutRef<"ul">, "children"> {
+  items: readonly ImageItem[];
+  /** The app's authenticated GET — thumbnails and the lightbox fetch through it. Only
+   *  images are fetched for the grid; a file (PDF) tile shows its icon and name. */
+  fetcher?: AuthedFetcher | null;
+  /**
+   * Per-image actions — a delete, an edit. Rendered BESIDE the open button (on top of
+   * the thumbnail's corner), never inside it: a button inside a button is invalid HTML
+   * and a screen reader flattens it into the outer one's name, where it cannot be
+   * reached. Use `IconButton variant="overlay"` for controls that sit on a photo.
+   */
+  renderActions?: (item: ImageItem, index: number) => ReactNode;
+  /**
+   * What a tile's click does. Left out, the grid opens its own {@link Lightbox} on that
+   * image. Given, the grid opens nothing — for a caller that keeps the lightbox's
+   * index in the URL, or that opens something else.
+   */
+  onOpen?: (index: number) => void;
+  /**
+   * A fixed column count. Left out, the grid is responsive: as many columns of at
+   * least {@link minTileSize} px as fit, so the same grid is three across in a card on
+   * a phone and eight across on a desktop page — no breakpoints to choose.
+   */
+  columns?: number;
+  /** The smallest a tile may be in the responsive layout. Default 96 (px). */
+  minTileSize?: number;
+  /** `square` (default) crops to a square; `video` to 16:9; `auto` keeps each image's
+   *  own proportions (a floor plan), within a square-ish box. */
+  aspect?: "square" | "video" | "auto";
+  /** Props for the built-in lightbox (ignored with {@link onOpen}). */
+  lightbox?: {
+    loop?: boolean;
+    zoom?: boolean;
+    download?: boolean;
+    onDownload?: (item: ImageItem, index: number) => void;
+    labels?: Partial<LightboxLabels>;
+  };
+  labels?: Partial<ImageGridLabels>;
+}
+
+const ASPECT_CLASS = {
+  square: "aspect-square",
+  video: "aspect-video",
+  auto: "aspect-[4/3]",
+} as const;
+
+/**
+ * A grid of thumbnails that open in a {@link Lightbox} — kastlan's room and defect
+ * photos (room-inspector, unit-rooms-tab) and its floor plans (unit-floor-plan), each
+ * of which drew its own `grid grid-cols-N` of `<img>` that nothing could open, with no
+ * loading state and nowhere to put a delete.
+ *
+ * Each tile is a real `<button>` named by the image's alt, with the actions beside it
+ * and the caption below it — outside the button, so the name stays the alt and the
+ * caption is read once. Placeholders come from {@link AuthedImage}: a skeleton while
+ * loading, a "couldn't load" tile on failure.
+ */
+export function ImageGrid({
+  items,
+  fetcher,
+  renderActions,
+  onOpen,
+  columns,
+  minTileSize = 96,
+  aspect = "square",
+  lightbox,
+  labels: labelsProp,
+  className,
+  style,
+  ...rest
+}: ImageGridProps) {
+  const labels = useKitLabels("imageGrid", DEFAULT_IMAGE_GRID_LABELS, labelsProp);
+  const [openIndex, setOpenIndex] = useState<number | null>(null);
+  const count = items.length;
+
+  const gridStyle: CSSProperties = {
+    gridTemplateColumns:
+      columns !== undefined
+        ? `repeat(${columns}, minmax(0, 1fr))`
+        : `repeat(auto-fill, minmax(min(${minTileSize}px, 100%), 1fr))`,
+    ...style,
+  };
+
+  return (
+    <>
+      <ul
+        aria-label={labels.list}
+        {...rest}
+        className={cn("grid gap-2", className)}
+        style={gridStyle}
+      >
+        {items.map((item, i) => {
+          const name = item.alt || labels.item(i + 1, count);
+          const kind = imageItemKind(item);
+          const actions = renderActions?.(item, i);
+          return (
+            <li key={item.key ?? item.src} className="relative min-w-0">
+              <button
+                type="button"
+                aria-label={name}
+                onClick={() => (onOpen ? onOpen(i) : setOpenIndex(i))}
+                className={cn(
+                  "block w-full overflow-hidden rounded-md border border-[var(--border)] bg-[var(--bg-hover)]",
+                  "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--brand)]",
+                  ASPECT_CLASS[aspect],
+                )}
+              >
+                {kind === "file" ? (
+                  <span className="flex h-full w-full flex-col items-center justify-center gap-1 p-2 text-center text-xs text-[var(--text-secondary)]">
+                    <FileText aria-hidden className="size-6 shrink-0 text-[var(--text-muted)]" />
+                    <span aria-hidden className="line-clamp-2 break-all">{item.fileName ?? item.alt}</span>
+                  </span>
+                ) : (
+                  <AuthedImage
+                    src={item.thumbnailSrc ?? item.src}
+                    // The button is named already; the picture inside it is decoration
+                    // to a reader, or the name would be read twice.
+                    alt=""
+                    fetcher={fetcher}
+                    loading="lazy"
+                    wrapperClassName="h-full w-full"
+                    className={cn("h-full w-full", aspect === "auto" ? "object-contain" : "object-cover")}
+                  />
+                )}
+              </button>
+              {actions !== undefined && actions !== null && actions !== false && (
+                <div
+                  role="group"
+                  aria-label={labels.actions(name)}
+                  className="absolute end-1 top-1 flex gap-1"
+                >
+                  {actions}
+                </div>
+              )}
+              {item.caption !== undefined && item.caption !== null && item.caption !== false && (
+                <div className="mt-1 line-clamp-2 text-xs text-[var(--text-secondary)]">{item.caption}</div>
+              )}
+            </li>
+          );
+        })}
+      </ul>
+      {!onOpen && (
+        <Lightbox
+          open={openIndex !== null}
+          onClose={() => setOpenIndex(null)}
+          items={items}
+          index={openIndex ?? 0}
+          onIndexChange={setOpenIndex}
+          fetcher={fetcher}
+          {...lightbox}
+        />
+      )}
+    </>
+  );
+}