@kosmeo-ui/react 0.1.1 → 0.2.0

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

@@ -88,7 +88,7 @@ button.k-badge {
 
 .k-badge-warning {
   background-color: var(--warning-color);
-  color: var(--text-color);
+  color: var(--warning-color-contrast);
 }
 
 .k-badge-success {
@@ -107,13 +107,15 @@ button.k-badge {
 }
 
 /* Subtle variants - transparent background with colored text */
+/* Subtle text blends the variant color 60/40 with --text-color: the full
+   variant color on its own 15% tint falls under 4.5:1 for most variants. */
 .k-badge-subtle.k-badge-primary {
   background-color: color-mix(
     in srgb,
     var(--primary-color) 15%,
     var(--background-color)
   );
-  color: var(--primary-color);
+  color: color-mix(in srgb, var(--primary-color) 60%, var(--text-color));
 }
 
 .k-badge-subtle.k-badge-secondary {
@@ -122,7 +124,7 @@ button.k-badge {
     var(--secondary-color) 15%,
     var(--background-color)
   );
-  color: var(--secondary-color);
+  color: color-mix(in srgb, var(--secondary-color) 60%, var(--text-color));
 }
 
 .k-badge-subtle.k-badge-light {
@@ -140,7 +142,7 @@ button.k-badge {
     var(--danger-color) 15%,
     var(--background-color)
   );
-  color: var(--danger-color);
+  color: color-mix(in srgb, var(--danger-color) 60%, var(--text-color));
 }
 
 .k-badge-subtle.k-badge-warning {
@@ -149,7 +151,7 @@ button.k-badge {
     var(--warning-color) 20%,
     var(--background-color)
   );
-  color: var(--warning-color);
+  color: var(--warning-color-text);
 }
 
 .k-badge-subtle.k-badge-success {
@@ -158,5 +160,5 @@ button.k-badge {
     var(--success-color) 15%,
     var(--background-color)
   );
-  color: var(--success-color);
+  color: color-mix(in srgb, var(--success-color) 60%, var(--text-color));
 }

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

@@ -1,7 +1,6 @@
 .k-empty-state-inline {
   font-size: 0.875rem;
-  color: var(--text-color);
-  opacity: 0.65;
+  color: var(--text-color-secondary);
   font-style: italic;
   padding: 0.5rem 0;
 }
@@ -14,8 +13,7 @@
   gap: 0.75rem;
   padding: 2rem 1rem;
   text-align: center;
-  color: var(--text-color);
-  opacity: 0.75;
+  color: var(--text-color-secondary);
 }
 
 .k-empty-state-icon {

package/src/components/feedback/progressBar/index.tsx

@@ -17,16 +17,22 @@ const ProgressBar = (props: ProgressBarProps) => {
   const fillBorderRadius =
     clampedProgress === 100 ? "0.25rem" : "0.25rem 0 0 0.25rem";
 
+  // The percentage sits beside the bar, not on the fill: no single text color
+  // reaches 4.5:1 on every variant's fill in both themes.
   return (
-    <div className={`k-progress-bar-container`}>
-      <div
-        className={`k-progress-bar-fill k-progress-bar-fill-${variant}`}
-        style={{ width: `${clampedProgress}%`, borderRadius: fillBorderRadius }}
-      >
-        {showPercentage && clampedProgress > 0 && (
-          <span className="k-progress-bar-text">{clampedProgress}%</span>
-        )}
+    <div className="k-progress-bar">
+      <div className="k-progress-bar-container">
+        <div
+          className={`k-progress-bar-fill k-progress-bar-fill-${variant}`}
+          style={{
+            width: `${clampedProgress}%`,
+            borderRadius: fillBorderRadius,
+          }}
+        />
       </div>
+      {showPercentage && (
+        <span className="k-progress-bar-text">{clampedProgress}%</span>
+      )}
     </div>
   );
 };

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

@@ -1,5 +1,13 @@
-.k-progress-bar-container {
+.k-progress-bar {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
   width: 100%;
+}
+
+.k-progress-bar-container {
+  flex: 1;
+  min-width: 0;
   height: 1.5625rem;
   background-color: var(--background-color-dark);
   border-radius: 0.25rem;
@@ -10,16 +18,17 @@
 .k-progress-bar-fill {
   height: 100%;
   background-color: var(--success-color);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  color: var(--text-color-light);
-  font-weight: 600;
   transition: width 0.5s ease-in-out;
 }
 
 .k-progress-bar-text {
+  flex-shrink: 0;
+  min-width: 2.75rem;
+  text-align: right;
   font-size: var(--text-size-sm);
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+  color: var(--text-color);
 }
 
 .k-progress-bar-fill-primary {

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

@@ -49,16 +49,3 @@
 .k-spinner-warning {
   border-left-color: var(--warning-color);
 }
-
-/* Visually hidden class for accessibility text */
-.k-sr-only {
-  position: absolute;
-  width: 0.0625rem;
-  height: 0.0625rem;
-  padding: 0;
-  margin: -0.0625rem;
-  overflow: hidden;
-  clip: rect(0, 0, 0, 0);
-  white-space: nowrap;
-  border: 0;
-}

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

@@ -28,7 +28,7 @@
 .k-field-shell-error {
   margin-top: 0.25rem;
   font-size: 0.8125rem;
-  color: var(--danger-color);
+  color: var(--danger-color-text);
 }
 
 .k-field-shell-helper {

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

@@ -42,7 +42,7 @@
     var(--danger-color) 12%,
     var(--background-color)
   );
-  color: var(--danger-color);
+  color: var(--danger-color-text);
   border: 0.0625rem solid var(--danger-color);
   border-radius: 0.375rem;
   padding: 0.5rem 0.75rem;

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

@@ -22,8 +22,7 @@
 
 .k-info-row-label {
   font-weight: 500;
-  color: var(--text-color);
-  opacity: 0.7;
+  color: var(--text-color-secondary);
 }
 
 .k-info-row-value {

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

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

package/src/components/index.ts

@@ -39,6 +39,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 +121,7 @@ export type {
   AddressBlockProps,
   AddressBlockAddress,
 } from "./data-display/addressBlock/index.js";
+export type { PaginationProps } from "./navigation/pagination/index.js";
 export type {
   StepperProps,
   StepperStep,

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

@@ -7,22 +7,39 @@ 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)}`;
 
+  // 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}`}>
       {props.label && (
@@ -42,8 +59,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

@@ -36,6 +36,14 @@
   color: var(--text-color);
 }
 
+.k-checkbox[aria-readonly="true"] {
+  cursor: default;
+}
+
+.k-checkbox-label:has(+ .k-checkbox[aria-readonly="true"]) {
+  color: var(--text-color-secondary);
+}
+
 .k-checkbox:disabled {
   cursor: not-allowed;
   opacity: 0.6;

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

@@ -48,5 +48,5 @@
 
 .k-color-picker-error {
   font-size: 0.8125rem;
-  color: var(--danger-color);
+  color: var(--danger-color-text);
 }

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

@@ -1,7 +1,7 @@
 "use client";
 
 import FieldShell from "../../forms/fieldShell/index.js";
-import { ChangeEvent } from "react";
+import { ChangeEvent, useId } from "react";
 import "./styles.css";
 import {
   dateInputToIso,
@@ -50,9 +50,12 @@ 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));
   return (
@@ -89,9 +92,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 +134,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/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) => {
@@ -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/dropdownArrowButton/index.tsx

@@ -25,6 +25,7 @@ const DropdownArrowButton = ({
       onClick={onClick}
       tabIndex={-1}
       disabled={disabled}
+      aria-label={isOpen ? "Hide options" : "Show options"}
     >
       <FontAwesomeIcon
         icon={faChevronDown}

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

@@ -15,7 +15,7 @@
 }
 
 .k-dropdown-arrow:hover:not(:disabled) {
-  color: var(--primary-color);
+  color: var(--primary-color-text);
 }
 
 .k-dropdown-arrow:focus {

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

@@ -1,11 +1,11 @@
 "use client";
 
-import { faEye, faEyeSlash } from "@fortawesome/free-solid-svg-icons";
+import { faEye, faEyeSlash, faXmark } from "@fortawesome/free-solid-svg-icons";
 import DropdownArrowButton from "../dropdownArrowButton/index.js";
+import { ReactNode, useCallback, useRef, useState } from "react";
 import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
 import FieldShell from "../../forms/fieldShell/index.js";
 import { PropsWithSize } from "../../types.js";
-import { ReactNode, useState } from "react";
 import "./styles.css";
 
 interface InputProps extends PropsWithSize {
@@ -27,6 +27,8 @@ interface InputProps extends PropsWithSize {
 
   /** **_Optional_** if the field is disabled */
   disabled?: boolean;
+  /** **_Optional_** if the field is read-only: unlike `disabled`, it stays focusable and is submitted */
+  readOnly?: boolean;
   /** **_Optional_** if the field is a dropdown */
   dropDown?: boolean;
   /** **_Optional_** whether or not the drop down options are open */
@@ -73,6 +75,8 @@ interface InputProps extends PropsWithSize {
   onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>;
   /** **_Optional_** function that is called when the input is clicked */
   onClick?: React.MouseEventHandler<HTMLInputElement>;
+  /** **_Optional_** shows an × button at the end of a non-empty field; clear the value here. Sits at the right edge, so don't combine with `suffix` or `type="password"` */
+  onClear?: () => void;
 }
 
 const Input = (props: InputProps) => {
@@ -86,6 +90,31 @@ const Input = (props: InputProps) => {
     suffix,
   } = props;
   const [showPassword, setShowPassword] = useState(false);
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const { ref: forwardedRef } = props;
+
+  // Keep our own handle on the input (the clear button refocuses it) while
+  // still honouring a caller's `ref`.
+  const setRefs = useCallback(
+    (el: HTMLInputElement | null) => {
+      inputRef.current = el;
+      if (typeof forwardedRef === "function") forwardedRef(el);
+      else if (forwardedRef) forwardedRef.current = el;
+    },
+    [forwardedRef]
+  );
+
+  const showClear =
+    !!props.onClear &&
+    String(props.value ?? "") !== "" &&
+    !disabled &&
+    !props.readOnly;
+
+  const handleClear = () => {
+    props.onClear?.();
+    // The button unmounts once the field is empty; keep focus in the field.
+    inputRef.current?.focus();
+  };
 
   const inputId =
     props.id || `input-${Math.random().toString(36).substring(2, 9)}`;
@@ -102,6 +131,7 @@ const Input = (props: InputProps) => {
     "k-input",
     `k-input-${size}`,
     type === "password" && "k-input-password",
+    props.onClear && "k-input-clearable",
     hasAddon && "k-input-with-addon",
     prefix !== undefined && "k-input-with-prefix",
     suffix !== undefined && "k-input-with-suffix",
@@ -110,9 +140,11 @@ const Input = (props: InputProps) => {
     .join(" ");
 
   const renderAddon = (content: ReactNode, side: "prefix" | "suffix") => (
+    // Not aria-hidden: addons can be interactive (PhoneInput's country
+    // picker), and text like "$" or "USD" is useful context. Icons hide
+    // themselves.
     <span
       className={`k-input-addon k-input-addon-${side} k-input-addon-${size}`}
-      aria-hidden="true"
     >
       {content}
     </span>
@@ -140,7 +172,7 @@ const Input = (props: InputProps) => {
       >
         {prefix !== undefined && renderAddon(prefix, "prefix")}
         <input
-          ref={props.ref}
+          ref={setRefs}
           id={inputId}
           name={props.name}
           type={inputType}
@@ -152,6 +184,7 @@ const Input = (props: InputProps) => {
           autoFocus={props.autoFocus}
           autoComplete={props.autoComplete}
           disabled={disabled}
+          readOnly={props.readOnly}
           onChange={props.onChange}
           onFocus={props.onFocus}
           onBlur={props.onBlur}
@@ -159,6 +192,16 @@ const Input = (props: InputProps) => {
           onKeyDown={props.onKeyDown}
           className={inputClasses}
         />
+        {showClear && (
+          <button
+            type="button"
+            onClick={handleClear}
+            className="k-input-clear-button"
+            aria-label="Clear"
+          >
+            <FontAwesomeIcon icon={faXmark} />
+          </button>
+        )}
         {suffix !== undefined && renderAddon(suffix, "suffix")}
         {props.dropDown && (
           <DropdownArrowButton

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

@@ -51,6 +51,13 @@
   box-shadow: 0 0 0 0.1875rem var(--border-shadow-color-active);
 }
 
+/* No opacity, unlike disabled: a read-only value keeps full text contrast. */
+.k-input[readonly]:not(:disabled) {
+  background-color: var(--background-color-dark);
+  color: var(--text-color-secondary);
+  cursor: default;
+}
+
 .k-input:disabled {
   background-color: var(--bg-color-disabled);
   color: var(--text-color-disabled);
@@ -58,9 +65,46 @@
   opacity: 0.6;
 }
 
+.k-input-clearable {
+  padding-right: 2.25rem;
+}
+
+.k-input-clear-button {
+  position: absolute;
+  right: 0.5rem;
+  top: 50%;
+  transform: translateY(-50%);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.5rem;
+  height: 1.5rem;
+  padding: 0;
+  border: none;
+  border-radius: 50%;
+  background: none;
+  color: var(--text-color-secondary);
+  cursor: pointer;
+  transition: color 0.2s ease-in-out;
+}
+
+.k-input-clear-button:hover {
+  color: var(--primary-color-text);
+}
+
+.k-input-clear-button:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 0.125rem var(--border-shadow-color-active);
+}
+
 .k-password-toggle-button {
   position: absolute;
-  right: 0.75rem;
+  right: 0.5rem;
+  top: 50%;
+  transform: translateY(-50%);
+  /* 24px hit area (WCAG 2.5.8) around the small eye icon. */
+  width: 1.5rem;
+  height: 1.5rem;
   background: none;
   border: none;
   cursor: pointer;
@@ -73,7 +117,7 @@
 }
 
 .k-password-toggle-button:hover {
-  color: var(--primary-color);
+  color: var(--primary-color-text);
 }
 
 .k-password-toggle-button:focus {

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

@@ -179,6 +179,7 @@ const MultiSelect = <T,>(props: MultiSelectProps<T>) => {
             <button
               type="button"
               className="k-multiselect-selected-item-remove"
+              aria-label={`Remove ${String(v[props.labelKey])}`}
               onClick={(e) => {
                 e.stopPropagation();
                 handleOptionToggle(v);

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

@@ -165,7 +165,7 @@
 }
 
 .k-multiselect-selected-item-remove:hover {
-  color: var(--danger-color);
+  color: var(--danger-color-text);
 }
 
 /* Dropdown */

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

@@ -169,10 +169,14 @@ const PhoneInput = (props: PhoneInputProps) => {
         className="k-phone-input-picker-trigger"
         onClick={() => !disabled && setPickerOpen((o) => !o)}
         disabled={disabled}
-        aria-label={`Country: ${countryName(country)}`}
+        // Starts with the visible "+1" so voice-control users can say what
+        // they see (WCAG 2.5.3); the flag is decorative next to the name.
+        aria-label={`+${getCountryCallingCode(country)} ${countryName(country)}, change country`}
         aria-expanded={pickerOpen}
       >
-        <span className="k-phone-input-flag">{flagEmoji(country)}</span>
+        <span className="k-phone-input-flag" aria-hidden="true">
+          {flagEmoji(country)}
+        </span>
         <span className="k-phone-input-dial">
           +{getCountryCallingCode(country)}
         </span>