@kosmeo-ui/react 0.1.1 → 1.0.0

package/src/components/feedback/tooltip/styles.css

@@ -33,11 +33,13 @@
 
 .k-tooltip-content {
   position: relative;
-  background-color: var(--text-color);
-  color: var(--text-color-light);
+  background-color: var(--k-text-color);
+  /* An inverted surface, so the text takes the page background, not a fixed
+     light color that disappears on the dark theme's light tooltip. */
+  color: var(--k-background-color);
   padding: 0.5rem 0.75rem;
   border-radius: 0.25rem;
-  font-size: var(--text-size-sm);
+  font-size: var(--k-text-size-sm);
   white-space: normal;
   max-width: 12.5rem;
   text-align: center;
@@ -59,26 +61,26 @@
   bottom: -0.625rem; /* Double the border-width to ensure visibility */
   left: 50%;
   transform: translateX(-50%);
-  border-color: var(--text-color) transparent transparent transparent;
+  border-color: var(--k-text-color) transparent transparent transparent;
 }
 
 .k-tooltip-bottom .k-tooltip-content::after {
   top: -0.625rem; /* Double the border-width to ensure visibility */
   left: 50%;
   transform: translateX(-50%);
-  border-color: transparent transparent var(--text-color) transparent;
+  border-color: transparent transparent var(--k-text-color) transparent;
 }
 
 .k-tooltip-left .k-tooltip-content::after {
   right: -0.625rem; /* Double the border-width to ensure visibility */
   top: 50%;
   transform: translateY(-50%);
-  border-color: transparent transparent transparent var(--text-color);
+  border-color: transparent transparent transparent var(--k-text-color);
 }
 
 .k-tooltip-right .k-tooltip-content::after {
   left: -0.625rem; /* Double the border-width to ensure visibility */
   top: 50%;
   transform: translateY(-50%);
-  border-color: transparent var(--text-color) transparent transparent;
+  border-color: transparent var(--k-text-color) transparent transparent;
 }

package/src/components/forms/detailField/styles.css

@@ -10,7 +10,7 @@
   font-weight: 600;
   text-transform: uppercase;
   letter-spacing: 0.04em;
