@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/checkbox/passport.json

@@ -0,0 +1,456 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Checkbox",
+    "folder": "checkbox",
+    "exports": [
+      "Checkbox",
+      "CheckboxGroup",
+      "CheckboxGroupContext"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.0",
+    "files": [
+      "core/group.ts",
+      "core/index.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Checkbox.tsx",
+      "react/CheckboxGroup.tsx",
+      "react/context.ts",
+      "react/locale.ts",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:9e6f5998958b5395575e8e46fcd4439d7848a10cec612a398bcb2bb393a3f77c"
+  },
+  "props": [
+    {
+      "name": "aria-describedby",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "aria-labelledby",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "autoComplete",
+      "type": "other",
+      "typeText": "HTMLInputAutoCompleteAttribute | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "autoFocus",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "checked",
+      "type": "other",
+      "typeText": "CheckedState | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "`true`, `false` or `\"indeterminate\"` (controlled).",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "children",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<CheckboxSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "defaultChecked",
+      "type": "other",
+      "typeText": "CheckedState | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "defaultValue",
+      "type": "other",
+      "typeText": "string[] | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "description",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "error",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "form",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "hidden",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "inputMode",
+      "type": "enum",
+      "values": [
+        "decimal",
+        "email",
+        "none",
+        "numeric",
+        "search",
+        "tel",
+        "text",
+        "url"
+      ],
+      "typeText": "'none' | 'search' | 'email' | 'tel' | 'text' | 'url' | 'numeric' | 'decimal' | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "label",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "localeText",
+      "type": "other",
+      "typeText": "Partial<CheckboxLocaleText> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "max",
+      "type": "other",
+      "typeText": "string | number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "maxLength",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "min",
+      "type": "other",
+      "typeText": "string | number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "minLength",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Form field name for every checkbox in the group.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "onChange",
+      "type": "function",
+      "signature": "ChangeEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "onCheckedChange",
+      "type": "function",
+      "signature": "((checked: boolean) => void) | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "onValueChange",
+      "type": "function",
+      "signature": "((values: string[]) => void) | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "options",
+      "type": "other",
+      "typeText": "readonly CheckboxOption[] | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Render these options, or pass `<Checkbox value=\"…\">` children.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "orientation",
+      "type": "enum",
+      "values": [
+        "horizontal",
+        "vertical"
+      ],
+      "typeText": "'vertical' | 'horizontal' | undefined",
+      "required": false,
+      "default": "vertical",
+      "origin": "derived",
+      "description": "Default `vertical`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "pattern",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "readOnly",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "ref",
+      "type": "other",
+      "typeText": "Ref<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "The `<input>` element.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "required",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "role",
+      "type": "other",
+      "typeText": "AriaRole | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "selectAll",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "With `options`, a parent box that checks or clears them all. `true` uses the default label.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "typeText": "CheckboxSize | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "step",
+      "type": "other",
+      "typeText": "string | number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "tabIndex",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "value",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Posted with the form when checked. Inside a CheckboxGroup, the value this box adds.",
+      "descriptionOrigin": "jsdoc"
+    }
+  ],
+  "inherits": [
+    {
+      "from": "InputHTMLAttributes<HTMLInputElement>",
+      "omitted": [
+        "checked",
+        "defaultChecked",
+        "onChange",
+        "size",
+        "type",
+        "value"
+      ],
+      "passthrough": true
+    }
+  ],
+  "events": [
+    {
+      "name": "onChange",
+      "signature": "ChangeEventHandler<HTMLInputElement> | undefined"
+    },
+    {
+      "name": "onCheckedChange",
+      "signature": "((checked: boolean) => void) | undefined"
+    },
+    {
+      "name": "onValueChange",
+      "signature": "((values: string[]) => void) | undefined"
+    }
+  ],
+  "slots": [
+    "root",
+    "control",
+    "input",
+    "label",
+    "description",
+    "error",
+    "legend",
+    "items"
+  ],
+  "states": [
+    {
+      "attr": "data-disabled"
+    },
+    {
+      "attr": "data-invalid"
+    },
+    {
+      "attr": "data-orientation",
+      "values": [
+        "horizontal"
+      ]
+    },
+    {
+      "attr": "data-required"
+    },
+    {
+      "attr": "data-select-all"
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "lg",
+        "sm"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 43,
+    "propsDescribed": 7,
+    "describedPct": 16,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}

package/source/components/checkbox/react/Checkbox.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+import {
+  use,
+  useId,
+  useImperativeHandle,
+  useLayoutEffect,
+  useRef,
+  type ChangeEvent,
+  type ChangeEventHandler,
+  type InputHTMLAttributes,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { useControllableState } from "../../shared/react/useControllableState";
+import { describeField } from "../../shared/core/field";
+import type { CheckboxSize, CheckedState } from "../core/types";
+import { CheckboxGroupContext } from "./context";
+import { cx, type CheckboxSlot } from "./props";
+
+export interface CheckboxProps
+  extends Omit<
+    InputHTMLAttributes<HTMLInputElement>,
+    "type" | "size" | "checked" | "defaultChecked" | "onChange" | "value"
+  > {
+  /** `true`, `false` or `"indeterminate"` (controlled). */
+  checked?: CheckedState;
+  defaultChecked?: CheckedState;
+  onCheckedChange?(checked: boolean): void;
+  onChange?: ChangeEventHandler<HTMLInputElement>;
+  /** Posted with the form when checked. Inside a CheckboxGroup, the value this box adds. */
+  value?: string;
+  label?: ReactNode;
+  description?: ReactNode;
+  error?: ReactNode;
+  size?: CheckboxSize;
+  classNames?: Partial<Record<CheckboxSlot, string>>;
+  /** The `<input>` element. */
+  ref?: Ref<HTMLInputElement>;
+}
+
+/**
+ * A native checkbox, styled. It posts with forms, works with form libraries and
+ * reads as a checkbox to every assistive technology, including the mixed state.
+ */
+export function Checkbox(props: CheckboxProps) {
+  const {
+    ref,
+    checked: checkedProp,
+    defaultChecked = false,
+    onCheckedChange,
+    onChange,
+    value,
+    label,
+    description,
+    error,
+    size,
+    className,
+    classNames,
+    style,
+    id: idProp,
+    disabled,
+    required,
+    name,
+    "aria-describedby": describedByProp,
+    ...inputProps
+  } = props;
+
+  const group = use(CheckboxGroupContext);
+  const reactId = useId();
+  const id = idProp ?? reactId;
+  const inputRef = useRef<HTMLInputElement>(null);
+  useImperativeHandle(ref, () => inputRef.current as HTMLInputElement, []);
+
+  const [own, setOwn] = useControllableState<CheckedState>(checkedProp, defaultChecked);
+  const inGroup = group !== null && value !== undefined;
+  // Inside a group the group owns the state, whoever owns it outside one.
+  const state: CheckedState = inGroup ? group.values.includes(value) : own;
+
+  // "Indeterminate" exists only as a DOM property, not an attribute.
+  useLayoutEffect(() => {
+    if (inputRef.current) inputRef.current.indeterminate = state === "indeterminate";
+  }, [state]);
+
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    const next = event.target.checked;
+    if (inGroup) group.toggle(value, next);
+    else setOwn(next);
+    onChange?.(event);
+    onCheckedChange?.(next);
+  };
+
+  const invalid = Boolean(error) || (group?.invalid ?? false);
+  const describedBy = describeField(id, { extra: describedByProp, description, error });
+
+  return (
+    <div
+      className={cx("ck-root", classNames?.root, className)}
+      style={style}
+      data-size={size ?? group?.size ?? "md"}
+      data-disabled={disabled || group?.disabled || undefined}
+      data-invalid={invalid ? "" : undefined}
+    >
+      <span className={cx("ck-control", classNames?.control)}>
+        <input
+          {...inputProps}
+          ref={inputRef}
+          id={id}
+          type="checkbox"
+          className={cx("ck-input", classNames?.input)}
+          checked={state === true}
+          value={value}
+          name={name ?? group?.name}
+          disabled={disabled}
+          required={required}
+          aria-invalid={invalid || undefined}
+          aria-describedby={describedBy}
+          onChange={handleChange}
+        />
+        <svg className="ck-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false">
+          <path className="ck-check" d="M3.5 8.5 6.5 11.5 12.5 4.5" pathLength={1} />
+          <path className="ck-dash" d="M4 8h8" />
+        </svg>
+      </span>
+
+      {(label || description || error) && (
+        <span className="ck-text">
+          {label && (
+            <label htmlFor={id} className={cx("ck-label", classNames?.label)} data-required={required || undefined}>
+              {label}
+            </label>
+          )}
+          {description && (
+            <span id={`${id}-description`} className={cx("ck-description", classNames?.description)}>
+              {description}
+            </span>
+          )}
+          {error && (
+            <span id={`${id}-error`} className={cx("ck-error", classNames?.error)} role="alert">
+              {error}
+            </span>
+          )}
+        </span>
+      )}
+    </div>
+  );
+}