@kosmeo-ui/react 0.1.1 → 0.2.0

package/src/components/inputs/richTextEditor/index.tsx

@@ -50,8 +50,12 @@ const RichTextEditor = (props: RichTextEditorProps) => {
   const [charCount, setCharCount] = useState(0);
   const [isInitialized, setIsInitialized] = useState(false);
 
-  const fieldId =
-    props.id || `richtext-${Math.random().toString(36).substring(2, 9)}`;
+  // Stable across renders: the editor reads labelId once, when it's created.
+  const [generatedId] = useState(
+    () => `richtext-${Math.random().toString(36).substring(2, 9)}`
+  );
+  const fieldId = props.id || generatedId;
+  const labelId = `${fieldId}-label`;
 
   const cleanHtml = (html: string): string | undefined => {
     // Remove trailing empty <p></p> tags
@@ -79,6 +83,14 @@ const RichTextEditor = (props: RichTextEditorProps) => {
       }),
     ],
     content: props.value,
+    editorProps: {
+      attributes: {
+        "aria-multiline": "true",
+        ...(props.label
+          ? { "aria-labelledby": labelId }
+          : { "aria-label": props.placeholder ?? "Rich text editor" }),
+      },
+    },
     editable: !disabled,
     autofocus: props.autofocus,
     onUpdate: ({ editor }) => {
@@ -146,7 +158,7 @@ const RichTextEditor = (props: RichTextEditorProps) => {
     <div className={`k-richtext-container k-richtext-container-${size}`}>
       {props.label && (
         <div className="k-richtext-label-wrapper">
-          <label htmlFor={fieldId} className="k-richtext-label">
+          <label id={labelId} className="k-richtext-label">
             {props.label}
             {props.required && <MandatoryAsterisk />}
           </label>
@@ -165,6 +177,8 @@ const RichTextEditor = (props: RichTextEditorProps) => {
           <Tooltip content="Bold" position="top">
             <IconButton
               icon={faBold}
+              aria-label="Bold"
+              aria-pressed={editorState.isBold}
               size={size}
               variant={editorState.isBold ? "primary" : "secondary"}
               onClick={() => editor.chain().focus().toggleBold().run()}
@@ -174,6 +188,8 @@ const RichTextEditor = (props: RichTextEditorProps) => {
           <Tooltip content="Italic" position="top">
             <IconButton
               icon={faItalic}
+              aria-label="Italic"
+              aria-pressed={editorState.isItalic}
               size={size}
               variant={editorState.isItalic ? "primary" : "secondary"}
               onClick={() => editor.chain().focus().toggleItalic().run()}
@@ -183,6 +199,8 @@ const RichTextEditor = (props: RichTextEditorProps) => {
           <Tooltip content="Underline" position="top">
             <IconButton
               icon={faUnderline}
+              aria-label="Underline"
+              aria-pressed={editorState.isUnderlined}
               size={size}
               variant={editorState.isUnderlined ? "primary" : "secondary"}
               onClick={() => editor.chain().focus().toggleUnderline().run()}
@@ -193,6 +211,8 @@ const RichTextEditor = (props: RichTextEditorProps) => {
           <Tooltip content="Bullet List" position="top">
             <IconButton
               icon={faListUl}
+              aria-label="Bullet list"
+              aria-pressed={editorState.isBulletedList}
               size={size}
               variant={editorState.isBulletedList ? "primary" : "secondary"}
               onClick={() => editor.chain().focus().toggleBulletList().run()}
@@ -202,6 +222,8 @@ const RichTextEditor = (props: RichTextEditorProps) => {
           <Tooltip content="Numbered List" position="top">
             <IconButton
               icon={faListOl}
+              aria-label="Numbered list"
+              aria-pressed={editorState.isNumberedList}
               size={size}
               variant={editorState.isNumberedList ? "primary" : "secondary"}
               onClick={() => editor.chain().focus().toggleOrderedList().run()}
@@ -212,6 +234,7 @@ const RichTextEditor = (props: RichTextEditorProps) => {
           <Tooltip content="Clear Formatting" position="top">
             <IconButton
               icon={faTextSlash}
+              aria-label="Clear formatting"
               size={size}
               variant="secondary"
               onClick={() => {
@@ -234,6 +257,7 @@ const RichTextEditor = (props: RichTextEditorProps) => {
           >
             <IconButton
               icon={faCode}
+              aria-label={showHtml ? "Show editor" : "Show HTML"}
               size={size}
               variant={showHtml ? "primary" : "secondary"}
               onClick={() => setShowHtml(!showHtml)}

package/src/components/layout/borderedSection/index.tsx

@@ -7,6 +7,8 @@ export interface BorderedSectionProps {
   children: ReactNode;
   /** Optional title shown above the body. */
   title?: ReactNode;
+  /** Heading element for the title, to fit the page's heading outline. Defaults to `h3`. Looks the same at every level. */
+  as?: "h2" | "h3" | "h4";
   /** Right-aligned actions in the title row. Implies a title row even when `title` is empty. */
   actions?: ReactNode;
   /** Body layout. `"stack"` (default) stacks children; `"row"` lays them out as a horizontal flex strip. */
@@ -20,6 +22,7 @@ export interface BorderedSectionProps {
 const BorderedSection = ({
   children,
   title,
+  as: Heading = "h3",
   actions,
   layout = "stack",
   gap,
@@ -40,7 +43,7 @@ const BorderedSection = ({
       {showHeader && (
         <div className="k-bordered-section-header">
           {title !== undefined && (
-            <h3 className="k-bordered-section-title">{title}</h3>
+            <Heading className="k-bordered-section-title">{title}</Heading>
           )}
           {actions !== undefined && (
             <div className="k-bordered-section-actions">{actions}</div>

package/src/components/layout/card/styles.css

@@ -76,8 +76,30 @@
 }
 
 /* Padding Variants */
+/* Edge-to-edge content (tables, images): clip it to the rounded corners, and
+   give the header and footer their own padding instead. */
 .k-card-padding-none {
   padding: 0;
+  overflow: hidden;
+}
+
+.k-card-padding-none .k-card-header {
+  padding: 0.75rem 1rem;
+  margin-bottom: 0;
+}
+
+.k-card-padding-none .k-card-footer {
+  padding: 0.75rem 1rem;
+  margin-top: 0;
+}
+
+/* The card already draws the outer edge and the line under the header. */
+.k-card-padding-none .k-card-body > .k-table {
+  border: none;
+}
+
+.k-card-padding-none .k-card-body > .k-table thead th {
+  border-top: none;
 }
 
 .k-card-padding-small {

package/src/components/layout/sectionHeader/styles.css

@@ -82,8 +82,7 @@
 
 .k-section-header-subtitle {
   font-size: 0.8125rem;
-  color: var(--text-color);
-  opacity: 0.65;
+  color: var(--text-color-secondary);
 }
 
 .k-section-header-badges {

package/src/components/navigation/pagination/index.tsx

@@ -0,0 +1,134 @@
+"use client";
+
+import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
+import Select from "../../inputs/select/index.js";
+import { PropsWithSize } from "../../types.js";
+import { pageRange } from "./utils.js";
+import { useId } from "react";
+import "./styles.css";
+import {
+  faChevronLeft,
+  faChevronRight,
+} from "@fortawesome/free-solid-svg-icons";
+
+export interface PaginationProps extends PropsWithSize {
+  /** Current page, starting at 1. */
+  page: number;
+  /** Total number of pages. */
+  pageCount: number;
+  onPageChange: (page: number) => void;
+  /** Total item count. With `pageSize`, shows a "51–75 of 240" summary. */
+  total?: number;
+  /** Items per page. Needed for the summary and the page-size picker. */
+  pageSize?: number;
+  /** Page sizes to offer. With `onPageSizeChange`, shows a "Rows per page" picker. */
+  pageSizeOptions?: number[];
+  onPageSizeChange?: (pageSize: number) => void;
+  /** Pages shown either side of the current page before a "…" gap. Defaults to 1. */
+  siblingCount?: number;
+  /** Accessible name for the navigation landmark. Defaults to "Pagination". */
+  "aria-label"?: string;
+}
+
+const Pagination = ({
+  page,
+  pageCount,
+  onPageChange,
+  total,
+  pageSize,
+  pageSizeOptions,
+  onPageSizeChange,
+  siblingCount = 1,
+  size = "md",
+  "aria-label": ariaLabel = "Pagination",
+}: PaginationProps) => {
+  const pageSizeId = useId();
+  const lastPage = Math.max(pageCount, 1);
+  const current = Math.min(Math.max(page, 1), lastPage);
+
+  const goTo = (target: number) => {
+    if (target >= 1 && target <= lastPage && target !== current) {
+      onPageChange(target);
+    }
+  };
+
+  const summary =
+    total !== undefined && pageSize !== undefined
+      ? total === 0
+        ? "No results"
+        : `${(current - 1) * pageSize + 1}–${Math.min(current * pageSize, total)} of ${total.toLocaleString()}`
+      : undefined;
+
+  return (
+    <nav className={`k-pagination k-pagination-${size}`} aria-label={ariaLabel}>
+      {summary && (
+        <p className="k-pagination-summary" aria-live="polite">
+          {summary}
+        </p>
+      )}
+
+      <ul className="k-pagination-pages">
+        <li>
+          <button
+            type="button"
+            className="k-pagination-button"
+            onClick={() => goTo(current - 1)}
+            disabled={current <= 1}
+            aria-label="Previous page"
+          >
+            <FontAwesomeIcon icon={faChevronLeft} aria-hidden="true" />
+          </button>
+        </li>
+        {pageRange(current, lastPage, siblingCount).map((item) =>
+          typeof item === "number" ? (
+            <li key={item}>
+              <button
+                type="button"
+                className={`k-pagination-button${item === current ? " k-pagination-button-current" : ""}`}
+                onClick={() => goTo(item)}
+                aria-label={`Page ${item}`}
+                aria-current={item === current ? "page" : undefined}
+              >
+                {item}
+              </button>
+            </li>
+          ) : (
+            <li key={item} className="k-pagination-gap" aria-hidden="true">
+              …
+            </li>
+          )
+        )}
+        <li>
+          <button
+            type="button"
+            className="k-pagination-button"
+            onClick={() => goTo(current + 1)}
+            disabled={current >= lastPage}
+            aria-label="Next page"
+          >
+            <FontAwesomeIcon icon={faChevronRight} aria-hidden="true" />
+          </button>
+        </li>
+      </ul>
+
+      {pageSizeOptions && onPageSizeChange && (
+        <div className="k-pagination-page-size">
+          <label htmlFor={pageSizeId}>Rows per page</label>
+          {/* Select works in strings. */}
+          <Select
+            id={pageSizeId}
+            size="sm"
+            value={pageSize === undefined ? undefined : String(pageSize)}
+            options={pageSizeOptions.map((n) => ({
+              value: String(n),
+              label: String(n),
+            }))}
+            onChange={(n) => n !== undefined && onPageSizeChange(Number(n))}
+          />
+        </div>
+      )}
+    </nav>
+  );
+};
+
+export default Pagination;

package/src/components/navigation/pagination/styles.css

@@ -0,0 +1,113 @@
+.k-pagination {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem 1.5rem;
+  color: var(--text-color);
+}
+
+.k-pagination-summary {
+  margin: 0;
+  color: var(--text-color-secondary);
+  font-variant-numeric: tabular-nums;
+}
+
+.k-pagination-pages {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.k-pagination-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: 0.0625rem solid var(--border-color);
+  border-radius: 0.375rem;
+  background-color: var(--background-color-light);
+  color: var(--text-color);
+  font-variant-numeric: tabular-nums;
+  cursor: pointer;
+  transition:
+    background-color 0.15s ease-in-out,
+    border-color 0.15s ease-in-out;
+}
+
+.k-pagination-button:not(:disabled):hover {
+  background-color: var(--background-color-hover);
+}
+
+.k-pagination-button:focus-visible {
+  outline: 0.125rem solid var(--border-color-active);
+  outline-offset: 0.125rem;
+}
+
+.k-pagination-button-current,
+.k-pagination-button-current:not(:disabled):hover {
+  border-color: var(--primary-color);
+  background-color: var(--primary-color);
+  color: var(--text-color-light);
+  font-weight: 600;
+}
+
+.k-pagination-button:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+.k-pagination-gap {
+  color: var(--text-color-secondary);
+  text-align: center;
+}
+
+.k-pagination-page-size {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  color: var(--text-color-secondary);
+  white-space: nowrap;
+}
+
+/* Sizes: every button stays at least 32px, above the 24px target minimum. */
+.k-pagination-sm {
+  font-size: var(--text-size-sm);
+}
+
+.k-pagination-sm .k-pagination-button,
+.k-pagination-sm .k-pagination-gap {
+  min-width: 2rem;
+  height: 2rem;
+  padding: 0 0.5rem;
+}
+
+.k-pagination-md {
+  font-size: var(--text-size-sm);
+}
+
+.k-pagination-md .k-pagination-button,
+.k-pagination-md .k-pagination-gap {
+  min-width: 2.25rem;
+  height: 2.25rem;
+  padding: 0 0.625rem;
+}
+
+.k-pagination-lg {
+  font-size: var(--text-size-md);
+}
+
+.k-pagination-lg .k-pagination-button,
+.k-pagination-lg .k-pagination-gap {
+  min-width: 2.75rem;
+  height: 2.75rem;
+  padding: 0 0.75rem;
+}
+
+.k-pagination-gap {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}

package/src/components/navigation/pagination/utils.ts

@@ -0,0 +1,32 @@
+export type PageRangeItem = number | "start-gap" | "end-gap";
+
+/**
+ * The page buttons to show: always the first and last page, the current page
+ * with `siblings` neighbours either side, and a gap marker wherever pages are
+ * skipped. The list is the same length on every page, so the control doesn't
+ * jump around as you move through it.
+ */
+export const pageRange = (
+  page: number,
+  pageCount: number,
+  siblings = 1
+): PageRangeItem[] => {
+  const range = (from: number, to: number) =>
+    Array.from({ length: to - from + 1 }, (_, i) => from + i);
+
+  // first + last + current + siblings + two gaps
+  const slots = siblings * 2 + 5;
+  if (pageCount <= slots) return range(1, pageCount);
+
+  const left = Math.max(page - siblings, 1);
+  const right = Math.min(page + siblings, pageCount);
+  const gapBefore = left > 2;
+  const gapAfter = right < pageCount - 1;
+  // Pages shown at the start or end when only one gap is needed.
+  const edge = siblings * 2 + 3;
+
+  if (!gapBefore) return [...range(1, edge), "end-gap", pageCount];
+  if (!gapAfter)
+    return [1, "start-gap", ...range(pageCount - edge + 1, pageCount)];
+  return [1, "start-gap", ...range(left, right), "end-gap", pageCount];
+};

package/src/components/navigation/sidebar/styles.css

@@ -14,7 +14,9 @@
   font-weight: 700;
   text-transform: uppercase;
   letter-spacing: 0.05em;
-  color: var(--overlay-light-medium);
+  /* 50% white: the weakest overlay that keeps small text above 4.5:1 on the
+     sidebar's dark background. */
+  color: var(--overlay-light-strong);
   white-space: nowrap;
   overflow: hidden;
 }
@@ -38,6 +40,12 @@
   background-color: var(--overlay-light-weak);
 }
 
+/* Browser default focus rings can vanish on the dark background. */
+.k-sidebar-nav-link:focus-visible {
+  outline: 2px solid var(--text-color-light);
+  outline-offset: -2px;
+}
+
 .k-sidebar-nav-link.active {
   background-color: var(--overlay-light-medium);
   color: var(--text-color-light);

package/src/components/navigation/tabButton/styles.css

@@ -35,12 +35,12 @@
 }
 
 .k-tab-button-primary:hover:not(.k-tab-button-disabled) {
-  color: var(--primary-color);
+  color: var(--primary-color-text);
   background-color: var(--background-color);
 }
 
 .k-tab-button-primary.k-tab-button-active {
-  color: var(--primary-color);
+  color: var(--primary-color-text);
   background-color: var(--background-color);
   border-bottom-color: var(--primary-color);
   border-color: var(--primary-color) var(--primary-color) transparent
@@ -89,12 +89,12 @@
 }
 
 .k-tab-button-danger:hover:not(.k-tab-button-disabled) {
-  color: var(--danger-color);
+  color: var(--danger-color-text);
   background-color: var(--background-color);
 }
 
 .k-tab-button-danger.k-tab-button-active {
-  color: var(--danger-color);
+  color: var(--danger-color-text);
   background-color: var(--background-color);
   border-bottom-color: var(--danger-color);
   border-color: var(--danger-color) var(--danger-color) transparent
@@ -107,12 +107,12 @@
 }
 
 .k-tab-button-warning:hover:not(.k-tab-button-disabled) {
-  color: var(--warning-color);
+  color: var(--warning-color-text);
   background-color: var(--background-color);
 }
 
 .k-tab-button-warning.k-tab-button-active {
-  color: var(--warning-color);
+  color: var(--warning-color-text);
   background-color: var(--background-color);
   border-bottom-color: var(--warning-color);
   border-color: var(--warning-color) var(--warning-color) transparent

package/src/components/navigation/tabs/styles.css

@@ -28,11 +28,11 @@
 }
 
 .k-tabs-button:hover:not(:disabled) {
-  color: var(--primary-color);
+  color: var(--primary-color-text);
 }
 
 .k-tabs-button-active {
-  color: var(--primary-color);
+  color: var(--primary-color-text);
   border-bottom-color: var(--primary-color);
 }
 

package/src/components/overlays/confirmationModal/index.tsx

@@ -1,7 +1,10 @@
 "use client";
 
 import Button from "../../buttons/button/index.js";
+import Input from "../../inputs/input/index.js";
 import Modal from "../modal/index.js";
+import { useState } from "react";
+import "./styles.css";
 
 export interface ConfirmationModalProps {
   show: boolean;
@@ -12,14 +15,34 @@ export interface ConfirmationModalProps {
   confirmButtonText: string;
   cancelButtonText?: string;
   isLoading?: boolean;
+  /** **_Optional_** text the user must type, exactly, before the confirm button enables (e.g. the name of what's being deleted) */
+  confirmationText?: string;
+  /** **_Optional_** whether Escape and a click outside close the modal. Defaults to `true` */
+  dismissible?: boolean;
 }
 
 const ConfirmationModal = (props: ConfirmationModalProps) => {
+  const [typed, setTyped] = useState("");
+  const [wasShown, setWasShown] = useState(props.show);
+
+  // Clear the typed text each time the modal opens, so a match from a
+  // previous confirmation never carries over.
+  if (props.show !== wasShown) {
+    setWasShown(props.show);
+    if (props.show) setTyped("");
+  }
+
+  const confirmed =
+    props.confirmationText === undefined || typed === props.confirmationText;
+  const canConfirm = confirmed && !props.isLoading;
+
   return (
     <Modal
       show={props.show}
       title={props.title}
       onClose={props.handleHide}
+      // Cancel is disabled while loading; Escape and the backdrop follow suit.
+      dismissible={props.dismissible !== false && !props.isLoading}
       footerButtons={[
         <Button
           key="cancel"
@@ -34,13 +57,26 @@ const ConfirmationModal = (props: ConfirmationModalProps) => {
           variant="danger"
           onClick={props.handleConfirm}
           isLoading={props.isLoading}
-          disabled={props.isLoading}
+          disabled={!canConfirm}
         >
           {props.confirmButtonText}
         </Button>,
       ]}
     >
       {props.body}
+      {props.confirmationText !== undefined && (
+        <div className="k-confirmation-modal-check">
+          <Input
+            label={`Type "${props.confirmationText}" to confirm`}
+            value={typed}
+            onChange={(e) => setTyped(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" && canConfirm) props.handleConfirm();
+            }}
+            autoComplete="off"
+          />
+        </div>
+      )}
     </Modal>
   );
 };

package/src/components/overlays/confirmationModal/styles.css

@@ -0,0 +1,3 @@
+.k-confirmation-modal-check {
+  margin-top: 1rem;
+}

package/src/components/overlays/modal/index.tsx

@@ -23,13 +23,16 @@ interface ModalProps extends PropsWithChildren {
    * editors) that would feel cramped at `lg`.
    */
   size?: ModalSize;
+  /** **_Optional_** whether Escape and a click on the backdrop close the modal. When `false`, only the modal's own buttons can close it. Defaults to `true` */
+  dismissible?: boolean;
 }
 
 const Modal = (props: ModalProps) => {
-  const { size = "md" } = props;
+  const { size = "md", dismissible = true } = props;
   const [shouldRender, setShouldRender] = useState(props.show);
   const [isAnimating, setIsAnimating] = useState(false);
   const contentRef = useRef<HTMLDivElement>(null);
+  const pressStartedOnOverlay = useRef(false);
 
   useEffect(() => {
     if (props.show) {
@@ -46,13 +49,13 @@ const Modal = (props: ModalProps) => {
   }, [props.show]);
 
   useEffect(() => {
-    if (!props.show) return;
+    if (!props.show || !dismissible) return;
     const handler = (e: KeyboardEvent) => {
       if (e.key === "Escape") props.onClose();
     };
     document.addEventListener("keydown", handler);
     return () => document.removeEventListener("keydown", handler);
-  }, [props.show, props.onClose]);
+  }, [props.show, props.onClose, dismissible]);
 
   useFocusTrap(contentRef, !!props.show && !!shouldRender);
 
@@ -60,7 +63,23 @@ const Modal = (props: ModalProps) => {
 
   return (
     <Portal>
-      <div className={`k-modal-overlay ${isAnimating ? "closing" : ""}`}>
+      {/* Close only when the press starts and ends on the backdrop, so a text
+          selection dragged out of the dialog doesn't close it. */}
+      <div
+        className={`k-modal-overlay ${isAnimating ? "closing" : ""}`}
+        onMouseDown={(e) => {
+          pressStartedOnOverlay.current = e.target === e.currentTarget;
+        }}
+        onClick={(e) => {
+          if (
+            dismissible &&
+            pressStartedOnOverlay.current &&
+            e.target === e.currentTarget
+          ) {
+            props.onClose();
+          }
+        }}
+      >
         <div
           ref={contentRef}
           className={`k-modal-content ${isAnimating ? "closing" : ""} ${size}`}

package/src/hooks/index.ts

@@ -4,6 +4,10 @@ export {
   type UseInfiniteReturn,
 } from "./useInfinite.js";
 export { default as useInfiniteCursor } from "./useInfiniteCursor.js";
+export {
+  default as usePaginated,
+  type UsePaginatedReturn,
+} from "./usePaginated.js";
 export { default as useScrollIntoView } from "./useScrollIntoView.js";
 export { default as useDebouncedValue } from "./useDebouncedValue.js";
 export { default as useOutsideClick } from "./useOutsideClick.js";