@grampro/kit 0.0.0-stage → 2.4.1

package/source/components/button/passport.json

@@ -0,0 +1,402 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Button",
+    "folder": "button",
+    "exports": [
+      "Button"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.1",
+    "files": [
+      "core/index.ts",
+      "core/state.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Button.tsx",
+      "react/locale.ts",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:85b2394bf3f7b37bd6bafd8ea93782b6c68a6ef4c5e207a6d3e6639a8ca23f9f"
+  },
+  "purpose": "Trigger an action. Not for navigation unless `render` supplies a link element.",
+  "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": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<ButtonSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "form",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "fullWidth",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "hidden",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "icon",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "An icon-only button. Give it an `aria-label`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "leading",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Icon before the label.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "loading",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Show a spinner and ignore clicks, while keeping focus and the button's width.",
+      "descriptionOrigin": "jsdoc",
+      "note": "Managed automatically when `onClick` returns a promise. Setting it manually opts out of that."
+    },
+    {
+      "name": "loadingText",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Text shown next to the spinner while busy, instead of keeping the label.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "localeText",
+      "type": "other",
+      "typeText": "Partial<ButtonLocaleText> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "onClick",
+      "type": "function",
+      "signature": "((event: MouseEvent<HTMLElement>) => unknown) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Return a promise to show the loading state until it settles.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "ref",
+      "type": "other",
+      "typeText": "Ref<HTMLButtonElement> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "render",
+      "type": "function",
+      "signature": "((props: ButtonRenderProps) => ReactElement) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Render another element with the button's look and behavior, e.g. a router\nlink: `render={(props) => <Link href=\"/billing\" {...props} />}`.",
+      "descriptionOrigin": "jsdoc",
+      "note": "Escape hatch for router links. Changes the rendered element, so composition rules apply to whatever it returns."
+    },
+    {
+      "name": "role",
+      "type": "other",
+      "typeText": "AriaRole | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "typeText": "ButtonSize | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived",
+      "description": "Default `md`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "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": "trailing",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Icon after the label.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "type",
+      "type": "enum",
+      "values": [
+        "button",
+        "reset",
+        "submit"
+      ],
+      "typeText": "'button' | 'submit' | 'reset' | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "value",
+      "type": "other",
+      "typeText": "string | number | readonly string[] | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "variant",
+      "type": "enum",
+      "values": [
+        "danger",
+        "ghost",
+        "link",
+        "outline",
+        "primary",
+        "secondary"
+      ],
+      "typeText": "ButtonVariant | undefined",
+      "required": false,
+      "default": "primary",
+      "origin": "derived",
+      "description": "Default `primary`.",
+      "descriptionOrigin": "jsdoc"
+    }
+  ],
+  "inherits": [
+    {
+      "from": "ButtonHTMLAttributes<HTMLButtonElement>",
+      "omitted": [
+        "onClick"
+      ],
+      "passthrough": true
+    }
+  ],
+  "events": [
+    {
+      "name": "onClick",
+      "signature": "((event: MouseEvent<HTMLElement>) => unknown) | undefined"
+    }
+  ],
+  "slots": [
+    "root",
+    "content",
+    "spinner",
+    "icon"
+  ],
+  "states": [
+    {
+      "attr": "data-busy",
+      "values": [
+        "state"
+      ]
+    },
+    {
+      "attr": "data-full-width",
+      "values": [
+        "full"
+      ]
+    },
+    {
+      "attr": "data-hidden"
+    },
+    {
+      "attr": "data-icon-only",
+      "values": [
+        "icon"
+      ]
+    },
+    {
+      "attr": "data-loading-text",
+      "values": [
+        "state"
+      ]
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "lg",
+        "size",
+        "sm"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    },
+    {
+      "attr": "data-variant",
+      "values": [
+        "danger",
+        "ghost",
+        "link",
+        "outline",
+        "secondary",
+        "variant"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [
+      "native <button> semantics, including Enter and Space activation",
+      "disabled state via the native attribute",
+      "focus-visible ring",
+      "the spinner is aria-hidden; loadingText is announced"
+    ],
+    "required": [
+      "aria-label when the button is icon-only (`icon` with no children)",
+      "type=\"submit\" on the button that submits a form; the default is \"button\""
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "Button",
+      "a"
+    ],
+    "notes": "Nesting interactive elements is invalid HTML and traps keyboard focus. Use `render` to change the element instead of wrapping it."
+  },
+  "operations": {},
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "safeMutations": {
+    "allowed": [
+      "variant",
+      "size",
+      "fullWidth",
+      "leading",
+      "trailing",
+      "icon",
+      "loadingText"
+    ],
+    "forbidden": [
+      "type",
+      "onClick",
+      "render",
+      "loading",
+      "disabled"
+    ],
+    "rationale": "Appearance is safe for an agent to change. `type` and `onClick` change behaviour; `loading` and `disabled` are owned by the component's own async handling."
+  },
+  "examples": [],
+  "coverage": {
+    "propsTotal": 29,
+    "propsDescribed": 9,
+    "describedPct": 31,
+    "authoredSections": [
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "purpose",
+      "safeMutations"
+    ]
+  }
+}

package/source/components/button/passport.manual.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "../../../schema/passport-v1.schema.json",
+  "component": "Button",
+  "purpose": "Trigger an action. Not for navigation unless `render` supplies a link element.",
+  "intentDomains": ["ActionIntent"],
+  "accessibility": {
+    "supplied": [
+      "native <button> semantics, including Enter and Space activation",
+      "disabled state via the native attribute",
+      "focus-visible ring",
+      "the spinner is aria-hidden; loadingText is announced"
+    ],
+    "required": [
+      "aria-label when the button is icon-only (`icon` with no children)",
+      "type=\"submit\" on the button that submits a form; the default is \"button\""
+    ]
+  },
+  "composition": {
+    "mustNotContain": ["Button", "a"],
+    "notes": "Nesting interactive elements is invalid HTML and traps keyboard focus. Use `render` to change the element instead of wrapping it."
+  },
+  "safeMutations": {
+    "allowed": ["variant", "size", "fullWidth", "leading", "trailing", "icon", "loadingText"],
+    "forbidden": ["type", "onClick", "render", "loading", "disabled"],
+    "rationale": "Appearance is safe for an agent to change. `type` and `onClick` change behaviour; `loading` and `disabled` are owned by the component's own async handling."
+  },
+  "propNotes": {
+    "render": "Escape hatch for router links. Changes the rendered element, so composition rules apply to whatever it returns.",
+    "loading": "Managed automatically when `onClick` returns a promise. Setting it manually opts out of that."
+  }
+}

