@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/textarea/passport.json

@@ -0,0 +1,382 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Textarea",
+    "folder": "textarea",
+    "exports": [
+      "Textarea"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.0",
+    "files": [
+      "core/count.ts",
+      "core/index.ts",
+      "core/size.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Textarea.tsx",
+      "react/locale.ts",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:99fe1b42359a0d09331c6cf00b5c8d2e01fe57d9a02769637c990906ede431cf"
+  },
+  "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": "autoFocus",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "autoResize",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Grow and shrink with the text, between `minRows` and `maxRows`. Default false.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<TextareaSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "cols",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "defaultValue",
+      "type": "string",
+      "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,
+      "origin": "inherited"
+    },
+    {
+      "name": "error",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Message below the field; also marks it invalid.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "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": "inherited"
+    },
+    {
+      "name": "label",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "localeText",
+      "type": "other",
+      "typeText": "Partial<TextareaLocaleText> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "maxLength",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "maxRows",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Largest height in rows before the text scrolls. No limit by default.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "minRows",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Smallest height in rows. Default `rows`, or 3.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "onValueChange",
+      "type": "function",
+      "signature": "((value: string) => void) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "The new text on every change. The native `onChange` fires as well.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "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<HTMLTextAreaElement> | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "The `<textarea>` element.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "required",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "resize",
+      "type": "enum",
+      "values": [
+        "both",
+        "horizontal",
+        "none",
+        "vertical"
+      ],
+      "typeText": "TextareaResize | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Which way people can drag to resize. Default `vertical`, or `none` with `autoResize`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "role",
+      "type": "other",
+      "typeText": "AriaRole | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "rows",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "showCount",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "A character counter; shows `count / maxLength` when `maxLength` is set.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "typeText": "FieldSize | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "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"
+    }
+  ],
+  "inherits": [
+    {
+      "from": "TextareaHTMLAttributes<HTMLTextAreaElement>",
+      "omitted": [
+        "defaultValue",
+        "value"
+      ],
+      "passthrough": true
+    }
+  ],
+  "events": [
+    {
+      "name": "onValueChange",
+      "signature": "((value: string) => void) | undefined"
+    }
+  ],
+  "slots": [
+    "root",
+    "label",
+    "textarea",
+    "description",
+    "error",
+    "count"
+  ],
+  "states": [
+    {
+      "attr": "data-autoresize"
+    },
+    {
+      "attr": "data-disabled"
+    },
+    {
+      "attr": "data-invalid"
+    },
+    {
+      "attr": "data-over"
+    },
+    {
+      "attr": "data-required"
+    },
+    {
+      "attr": "data-resize",
+      "values": [
+        "both",
+        "horizontal",
+        "none",
+        "vertical"
+      ]
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "lg",
+        "sm"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 35,
+    "propsDescribed": 8,
+    "describedPct": 23,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}

package/source/components/textarea/react/Textarea.tsx

@@ -0,0 +1,208 @@
+"use client";
+
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  type ChangeEvent,
+  type CSSProperties,
+  type ReactNode,
+  type Ref,
+  type TextareaHTMLAttributes,
+} from "react";
+import { useControllableState } from "../../shared/react/useControllableState";
+import { describeField } from "../../shared/core/field";
+import { countCharacters } from "../core/count";
+import { fitHeight } from "../core/size";
+import type { FieldSize, TextareaLocaleText, TextareaResize } from "../core/types";
+import { defaultTextareaText } from "./locale";
+import { cx, type TextareaSlot } from "./props";
+
+export interface TextareaProps
+  extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "value" | "defaultValue"> {
+  value?: string;
+  defaultValue?: string;
+  /** The new text on every change. The native `onChange` fires as well. */
+  onValueChange?(value: string): void;
+  label?: ReactNode;
+  description?: ReactNode;
+  /** Message below the field; also marks it invalid. */
+  error?: ReactNode;
+  size?: FieldSize;
+  /** Grow and shrink with the text, between `minRows` and `maxRows`. Default false. */
+  autoResize?: boolean;
+  /** Smallest height in rows. Default `rows`, or 3. */
+  minRows?: number;
+  /** Largest height in rows before the text scrolls. No limit by default. */
+  maxRows?: number;
+  /** Which way people can drag to resize. Default `vertical`, or `none` with `autoResize`. */
+  resize?: TextareaResize;
+  /** A character counter; shows `count / maxLength` when `maxLength` is set. */
+  showCount?: boolean;
+  classNames?: Partial<Record<TextareaSlot, string>>;
+  localeText?: Partial<TextareaLocaleText>;
+  /** The `<textarea>` element. */
+  ref?: Ref<HTMLTextAreaElement>;
+}
+
+const supportsFieldSizing = () =>
+  typeof CSS !== "undefined" && CSS.supports("field-sizing", "content");
+
+const px = (value: string) => Number.parseFloat(value) || 0;
+
+/**
+ * A multi-line text field with label, hint, error, character counter and
+ * auto-resize. Every other prop goes to the `<textarea>`.
+ */
+export function Textarea(props: TextareaProps) {
+  const {
+    ref,
+    value: valueProp,
+    defaultValue,
+    onChange,
+    onValueChange,
+    label,
+    description,
+    error,
+    size = "md",
+    autoResize = false,
+    minRows,
+    maxRows,
+    rows,
+    resize,
+    showCount = false,
+    className,
+    classNames,
+    style,
+    localeText,
+    id: idProp,
+    disabled,
+    readOnly,
+    required,
+    maxLength,
+    "aria-describedby": describedByProp,
+    ...textareaProps
+  } = props;
+
+  const reactId = useId();
+  const id = idProp ?? reactId;
+  const text = useMemo(() => ({ ...defaultTextareaText, ...localeText }), [localeText]);
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+  useImperativeHandle(ref, () => textareaRef.current as HTMLTextAreaElement, []);
+
+  // Mirrors the text even when uncontrolled, for the counter and auto-resize.
+  const [current, setCurrent] = useControllableState(valueProp, defaultValue ?? "");
+  const floor = Math.max(1, minRows ?? rows ?? 3);
+
+  const handleChange = (event: ChangeEvent<HTMLTextAreaElement>) => {
+    setCurrent(event.target.value);
+    onChange?.(event);
+    onValueChange?.(event.target.value);
+  };
+
+  // Browsers with `field-sizing: content` resize in CSS; others are measured here.
+  const measure = useCallback(() => {
+    const element = textareaRef.current;
+    if (!autoResize || !element || supportsFieldSizing()) return;
+    const computed = getComputedStyle(element);
+    const metrics = {
+      lineHeight: px(computed.lineHeight) || px(computed.fontSize) * 1.5,
+      paddingBlock: px(computed.paddingTop) + px(computed.paddingBottom),
+      borderBlock: px(computed.borderTopWidth) + px(computed.borderBottomWidth),
+    };
+    element.style.height = "auto";
+    const { height, overflow } = fitHeight(element.scrollHeight, metrics, floor, maxRows);
+    element.style.height = `${height}px`;
+    element.style.overflowY = overflow ? "auto" : "hidden";
+  }, [autoResize, floor, maxRows]);
+
+  useLayoutEffect(() => {
+    measure();
+  }, [measure, current]);
+
+  // A narrower field wraps more lines, so measure again when the width changes.
+  useEffect(() => {
+    const element = textareaRef.current;
+    if (!autoResize || !element || supportsFieldSizing()) return;
+    let width = element.offsetWidth;
+    const observer = new ResizeObserver(() => {
+      if (element.offsetWidth === width) return;
+      width = element.offsetWidth;
+      measure();
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, [autoResize, measure]);
+
+  const invalid = Boolean(error);
+  const count = countCharacters(current);
+  const describedBy = describeField(id, { extra: describedByProp, description, error });
+  const rowVariables = {
+    "--ta-min-rows": floor,
+    "--ta-max-rows": maxRows ?? "none",
+  } as CSSProperties;
+
+  return (
+    <div
+      className={cx("ta-root", classNames?.root, className)}
+      style={style}
+      data-size={size}
+      data-disabled={disabled || undefined}
+      data-invalid={invalid ? "" : undefined}
+    >
+      {label && (
+        <label htmlFor={id} className={cx("ta-label", classNames?.label)} data-required={required || undefined}>
+          {label}
+        </label>
+      )}
+
+      <textarea
+        {...textareaProps}
+        ref={textareaRef}
+        id={id}
+        className={cx("ta-input", classNames?.textarea)}
+        style={rowVariables}
+        rows={autoResize ? floor : (rows ?? floor)}
+        value={valueProp}
+        defaultValue={valueProp === undefined ? defaultValue : undefined}
+        disabled={disabled}
+        readOnly={readOnly}
+        required={required}
+        maxLength={maxLength}
+        data-autoresize={autoResize || undefined}
+        data-resize={resize ?? (autoResize ? "none" : "vertical")}
+        data-invalid={invalid ? "" : undefined}
+        aria-invalid={invalid || undefined}
+        aria-describedby={describedBy}
+        onChange={handleChange}
+      />
+
+      {(description || showCount) && (
+        <div className="ta-footer">
+          {description && (
+            <span id={`${id}-description`} className={cx("ta-description", classNames?.description)}>
+              {description}
+            </span>
+          )}
+          {showCount && (
+            <span
+              className={cx("ta-count", classNames?.count)}
+              data-over={maxLength !== undefined && count > maxLength ? "" : undefined}
+            >
+              {text.characterCount(String(count), maxLength !== undefined ? String(maxLength) : undefined)}
+            </span>
+          )}
+        </div>
+      )}
+      {error && (
+        <span id={`${id}-error`} className={cx("ta-error", classNames?.error)} role="alert">
+          {error}
+        </span>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,5 @@
+import type { TextareaLocaleText } from "../core/types";
+
+export const defaultTextareaText: TextareaLocaleText = {
+  characterCount: (count, max) => (max === undefined ? count : `${count} / ${max}`),
+};

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

@@ -0,0 +1,4 @@
+export type TextareaSlot = "root" | "label" | "textarea" | "description" | "error" | "count";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";