@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/popover/react/Popover.tsx

@@ -0,0 +1,202 @@
+"use client";
+
+import {
+  cloneElement,
+  isValidElement,
+  useCallback,
+  useId,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type MouseEvent,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { AnchoredPopover } from "../../shared/react/Popover";
+import { useControllableState } from "../../shared/react/useControllableState";
+import type {
+  PopoverAlign,
+  PopoverCloseReason,
+  PopoverLocaleText,
+  PopoverSide,
+  PopoverSlot,
+} from "../core/types";
+import { defaultPopoverText } from "./locale";
+import { cx } from "./props";
+
+export interface PopoverHandle {
+  open(): void;
+  close(): void;
+  /** The panel, while it is open. */
+  getElement(): HTMLElement | null;
+}
+
+/** Given to `children` when it is a function. */
+export interface PopoverRenderProps {
+  close(): void;
+}
+
+export interface PopoverProps {
+  /**
+   * The element that opens it. It is cloned with a ref and the ARIA attributes
+   * that tie it to the panel, so pass a single element that forwards both — any
+   * button in this library does.
+   */
+  trigger: ReactElement<{ ref?: Ref<HTMLElement>; [attribute: string]: unknown }>;
+  children?: ReactNode | ((props: PopoverRenderProps) => ReactNode);
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?(open: boolean, reason?: PopoverCloseReason): void;
+  /** Heading inside the panel, which also names it. */
+  title?: ReactNode;
+  description?: ReactNode;
+  /** Names the panel when there is no `title`. */
+  "aria-label"?: string;
+  /** Side of the trigger to open on, before flipping for space. Default `bottom`. */
+  side?: PopoverSide;
+  /** Default `start`. */
+  align?: PopoverAlign;
+  /** Distance from the trigger, in pixels. Default 6. */
+  gap?: number;
+  /** Cap the panel to the space available and let it scroll. Default false. */
+  scrollable?: boolean;
+  /** Move focus into the panel when it opens. Default true. */
+  autoFocus?: boolean;
+  id?: string;
+  className?: string;
+  classNames?: Partial<Record<PopoverSlot, string>>;
+  style?: CSSProperties;
+  localeText?: Partial<PopoverLocaleText>;
+  ref?: Ref<PopoverHandle>;
+}
+
+/**
+ * A panel anchored to the element that opens it, in the top layer, so it is
+ * never clipped by a scrolling parent. The browser provides light dismiss and
+ * Escape; focus moves into the panel and returns to the trigger on close.
+ *
+ * For a list of commands use the Menu, and for a short label on hover use the
+ * Tooltip. This is for everything else: a filter form, a colour picker, a bit
+ * of help text too long for a tooltip.
+ */
+export function Popover(props: PopoverProps) {
+  const {
+    ref,
+    trigger,
+    children,
+    open: openProp,
+    defaultOpen = false,
+    onOpenChange,
+    title,
+    description,
+    "aria-label": ariaLabel,
+    side = "bottom",
+    align = "start",
+    gap = 6,
+    scrollable = false,
+    autoFocus = true,
+    id: idProp,
+    className,
+    classNames,
+    style,
+    localeText,
+  } = props;
+
+  const reactId = useId();
+  const id = idProp ?? reactId;
+  const text = useMemo(() => ({ ...defaultPopoverText, ...localeText }), [localeText]);
+
+  const panelRef = useRef<HTMLDivElement>(null);
+  const [open, setOpenState] = useControllableState(openProp, defaultOpen);
+
+  const setOpen = useCallback(
+    (next: boolean, reason?: PopoverCloseReason) => {
+      setOpenState(next);
+      onOpenChange?.(next, reason);
+    },
+    [setOpenState, onOpenChange],
+  );
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      open: () => setOpen(true),
+      close: () => setOpen(false, "api"),
+      getElement: () => panelRef.current,
+    }),
+    [setOpen],
+  );
+
+  // The anchor is state, not a ref: the panel only renders once we have an
+  // element to position it against.
+  const [anchor, setAnchor] = useState<HTMLElement | null>(null);
+
+  const renderProps: PopoverRenderProps = { close: () => setOpen(false, "api") };
+  const content = typeof children === "function" ? children(renderProps) : children;
+
+  if (!isValidElement(trigger)) {
+    throw new Error("Popover: `trigger` must be a single React element.");
+  }
+
+  const triggerProps = {
+    "aria-haspopup": "dialog" as const,
+    "aria-expanded": open,
+    "aria-controls": open ? `${id}-panel` : undefined,
+    onClick: (event: MouseEvent<HTMLElement>) => {
+      (trigger.props as { onClick?: (event: MouseEvent<HTMLElement>) => void }).onClick?.(event);
+      if (event.defaultPrevented) return;
+      if (open) {
+        setOpen(false, "trigger");
+      } else {
+        setAnchor(event.currentTarget);
+        setOpen(true);
+      }
+    },
+  };
+
+  return (
+    <>
+      {cloneElement(trigger, triggerProps)}
+      {open && anchor && (
+        <AnchoredPopover
+          anchor={anchor}
+          onClose={() => setOpen(false, "outside")}
+          id={`${id}-panel`}
+          label={title ? undefined : (ariaLabel ?? text.label)}
+          labelledBy={title ? `${id}-title` : undefined}
+          describedBy={description ? `${id}-description` : undefined}
+          side={side}
+          align={align}
+          gap={gap}
+          fitHeight={scrollable}
+          autoFocus={autoFocus}
+          observeResize="self"
+          returnFocus
+          className={cx("pv-root", classNames?.root, className)}
+        >
+          {/* The popover element itself is the dialog; this only draws it. */}
+          <div ref={panelRef} className={cx("pv-panel", classNames?.panel)} style={style}>
+            {(title || description) && (
+              <div className={cx("pv-header", classNames?.header)}>
+                {title && (
+                  <p id={`${id}-title`} className={cx("pv-title", classNames?.title)}>
+                    {title}
+                  </p>
+                )}
+                {description && (
+                  <p id={`${id}-description`} className={cx("pv-description", classNames?.description)}>
+                    {description}
+                  </p>
+                )}
+              </div>
+            )}
+            <div className={cx("pv-body", classNames?.body)}>{content}</div>
+          </div>
+        </AnchoredPopover>
+      )}
+    </>
+  );
+}

