@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/radio-group/README.md

@@ -0,0 +1,58 @@
+# Radio and RadioGroup
+
+One choice out of a few, for React 19, styled to match the rest of the library.
+The buttons are real `<input type="radio">` elements sharing a `name`, so the
+arrow keys roam the group, the group is one tab stop, and the browser validates
+it as one required field — without a line of JavaScript. No runtime
+dependencies besides React.
+
+```ts
+import { Radio, RadioGroup } from "@/components/radio-group";
+import "@/components/radio-group/styles.css";
+```
+
+```tsx
+<RadioGroup
+  label="Send the report"
+  name="frequency"
+  options={["Daily", "Weekly", "Monthly"]}
+  value={frequency}
+  onValueChange={setFrequency}
+/>
+
+{/* Tiles, for choices that need explaining. */}
+<RadioGroup
+  label="Plan"
+  variant="card"
+  orientation="horizontal"
+  options={[
+    { value: "starter", label: "Starter", description: "Up to 3 projects" },
+    { value: "team", label: "Team", description: "Unlimited projects and members" },
+  ]}
+  defaultValue="team"
+/>
+
+{/* Or compose them, when each choice needs its own markup. */}
+<RadioGroup label="Delivery" name="delivery">
+  <Radio value="standard" label="Standard" description="3–5 days" />
+  <Radio value="express" label="Express" description="Tomorrow" disabled />
+</RadioGroup>
+```
+
+**RadioGroup:** `value` / `defaultValue` / `onValueChange` (`string | null`),
+`options` (plain strings or full options) or `<Radio value>` children, `label`
+(legend), `description`, `error`, `required`, `disabled`, `name`, `size`,
+`orientation`, `variant` (`default` `card`), `clearable`, `classNames` (`root`
+`legend` `description` `items` `clear` `error`), `localeText`.
+
+**Radio:** `value`, `label`, `description`, `error`, `size`, `disabled`,
+`classNames` (`root` `control` `input` `label` `description` `error`), `ref`
+(the `<input>`), and every `<input>` attribute.
+
+A radio cannot be unselected by clicking or by keyboard — that is what the
+control is — so an optional question needs either `clearable`, which offers a
+button that empties the group, or a "None" option of its own.
+
+`normalizeOptions`, `resolveValue` and `hasEnabledOption` are exported from the
+framework-free `core`. `resolveValue` is what makes a value the group does not
+offer select nothing, rather than guessing at an option the record never chose.

package/source/components/radio-group/core/group.ts

@@ -0,0 +1,36 @@
+import type { RadioOption } from "./types";
+
+/**
+ * Accepts `["daily", "weekly"]` as well as the full option objects, because a
+ * list of plain values is the common case and writing `{ value: x, label: x }`
+ * for each one adds nothing.
+ */
+export function normalizeOptions(
+  options: readonly (string | RadioOption)[],
+): RadioOption[] {
+  return options.map((option) =>
+    typeof option === "string" ? { value: option, label: option } : option,
+  );
+}
+
+/**
+ * The value the group should actually show as selected.
+ *
+ * A value that matches no option selects nothing, which is what native radios
+ * do and the right answer for a stale value from a server: showing an arbitrary
+ * option instead would claim a choice the record never made. A *disabled*
+ * option still counts — a locked-in choice has to be visible, or the group
+ * would look empty while refusing to let anything be chosen.
+ */
+export function resolveValue(
+  options: readonly RadioOption[],
+  value: string | null | undefined,
+): string | null {
+  if (value === null || value === undefined) return null;
+  return options.some((option) => option.value === value) ? value : null;
+}
+
+/** Whether anything in the group can still be chosen, for a `clear` button. */
+export function hasEnabledOption(options: readonly RadioOption[], disabled: boolean): boolean {
+  return !disabled && options.some((option) => !option.disabled);
+}

package/source/components/radio-group/core/index.ts

@@ -0,0 +1,2 @@
+export { hasEnabledOption, normalizeOptions, resolveValue } from "./group";
+export type * from "./types";