package/source/components/button/react/Button.tsx

@@ -0,0 +1,173 @@
+"use client";
+
+import {
+  useMemo,
+  useState,
+  type ButtonHTMLAttributes,
+  type MouseEvent,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { useFormStatus } from "react-dom";
+import { buttonState, isPromiseLike } from "../core/state";
+import type { ButtonLocaleText, ButtonSize, ButtonVariant } from "../core/types";
+import { defaultButtonText } from "./locale";
+import { cx, type ButtonRenderProps, type ButtonSlot } from "./props";
+
+export interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> {
+  /** Default `primary`. */
+  variant?: ButtonVariant;
+  /** Default `md`. */
+  size?: ButtonSize;
+  /** Show a spinner and ignore clicks, while keeping focus and the button's width. */
+  loading?: boolean;
+  /** Text shown next to the spinner while busy, instead of keeping the label. */
+  loadingText?: ReactNode;
+  /** Icon before the label. */
+  leading?: ReactNode;
+  /** Icon after the label. */
+  trailing?: ReactNode;
+  /** An icon-only button. Give it an `aria-label`. */
+  icon?: ReactNode;
+  fullWidth?: boolean;
+  /** Return a promise to show the loading state until it settles. */
+  onClick?(event: MouseEvent<HTMLElement>): unknown;
+  /**
+   * Render another element with the button's look and behavior, e.g. a router
+   * link: `render={(props) => <Link href="/billing" {...props} />}`.
+   */
+  render?(props: ButtonRenderProps): ReactElement;
+  classNames?: Partial<Record<ButtonSlot, string>>;
+  localeText?: Partial<ButtonLocaleText>;
+  ref?: Ref<HTMLButtonElement>;
+}
+
+/** Attributes that only mean something on a `<button>`, left off a `render`ed element. */
+const BUTTON_ONLY = new Set(["form", "formAction", "formEncType", "formMethod", "formNoValidate", "formTarget", "name", "value", "type"]);
+
+const Spinner = () => (
+  <svg className="bt-spinner-ring" viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+    <circle cx="12" cy="12" r="9" pathLength={100} />
+  </svg>
+);
+
+/**
+ * A button with variants, sizes, icons and a loading state. An async `onClick`
+ * shows progress by itself, and a submit button shows progress while its form's
+ * Server Action runs.
+ */
+export function Button(props: ButtonProps) {
+  const {
+    ref,
+    variant = "primary",
+    size = "md",
+    type = "button",
+    loading = false,
+    loadingText,
+    leading,
+    trailing,
+    icon,
+    fullWidth = false,
+    disabled = false,
+    onClick,
+    render,
+    className,
+    classNames,
+    localeText,
+    children,
+    ...rest
+  } = props;
+
+  const text = useMemo(() => ({ ...defaultButtonText, ...localeText }), [localeText]);
+  // Pending while the surrounding <form action={…}> is submitting (React 19).
+  const { pending: formPending } = useFormStatus();
+  const [clickPending, setClickPending] = useState(false);
+  const state = buttonState({
+    disabled,
+    loading,
+    pending: clickPending || (type === "submit" && formPending),
+  });
+  const iconOnly = icon !== undefined && (children === undefined || children === null);
+
+  const handleClick = (event: MouseEvent<HTMLElement>) => {
+    // aria-disabled doesn't stop a click or a form submit on its own.
+    if (state.inactive) {
+      event.preventDefault();
+      return;
+    }
+    const result = onClick?.(event);
+    if (!isPromiseLike(result)) return;
+    setClickPending(true);
+    const done = () => setClickPending(false);
+    Promise.resolve(result).then(done, (error: unknown) => {
+      done();
+      // Keep the failure visible instead of swallowing it.
+      throw error;
+    });
+  };
+
+  const content = (
+    <>
+      <span
+        className={cx("bt-content", classNames?.content)}
+        // Hidden, not removed, so the button keeps its width while busy.
+        data-hidden={state.busy ? "" : undefined}
+      >
+        {leading && (
+          <span className={cx("bt-icon", classNames?.icon)} aria-hidden="true">
+            {leading}
+          </span>
+        )}
+        {iconOnly ? <span className={cx("bt-icon", classNames?.icon)}>{icon}</span> : children}
+        {trailing && (
+          <span className={cx("bt-icon", classNames?.icon)} aria-hidden="true">
+            {trailing}
+          </span>
+        )}
+      </span>
+      {state.busy && (
+        <span className={cx("bt-spinner", classNames?.spinner)}>
+          <Spinner />
+          {loadingText ?? <span className="bt-sr-only">{text.loading}</span>}
+        </span>
+      )}
+    </>
+  );
+
+  const shared = {
+    className: cx("bt-root", classNames?.root, className),
+    "data-variant": variant,
+    "data-size": size,
+    "data-busy": state.busy ? ("" as const) : undefined,
+    "data-icon-only": iconOnly ? ("" as const) : undefined,
+    "data-full-width": fullWidth ? ("" as const) : undefined,
+    "data-loading-text": state.busy && loadingText ? "" : undefined,
+    "aria-busy": state.busy || undefined,
+  };
+
+  if (render) {
+    const attributes = Object.fromEntries(Object.entries(rest).filter(([key]) => !BUTTON_ONLY.has(key)));
+    return render({
+      ...attributes,
+      ...shared,
+      "aria-disabled": state.inactive || undefined,
+      onClick: handleClick,
+      children: content,
+    });
+  }
+
+  return (
+    <button
+      {...rest}
+      {...shared}
+      ref={ref}
+      type={type}
+      disabled={state.nativeDisabled}
+      aria-disabled={state.inactive && !state.nativeDisabled ? true : undefined}
+      onClick={handleClick}
+    >
+      {content}
+    </button>
+  );
+}

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

@@ -0,0 +1,5 @@
+import type { ButtonLocaleText } from "../core/types";
+
+export const defaultButtonText: ButtonLocaleText = {
+  loading: "Loading",
+};

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

@@ -0,0 +1,23 @@
+import type { CSSProperties, MouseEvent, ReactNode } from "react";
+import type { ButtonSize, ButtonVariant } from "../core/types";
+
+export type ButtonSlot = "root" | "content" | "spinner" | "icon";
+
+/** Handed to `render`, to put the button's look and behavior on another element. */
+export interface ButtonRenderProps {
+  className: string;
+  style?: CSSProperties;
+  children: ReactNode;
+  onClick(event: MouseEvent<HTMLElement>): void;
+  "data-variant": ButtonVariant;
+  "data-size": ButtonSize;
+  "data-busy"?: "";
+  "data-icon-only"?: "";
+  "data-full-width"?: "";
+  "aria-busy"?: boolean;
+  "aria-disabled"?: boolean;
+  [attribute: string]: unknown;
+}
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";