-  color: var(--text-color-secondary);
+  color: var(--k-text-color-secondary);
 }
 
 .k-detail-field-value {

package/src/components/forms/fieldShell/index.tsx

@@ -11,6 +11,8 @@ interface FieldShellProps {
   required?: boolean;
   /** `htmlFor` target id, used when label is a string. */
   htmlFor?: string;
+  /** Id for the label element, for a control named with `aria-labelledby` (a `<label>` can't target a non-form element). */
+  labelId?: string;
   /** Optional right-aligned annotation in the label row (e.g. char count). */
   labelAside?: ReactNode;
   /** Optional error message rendered below the input. */
@@ -28,6 +30,7 @@ const FieldShell = ({
   label,
   required,
   htmlFor,
+  labelId,
   labelAside,
   error,
   helperText,
@@ -38,7 +41,7 @@ const FieldShell = ({
     {(label || labelAside) && (
       <div className="k-field-shell-label-row">
         {label && (
-          <label htmlFor={htmlFor} className="k-field-shell-label">
+          <label id={labelId} htmlFor={htmlFor} className="k-field-shell-label">
             {typeof label === "string" ? (
               <>
                 {label}

package/src/components/forms/fieldShell/styles.css

@@ -15,24 +15,24 @@
   display: block;
   font-size: 0.875rem;
   font-weight: 500;
-  color: var(--text-color);
+  color: var(--k-text-color);
 }
 
 .k-field-shell-aside {
   font-weight: 500;
-  font-size: var(--text-size-sm);
-  color: var(--text-color-secondary);
+  font-size: var(--k-text-size-sm);
+  color: var(--k-text-color-secondary);
   margin-left: 0.5rem;
 }
 
 .k-field-shell-error {
   margin-top: 0.25rem;
   font-size: 0.8125rem;
-  color: var(--danger-color);
+  color: var(--k-danger-color-text);
 }
 
 .k-field-shell-helper {
   margin-top: 0.25rem;
   font-size: 0.8125rem;
-  color: var(--text-color-secondary);
+  color: var(--k-text-color-secondary);
 }

package/src/components/forms/form/styles.css

@@ -9,19 +9,19 @@
 }
 
 .k-form-validating .k-input-invalid {
-  border-color: var(--danger-color);
+  border-color: var(--k-danger-color);
 }
 
 .k-form-validating .k-input-invalid:focus {
-  border-color: var(--danger-color);
-  box-shadow: 0 0 0 0.1875rem var(--shadow-color-hover);
+  border-color: var(--k-danger-color);
+  box-shadow: 0 0 0 0.1875rem var(--k-shadow-color-hover);
 }
 
 .k-form-validating .k-input-valid {
-  border-color: var(--success-color);
+  border-color: var(--k-success-color);
 }
 
 .k-form-validating .k-input-valid:focus {
-  border-color: var(--success-color);
-  box-shadow: 0 0 0 0.1875rem var(--shadow-color-hover);
+  border-color: var(--k-success-color);
+  box-shadow: 0 0 0 0.1875rem var(--k-shadow-color-hover);
 }

package/src/components/forms/formActions/styles.css

@@ -39,11 +39,11 @@
 .k-form-error {
   background-color: color-mix(
     in srgb,
-    var(--danger-color) 12%,
-    var(--background-color)
+    var(--k-danger-color) 12%,
+    var(--k-background-color)
   );
-  color: var(--danger-color);
-  border: 0.0625rem solid var(--danger-color);
+  color: var(--k-danger-color-text);
+  border: 0.0625rem solid var(--k-danger-color);
   border-radius: 0.375rem;
   padding: 0.5rem 0.75rem;
   font-size: 0.875rem;

package/src/components/forms/formGrid/styles.css

@@ -39,3 +39,35 @@
     grid-template-columns: 1fr;
   }
 }
+
+/* Each item spans three rows (label, control, message) and fields share them
+   through subgrid, so controls in a row stay level when one label wraps or
+   one field shows helper or error text. Non-field items span the same three
+   rows so auto-placement stays one item per cell. */
+.k-form-grid > * {
+  grid-row: span 3;
+}
+
+.k-form-grid > .k-field-shell,
+.k-form-grid > * > .k-field-shell,
+.k-form-grid > :has(> .k-field-shell) {
+  display: grid;
+  grid-template-rows: subgrid;
+  grid-row: span 3;
+  row-gap: 0;
+}
+
+:is(.k-form-grid > .k-field-shell, .k-form-grid > * > .k-field-shell) > * {
+  grid-row: 2;
+}
+
+:is(.k-form-grid > .k-field-shell, .k-form-grid > * > .k-field-shell)
+  > .k-field-shell-label-row {
+  grid-row: 1;
+  align-self: end;
+}
+
+:is(.k-form-grid > .k-field-shell, .k-form-grid > * > .k-field-shell)
+  > :is(.k-field-shell-error, .k-field-shell-helper) {
+  grid-row: 3;
+}

package/src/components/forms/infoRow/styles.css

@@ -2,7 +2,7 @@
   display: flex;
   gap: 0.75rem;
   padding: 0.5rem 0;
-  border-bottom: 0.0625rem solid var(--border-color);
+  border-bottom: 0.0625rem solid var(--k-border-color);
 }
 
 .k-info-row:last-child {
@@ -22,8 +22,7 @@
 
 .k-info-row-label {
   font-weight: 500;
-  color: var(--text-color);
-  opacity: 0.7;
+  color: var(--k-text-color-secondary);
 }
 
 .k-info-row-value {

package/src/components/forms/optionsGroup/index.tsx

@@ -1,26 +1,45 @@
 "use client";
 
 import MandatoryAsterisk from "../requiredAsterisk/index.js";
-import { ReactNode } from "react";
+import { ReactNode, useId } from "react";
 import "./styles.css";
 
 interface OptionsGroupProps {
   label?: string;
   required?: boolean;
+  /** `radiogroup` for radios; `group` (the default) for checkboxes. */
+  role?: "group" | "radiogroup";
   children: ReactNode;
 }
 
 /** Internal shell for CheckboxGroup / RadioGroup — label + option list. */
-const OptionsGroup = ({ label, required, children }: OptionsGroupProps) => (
-  <div className="k-options-group">
-    {label && (
-      <label className="k-options-group-label">
-        {label}
-        {required && <MandatoryAsterisk />}
-      </label>
-    )}
-    <div className="k-options-group-options">{children}</div>
-  </div>
-);
+const OptionsGroup = ({
+  label,
+  required,
+  role = "group",
+  children,
+}: OptionsGroupProps) => {
+  const labelId = useId();
+  return (
+    <div
+      className="k-options-group"
+      role={role}
+      aria-labelledby={label ? labelId : undefined}
+      aria-required={(role === "radiogroup" && required) || undefined}
+    >
+      {label && (
+        <label id={labelId} className="k-options-group-label">
+          {label}
+          {required && <MandatoryAsterisk />}
+          {/* ARIA can't mark a checkbox group required, so say it. */}
+          {required && role === "group" && (
+            <span className="k-sr-only"> (required)</span>
+          )}
+        </label>
+      )}
+      <div className="k-options-group-options">{children}</div>
+    </div>
+  );
+};
 
 export default OptionsGroup;

package/src/components/forms/optionsGroup/styles.css

@@ -7,7 +7,7 @@
 .k-options-group-label {
   font-weight: 600;
   font-size: 0.875rem;
-  color: var(--text-color);
+  color: var(--k-text-color);
 }
 
 .k-options-group-options {

package/src/components/forms/requiredAsterisk/index.tsx

@@ -2,8 +2,12 @@
 
 import "./styles.css";
 
+// Hidden from assistive tech, which reads "required" from the field itself.
 const MandatoryAsterisk = () => (
-  <span className="k-mandatory-asterisk"> *</span>
+  <span className="k-mandatory-asterisk" aria-hidden="true">
+    {" "}
+    *
+  </span>
 );
 
 export default MandatoryAsterisk;

package/src/components/forms/requiredAsterisk/styles.css

@@ -1,3 +1,3 @@
 .k-mandatory-asterisk {
-  color: var(--danger-color);
+  color: var(--k-danger-color-text);
 }

package/src/components/index.ts

@@ -1,6 +1,7 @@
 export { default as RecoveryCodeGrid } from "./data-display/recoveryCodeGrid/index.js";
 export { default as ConfirmationModal } from "./overlays/confirmationModal/index.js";
 export { default as InfiniteScroll } from "./data-display/infiniteScroll/index.js";
+export { default as TableFilters } from "./data-display/tableFilters/index.js";
 export {
   DateInput,
   DateTimeInput,
@@ -39,6 +40,7 @@ export { default as RadioGroup } from "./inputs/radioGroup/index.js";
 export { default as ListRow } from "./data-display/listRow/index.js";
 export { default as TagCard } from "./data-display/tagCard/index.js";
 export { default as Stepper } from "./navigation/stepper/index.js";
+export { default as Pagination } from "./navigation/pagination/index.js";
 export { default as Typeahead } from "./inputs/typeahead/index.js";
 export { default as AuthPage } from "./layout/authPage/index.js";
 export { default as Checkbox } from "./inputs/checkbox/index.js";
@@ -120,6 +122,8 @@ export type {
   AddressBlockProps,
   AddressBlockAddress,
 } from "./data-display/addressBlock/index.js";
+export type { PaginationProps } from "./navigation/pagination/index.js";
+export type { TableFiltersProps } from "./data-display/tableFilters/index.js";
 export type {
   StepperProps,
   StepperStep,

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

@@ -1,27 +1,45 @@
 "use client";
 
 import MandatoryAsterisk from "../../forms/requiredAsterisk/index.js";
+import { useId } from "react";
 import "./styles.css";
 
 interface CheckboxProps {
   label?: string | React.ReactNode;
   labelLocation?: "top" | "right" | "bottom" | "left";
   checked: boolean;
-  onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+  /** **_Optional_** only when `readOnly`, which never calls it */
+  onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
   onClick?: (event: React.MouseEvent<HTMLInputElement>) => void;
   /** **_Optional_** whether the field is required (shows red asterisk and enables validation) */
   required?: boolean;
   /** **_Optional_** if the checkbox is disabled */
   disabled?: boolean;
+  /** **_Optional_** if the checkbox is read-only: unlike `disabled`, it stays focusable and is announced as read-only */
+  readOnly?: boolean;
   /** **_Optional_** ID of the field. If one is not provided, it will be randomly generated */
   id?: string;
+  /** **_Optional_** accessible name when there's no visible `label` (e.g. a row-select checkbox) */
+  "aria-label"?: string;
 }
 
 const Checkbox = (props: CheckboxProps) => {
-  const { labelLocation = "top", disabled = false, required = false } = props;
+  const {
+    labelLocation = "top",
+    disabled = false,
+    required = false,
+    readOnly = false,
+  } = props;
 
-  const inputId =
-    props.id || `checkbox-${Math.random().toString(36).substring(2, 9)}`;
+  const generatedId = useId();
+  const inputId = props.id || `checkbox-${generatedId}`;
+
+  // Browsers ignore `readonly` on checkboxes, so a click (or Space) is
+  // cancelled here instead; aria-readonly tells assistive tech why.
+  const handleClick = (event: React.MouseEvent<HTMLInputElement>) => {
+    if (readOnly) event.preventDefault();
+    props.onClick?.(event);
+  };
 
   return (
     <div className={`k-checkbox-container k-${labelLocation}`}>
@@ -42,8 +60,11 @@ const Checkbox = (props: CheckboxProps) => {
         type="checkbox"
         required={required}
         checked={props.checked}
-        onClick={props.onClick}
-        onChange={props.onChange}
+        onClick={handleClick}
+        onChange={readOnly ? undefined : props.onChange}
+        readOnly={readOnly}
+        aria-readonly={readOnly || undefined}
+        aria-label={props["aria-label"]}
         className="k-checkbox"
         disabled={disabled}
       />

package/src/components/inputs/checkbox/styles.css

@@ -25,7 +25,7 @@
   height: 1.25rem;
   width: 1.25rem;
   border-radius: 0.25rem;
-  border-color: var(--border-color);
+  border-color: var(--k-border-color);
 }
 
 .k-checkbox-label {
@@ -33,7 +33,15 @@
   margin-bottom: 0.1rem;
   font-size: 0.875rem;
   font-weight: 500;
-  color: var(--text-color);
+  color: var(--k-text-color);
+}
+
+.k-checkbox[aria-readonly="true"] {
+  cursor: default;
+}
+
+.k-checkbox-label:has(+ .k-checkbox[aria-readonly="true"]) {
+  color: var(--k-text-color-secondary);
 }
 
 .k-checkbox:disabled {
@@ -43,6 +51,6 @@
 
 .k-checkbox:disabled + .k-checkbox-label,
 .k-checkbox-label:has(+ .k-checkbox:disabled) {
-  color: var(--text-color-disabled);
+  color: var(--k-text-color-disabled);
   cursor: not-allowed;
 }

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

@@ -1,7 +1,7 @@
 "use client";
 
+import { ChangeEvent, useId } from "react";
 import Input from "../input/index.js";
-import { ChangeEvent } from "react";
 import "./styles.css";
 
 export interface ColorPickerProps {
@@ -30,6 +30,7 @@ const ColorPicker = ({
   required,
   invalidMessage = DEFAULT_INVALID_MESSAGE,
 }: ColorPickerProps) => {
+  const inputId = useId();
   const trimmed = value.trim();
   const isEmpty = trimmed === "";
   const isValid = HEX_RE.test(trimmed);
@@ -46,7 +47,7 @@ const ColorPicker = ({
   return (
     <div className="k-color-picker">
       {label && (
-        <label className="k-color-picker-label">
+        <label className="k-color-picker-label" htmlFor={inputId}>
           {label}
           {required && <span aria-hidden> *</span>}
         </label>
@@ -61,9 +62,11 @@ const ColorPicker = ({
         />
         <div className="k-color-picker-input">
           <Input
+            id={inputId}
             value={value}
             onChange={(e) => onChange(e.target.value)}
             placeholder={placeholder}
+            required={required}
           />
         </div>
       </div>

package/src/components/inputs/colorPicker/styles.css

@@ -7,7 +7,7 @@
 .k-color-picker-label {
   font-size: 0.875rem;
   font-weight: 500;
-  color: var(--text-color);
+  color: var(--k-text-color);
 }
 
 .k-color-picker-row {
@@ -21,7 +21,7 @@
   -webkit-appearance: none;
   width: 2.5rem;
   height: 2.5rem;
-  border: 0.0625rem solid var(--border-color);
+  border: 0.0625rem solid var(--k-border-color);
   border-radius: 0.375rem;
   padding: 0;
   cursor: pointer;
@@ -48,5 +48,5 @@
 
 .k-color-picker-error {
   font-size: 0.8125rem;
-  color: var(--danger-color);
+  color: var(--k-danger-color-text);
 }

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

@@ -1,10 +1,9 @@
 "use client";
 
 import FieldShell from "../../forms/fieldShell/index.js";
-import { ChangeEvent } from "react";
+import { ChangeEvent, useId } from "react";
 import "./styles.css";
 import {
-  dateInputToIso,
   dateTimeLocalToIso,
   toDateInputValue,
   toDateTimeLocalValue,
@@ -23,10 +22,10 @@ export interface DateInputBaseProps {
 }
 
 export interface DateInputProps extends DateInputBaseProps {
-  /** Accepts an ISO string or `Date`. Empty string and null both mean "no value". */
+  /** Accepts a `yyyy-mm-dd` date, an ISO string or `Date`. Empty string and null both mean "no value". */
   value: string | Date | null;
-  /** Fires with an ISO date-time string (start-of-day) or `null` when cleared. */
-  onChange: (iso: string | null) => void;
+  /** Fires with the picked calendar day as `yyyy-mm-dd`, or `null` when cleared. */
+  onChange: (date: string | null) => void;
 }
 
 export interface DateTimeInputProps extends DateInputBaseProps {
@@ -50,11 +49,14 @@ export const DateInput = ({
   disabled,
   min,
   max,
-  id,
+  id: idProp,
   name,
 }: DateInputProps) => {
+  // Without an id the label isn't linked to the input.
+  const fallbackId = useId();
+  const id = idProp ?? fallbackId;
   const handle = (e: ChangeEvent<HTMLInputElement>) =>
-    onChange(dateInputToIso(e.target.value));
+    onChange(e.target.value || null);
   return (
     <FieldShell
       label={label}
@@ -89,9 +91,12 @@ export const DateTimeInput = ({
   disabled,
   min,
   max,
-  id,
+  id: idProp,
   name,
 }: DateTimeInputProps) => {
+  // Without an id the label isn't linked to the input.
+  const fallbackId = useId();
+  const id = idProp ?? fallbackId;
   const handle = (e: ChangeEvent<HTMLInputElement>) =>
     onChange(dateTimeLocalToIso(e.target.value));
   return (
@@ -128,9 +133,12 @@ export const TimeInput = ({
   disabled,
   min,
   max,
-  id,
+  id: idProp,
   name,
 }: TimeInputProps) => {
+  // Without an id the label isn't linked to the input.
+  const fallbackId = useId();
+  const id = idProp ?? fallbackId;
   const handle = (e: ChangeEvent<HTMLInputElement>) =>
     onChange(e.target.value || null);
   return (

package/src/components/inputs/dateInput/styles.css

@@ -1,19 +1,19 @@
 .k-date-input-field {
-  border: 0.0625rem solid var(--border-color);
+  border: 0.0625rem solid var(--k-border-color);
   border-radius: 0.375rem;
   padding: 0.5rem 0.625rem;
   font-size: 0.9375rem;
-  background-color: var(--background-color);
-  color: var(--text-color);
+  background-color: var(--k-background-color);
+  color: var(--k-text-color);
   width: 100%;
   box-sizing: border-box;
 }
 
 .k-date-input-field:focus {
   outline: none;
-  border-color: var(--primary-color);
+  border-color: var(--k-primary-color);
   box-shadow: 0 0 0 0.125rem
-    color-mix(in srgb, var(--primary-color) 30%, transparent);
+    color-mix(in srgb, var(--k-primary-color) 30%, transparent);
 }
 
 .k-date-input-field:disabled {

package/src/components/inputs/dateInput/utils.ts

@@ -1,10 +1,20 @@
 const pad = (n: number) => n.toString().padStart(2, "0");
 
+// `new Date("2024-01-05")` is UTC midnight, which is the previous day west of
+// UTC; a date-only string means that calendar day locally.
+const toDate = (value: string | Date): Date => {
+  if (value instanceof Date) return value;
+  const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!dateOnly) return new Date(value);
+  const [, y, m, d] = dateOnly.map(Number);
+  return new Date(y, m - 1, d);
+};
+
 export const toDateInputValue = (
   value: string | Date | null | undefined
 ): string => {
   if (value == null || value === "") return "";
-  const d = value instanceof Date ? value : new Date(value);
+  const d = toDate(value);
   if (Number.isNaN(d.getTime())) return "";
   return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
 };
@@ -13,19 +23,13 @@ export const toDateTimeLocalValue = (
   value: string | Date | null | undefined
 ): string => {
   if (value == null || value === "") return "";
-  const d = value instanceof Date ? value : new Date(value);
+  const d = toDate(value);
   if (Number.isNaN(d.getTime())) return "";
   return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(
     d.getHours()
   )}:${pad(d.getMinutes())}`;
 };
 
-export const dateInputToIso = (value: string): string | null => {
-  if (!value) return null;
-  const d = new Date(`${value}T00:00:00`);
-  return Number.isNaN(d.getTime()) ? null : d.toISOString();
-};
-
 export const dateTimeLocalToIso = (value: string): string | null => {
   if (!value) return null;
   const d = new Date(value);

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

@@ -23,6 +23,8 @@ export interface DropdownProps extends PropsWithSize, PropsWithVariant {
   isOpen?: boolean;
   /** Controlled mode: callback when open state changes */
   onOpenChange?: (isOpen: boolean) => void;
+  /** Accessible name for the trigger. Required when it shows only an `icon`. */
+  "aria-label"?: string;
 }
 
 const Dropdown = (props: DropdownProps) => {
@@ -44,7 +46,7 @@ const Dropdown = (props: DropdownProps) => {
     setIsOpen(!isOpen);
   };
 
-  useOutsideClick([dropdownRef], () => setIsOpen(false));
+  useOutsideClick([dropdownRef], () => setIsOpen(false), isOpen);
 
   const label = (
     <div className="k-dropdown-label-container">
@@ -63,6 +65,7 @@ const Dropdown = (props: DropdownProps) => {
           variant={props.variant}
           icon={props.icon}
           onClick={handleTriggerClick}
+          aria-label={props["aria-label"]}
         >
           {props.label && label}
         </IconButton>
@@ -71,6 +74,7 @@ const Dropdown = (props: DropdownProps) => {
           size={props.size}
           variant={props.variant}
           onClick={handleTriggerClick}
+          aria-label={props["aria-label"]}
         >
           {props.label && label}
         </Button>

package/src/components/inputs/dropdown/styles.css

@@ -7,9 +7,9 @@
 .k-dropdown-menu {
   position: absolute;
   top: 100%;
-  background-color: var(--background-color);
+  background-color: var(--k-background-color);
   border-radius: 0.5rem;
-  box-shadow: 0 0.375rem 1.25rem var(--shadow-color);
+  box-shadow: 0 0.375rem 1.25rem var(--k-shadow-color);
   overflow: hidden;
   transform: translateY(-0.625rem);
   opacity: 0;