package/source/components/radio-group/core/types.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from "react";
+
+export type RadioSize = "sm" | "md" | "lg";
+
+/** `card` draws each choice as a bordered tile, for choices that carry detail. */
+export type RadioVariant = "default" | "card";
+
+export type RadioOrientation = "vertical" | "horizontal";
+
+export interface RadioOption {
+  value: string;
+  label: ReactNode;
+  description?: ReactNode;
+  disabled?: boolean;
+}
+
+export interface RadioGroupLocaleText {
+  /** The button that empties a `clearable` group. */
+  clear: string;
+}

package/source/components/radio-group/index.ts

@@ -0,0 +1,9 @@
+export { Radio } from "./react/Radio";
+export type { RadioProps } from "./react/Radio";
+export { RadioGroup } from "./react/RadioGroup";
+export type { RadioGroupProps } from "./react/RadioGroup";
+export { RadioGroupContext } from "./react/context";
+export type { RadioGroupContextValue } from "./react/context";
+export { defaultRadioGroupText } from "./react/locale";
+export type { RadioGroupSlot, RadioSlot } from "./react/props";
+export * from "./core";

package/source/components/radio-group/passport.json

@@ -0,0 +1,477 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Radio",
+    "folder": "radio-group",
+    "exports": [
+      "Radio",
+      "RadioGroup",
+      "RadioGroupContext"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.0",
+    "files": [
+      "core/group.ts",
+      "core/index.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Radio.tsx",
+      "react/RadioGroup.tsx",
+      "react/context.ts",
+      "react/locale.ts",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:75988fb28f81a91f9ec61a6b1cc89f4e6b9f5c45b7ae38cfe94abcc5de40ff2d"
+  },
+  "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": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Selected (controlled). Inside a RadioGroup the group decides instead.",
+      "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<RadioSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "clearable",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Offer a button that empties the group. Radios cannot be unselected by\r\nclicking or by keyboard — that is the control's nature, not an oversight —\r\nso an optional choice needs either this or a \"None\" option of its own.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "defaultChecked",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "defaultValue",
+      "type": "string",
+      "typeText": "string | null | 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<RadioGroupLocaleText> | 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 shared by every radio. One is generated when it is left out.",
+      "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": "((value: string | null) => void) | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "options",
+      "type": "other",
+      "typeText": "readonly (string | RadioOption)[] | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Render these choices, or pass `<Radio value=\"…\">` children. Plain strings work too.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "orientation",
+      "type": "enum",
+      "values": [
+        "horizontal",
+        "vertical"
+      ],
+      "typeText": "RadioOrientation | 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": "size",
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "typeText": "RadioSize | 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",
+      "required": true,
+      "origin": "derived",
+      "description": "The value this choice contributes to its group.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "variant",
+      "type": "enum",
+      "values": [
+        "card",
+        "default"
+      ],
+      "typeText": "RadioVariant | undefined",
+      "required": false,
+      "default": "default",
+      "origin": "derived",
+      "description": "Default `default`. `card` draws each choice as a tile.",
+      "descriptionOrigin": "jsdoc"
+    }
+  ],
+  "inherits": [
+    {
+      "from": "InputHTMLAttributes<HTMLInputElement>",
+      "omitted": [
+        "checked",
+        "defaultChecked",
+        "onChange",
+        "size",
+        "type"
+      ],
+      "passthrough": true
+    }
+  ],
+  "events": [
+    {
+      "name": "onChange",
+      "signature": "ChangeEventHandler<HTMLInputElement> | undefined"
+    },
+    {
+      "name": "onCheckedChange",
+      "signature": "((checked: boolean) => void) | undefined"
+    },
+    {
+      "name": "onValueChange",
+      "signature": "((value: string | null) => void) | undefined"
+    }
+  ],
+  "slots": [
+    "root",
+    "control",
+    "input",
+    "label",
+    "description",
+    "error",
+    "legend",
+    "items",
+    "clear"
+  ],
+  "states": [
+    {
+      "attr": "data-checked"
+    },
+    {
+      "attr": "data-disabled"
+    },
+    {
+      "attr": "data-invalid"
+    },
+    {
+      "attr": "data-orientation",
+      "values": [
+        "horizontal"
+      ]
+    },
+    {
+      "attr": "data-required"
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "lg",
+        "sm"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    },
+    {
+      "attr": "data-variant",
+      "values": [
+        "card"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 44,
+    "propsDescribed": 8,
+    "describedPct": 18,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}