package/source/components/popover/react/locale.ts

@@ -0,0 +1,5 @@
+import type { PopoverLocaleText } from "../core/types";
+
+export const defaultPopoverText: PopoverLocaleText = {
+  label: "More information",
+};

package/source/components/popover/react/props.ts

@@ -0,0 +1,4 @@
+export type { PopoverSlot } from "../core/types";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

package/source/components/popover/styles.css

@@ -0,0 +1,148 @@
+/*
+ * Popover styles.
+ *
+ * Tokens read the shared --gbs-* variables when they are set on an ancestor
+ * (set them on :root to theme every component at once) and fall back to the
+ * same default palette otherwise. Rules are unlayered: they beat a framework
+ * reset on specificity, and lose to anything you pass through `className`.
+ * With Tailwind v4, import this file after the framework and inside its
+ * components layer - see the README.
+ */
+
+.pv-root {
+  --pv-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
+  --pv-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+  --pv-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+  --pv-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+  --pv-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+  --pv-shadow: var(--gbs-shadow, var(--dg-shadow, 0 10px 30px -8px light-dark(rgb(0 0 0 / 0.18), rgb(0 0 0 / 0.6))));
+  --pv-radius: var(--gbs-radius, var(--dg-radius, 8px));
+  --pv-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+  --pv-px: 12px;
+  --pv-width: 280px;
+  --pv-duration: 140ms;
+
+  position: fixed;
+  inset: auto;
+  z-index: 60;
+  width: max-content;
+  max-width: min(var(--pv-width), calc(100vw - 16px));
+  margin: 0;
+  padding: 0;
+  overflow: auto;
+  overscroll-behavior: contain;
+  border: 1px solid var(--pv-border);
+  border-radius: var(--pv-radius);
+  background: var(--pv-bg);
+  color: var(--pv-fg);
+  box-shadow: var(--pv-shadow);
+  color-scheme: inherit;
+  font-size: var(--pv-font-size);
+  line-height: 1.5;
+  scrollbar-width: var(--gbs-scrollbar-width, thin);
+  scrollbar-color: var(--gbs-scrollbar-thumb, light-dark(#c4c4ca, #3f3f46))
+    var(--gbs-scrollbar-track, transparent);
+}
+
+:where(.dark, [data-theme="dark"]) .pv-root {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) .pv-root {
+  color-scheme: light;
+}
+
+:where(.pv-root) *,
+:where(.pv-root) *::before,
+:where(.pv-root) *::after {
+  box-sizing: border-box;
+}
+
+/* The panel is focused when it opens, which should not draw a ring unless
+   the person is actually navigating by keyboard. */
+.pv-root:focus {
+  outline: none;
+}
+.pv-root:focus-visible {
+  outline: 2px solid var(--pv-focus);
+  outline-offset: 2px;
+}
+
+.pv-root:popover-open {
+  animation: pv-in var(--pv-duration) ease;
+}
+
+/* Grows from the edge it is anchored to, so it reads as coming from the
+   trigger rather than appearing from nowhere. */
+@keyframes pv-in {
+  from {
+    opacity: 0;
+    translate: 0 -2px;
+  }
+}
+.pv-root[data-side="top"]:popover-open {
+  animation-name: pv-in-top;
+}
+@keyframes pv-in-top {
+  from {
+    opacity: 0;
+    translate: 0 2px;
+  }
+}
+.pv-root[data-side="left"]:popover-open {
+  animation-name: pv-in-left;
+}
+@keyframes pv-in-left {
+  from {
+    opacity: 0;
+    translate: 2px 0;
+  }
+}
+.pv-root[data-side="right"]:popover-open {
+  animation-name: pv-in-right;
+}
+@keyframes pv-in-right {
+  from {
+    opacity: 0;
+    translate: -2px 0;
+  }
+}
+
+/* -------------------------------------------------------------- content */
+
+.pv-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: var(--pv-px);
+}
+
+.pv-header {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+.pv-title {
+  margin: 0;
+  font-size: 1.02em;
+  font-weight: 600;
+}
+.pv-description {
+  margin: 0;
+  color: var(--pv-muted);
+}
+
+.pv-body:empty {
+  display: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .pv-root:popover-open {
+    animation: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .pv-root {
+    border: 1px solid CanvasText;
+  }
+}

package/source/components/progress/README.md

@@ -0,0 +1,38 @@
+# Progress and CircularProgress
+
+A bar, or a ring, for something with a known end: an upload, an import, a
+quota. For React 19, styled to match the rest of the library. No runtime
+dependencies besides React.
+
+```ts
+import { CircularProgress, Progress } from "@/components/progress";
+import "@/components/progress/styles.css";
+```
+
+```tsx
+<Progress label="Uploading report.pdf" value={62} showValue />
+<Progress value={null} label="Preparing export" />            {/* length unknown */}
+<Progress value={92} max={100} variant="warning" label="Storage" size="sm" />
+
+<CircularProgress value={62} size={56} showValue />
+```
+
+**Progress:** `value` (`number | null`), `max`, `label`, `showValue`,
+`valueText`, `variant` (`accent` `success` `warning` `danger`), `size` (`sm`
+`md` `lg`), `classNames` (`root` `header` `label` `value` `track` `bar`),
+`localeText`, `ref`, and every `<div>` attribute.
+
+**CircularProgress:** the same value props, plus `size` (pixels), `thickness`,
+`showValue` or `children` for the middle.
+
+`value={null}` means the length is not known yet, which is a different thing
+from zero: the bar sweeps, and `aria-valuenow` is left off entirely, which is
+what makes a screen reader say "busy" instead of reading out a zero.
+
+Use a **Spinner** when there is nothing to measure at all. A progress bar that
+spends its life indeterminate is a spinner drawn as a promise it cannot keep.
+
+`describeProgress` and `stepFraction` are exported from the framework-free
+`core`. `describeProgress` is where a `max` of zero stops being a division by
+zero, and where the drawn fraction stays unrounded so a 99.6% bar does not
+reach the end early.

package/source/components/progress/core/index.ts

@@ -0,0 +1,2 @@
+export { describeProgress, stepFraction } from "./progress";
+export type * from "./types";

package/source/components/progress/core/progress.ts

@@ -0,0 +1,40 @@
+import type { ProgressState } from "./types";
+
+/**
+ * What a progress bar knows about itself.
+ *
+ * Kept apart from the component because the two interesting cases are easy to
+ * get wrong and invisible when you do: a value of `null` is *unknown*, not
+ * zero, and a `max` of zero is a task with nothing in it, which must not become
+ * a division by zero shown as `NaN%`.
+ */
+export function describeProgress(
+  value: number | null | undefined,
+  max = 100,
+): ProgressState {
+  if (value === null || value === undefined || !Number.isFinite(value)) {
+    return { indeterminate: true, value: null, fraction: 0, percent: 0 };
+  }
+  const top = Number.isFinite(max) && max > 0 ? max : 0;
+  const clamped = Math.min(Math.max(value, 0), top || value);
+  const fraction = top === 0 ? 0 : clamped / top;
+  return {
+    indeterminate: false,
+    value: clamped,
+    fraction,
+    // Rounded for display only; the bar itself is drawn from `fraction`, so a
+    // 99.6% bar does not snap to full while the last bytes are still moving.
+    percent: Math.round(fraction * 100),
+  };
+}
+
+/**
+ * A step counter's fraction: "step 2 of 5" is 40%, not 20%.
+ *
+ * Off-by-one here is the classic wizard bug — the first step showing an empty
+ * bar, or the last showing one still short of full.
+ */
+export function stepFraction(step: number, total: number): number {
+  if (!Number.isFinite(step) || !Number.isFinite(total) || total <= 0) return 0;
+  return Math.min(Math.max(step, 0), total) / total;
+}

package/source/components/progress/core/types.ts

@@ -0,0 +1,23 @@
+export type ProgressVariant = "accent" | "success" | "warning" | "danger";
+
+export type ProgressSize = "sm" | "md" | "lg";
+
+export interface ProgressState {
+  /** The task is running but its length is unknown. */
+  indeterminate: boolean;
+  /** Clamped into range, or null when indeterminate. */
+  value: number | null;
+  /** 0 to 1, for drawing. */
+  fraction: number;
+  /** 0 to 100, rounded, for reading. */
+  percent: number;
+}
+
+export interface ProgressLocaleText {
+  /** The accessible name when none is given. */
+  label: string;
+  /** What a screen reader reads instead of the raw number. */
+  valueText(percent: number): string;
+  /** Announced while the length is unknown. */
+  working: string;
+}

package/source/components/progress/index.ts

@@ -0,0 +1,7 @@
+export { Progress } from "./react/Progress";
+export type { ProgressProps } from "./react/Progress";
+export { CircularProgress } from "./react/CircularProgress";
+export type { CircularProgressProps } from "./react/CircularProgress";
+export { defaultProgressText } from "./react/locale";
+export type { CircularProgressSlot, ProgressSlot } from "./react/props";
+export * from "./core";