@grampro/kit 0.0.0-stage → 2.4.1

package/source/components/switch/README.md

@@ -0,0 +1,46 @@
+# Switch
+
+A setting that takes effect the moment it is flipped, for React 19, styled to
+match the rest of the library. The control is a real
+`<input type="checkbox" role="switch">`, so forms, form libraries and assistive
+technology work as they do natively — and it is announced as "on"/"off" rather
+than "checked". No runtime dependencies besides React.
+
+```ts
+import { Switch } from "@/components/switch";
+import "@/components/switch/styles.css";
+```
+
+```tsx
+<Switch label="Email notifications" name="notify" checked={on} onCheckedChange={setOn} />
+
+{/* Return a promise and the switch shows the new setting, spins while it saves,
+    and puts itself back if the save fails. */}
+<Switch
+  label="Two-factor authentication"
+  description="Ask for a code from your authenticator app."
+  checked={enabled}
+  onCheckedChange={(next) => api.setTwoFactor(next)}
+/>
+
+{/* A settings row: label first, switch against the right edge. */}
+<Switch label="Weekly digest" labelPosition="start" defaultChecked />
+```
+
+**Props:** `checked` / `defaultChecked` / `onCheckedChange` (may return a
+promise), `value`, `label`, `description`, `error`, `size` (`sm` `md` `lg`),
+`labelPosition` (`end` `start`), `loading`, `disabled`, `readOnly`, `required`,
+`name`, `classNames` (`root` `control` `input` `track` `thumb` `label`
+`description` `error`), `localeText`, `ref` (the `<input>`), and every
+`<input>` attribute.
+
+**Keyboard:** **Space** toggles. **→** turns it on and **←** off (mirrored in
+right-to-left layouts), which is the ARIA switch pattern.
+
+The `idleToggle`, `request`, `settle` and `adopt` state machine behind the
+saving behaviour is exported from the framework-free `core`: it decides what a
+failed save goes back to, and ignores the answer to a request that a later one
+has already replaced.
+
+Use a **Checkbox** instead when the value is part of a form that is submitted
+later, and a Switch when flipping it *is* the action.

package/source/components/switch/core/index.ts

@@ -0,0 +1,2 @@
+export { adopt, idleToggle, request, settle, type ToggleState } from "./toggle";
+export type * from "./types";

package/source/components/switch/core/toggle.ts

@@ -0,0 +1,54 @@
+/**
+ * The state of a switch whose change has to be saved somewhere.
+ *
+ * A switch is usually the whole interaction: there is no form to submit
+ * afterwards, so flipping it *is* the request. That leaves three things to
+ * agree on, and they are worth keeping out of the component and under test.
+ *
+ * The switch moves as soon as it is pressed, rather than waiting for the
+ * server, because a control that ignores a press feels broken. If the save
+ * fails it goes back to where it was — to `fallback`, the value from before the
+ * press, not simply the opposite of what is on screen, since the two differ
+ * once anything else has changed the value in the meantime.
+ *
+ * And a request that is overtaken is ignored: `settle` only accepts an outcome
+ * for the change still in flight (`pending`), so a late failure from an
+ * abandoned request cannot drag a newer value back with it.
+ */
+
+export interface ToggleState {
+  /** What the switch shows now. */
+  checked: boolean;
+  /** The change being saved, or null when nothing is in flight. */
+  pending: boolean | null;
+  /** What to go back to if the save fails. */
+  fallback: boolean;
+}
+
+export const idleToggle = (checked: boolean): ToggleState => ({
+  checked,
+  pending: null,
+  fallback: checked,
+});
+
+/** Shows `next` at once and remembers where to return to. */
+export function request(state: ToggleState, next: boolean): ToggleState {
+  if (next === state.checked && state.pending === null) return state;
+  return { checked: next, pending: next, fallback: state.pending === null ? state.checked : state.fallback };
+}
+
+/**
+ * Applies the outcome of the change that is in flight. An outcome for anything
+ * else — a request that was already overtaken — leaves the state alone.
+ */
+export function settle(state: ToggleState, requested: boolean, saved: boolean): ToggleState {
+  if (state.pending === null || state.pending !== requested) return state;
+  const checked = saved ? state.checked : state.fallback;
+  return { checked, pending: null, fallback: checked };
+}
+
+/** A value arriving from a controlled prop wins, and ends anything in flight. */
+export function adopt(state: ToggleState, checked: boolean): ToggleState {
+  if (checked === state.checked && state.pending === null) return state;
+  return idleToggle(checked);
+}

package/source/components/switch/core/types.ts

@@ -0,0 +1,9 @@
+export type SwitchSize = "sm" | "md" | "lg";
+
+/** Which side of the track the label sits on. */
+export type SwitchLabelPosition = "end" | "start";
+
+export interface SwitchLocaleText {
+  /** Announced while a change is being saved. */
+  saving: string;
+}

package/source/components/switch/index.ts

@@ -0,0 +1,5 @@
+export { Switch } from "./react/Switch";
+export type { SwitchProps } from "./react/Switch";
+export { defaultSwitchText } from "./react/locale";
+export type { SwitchSlot } from "./react/props";
+export * from "./core";

package/source/components/switch/passport.json

@@ -0,0 +1,421 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Switch",
+    "folder": "switch",
+    "exports": [
+      "Switch"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.1",
+    "files": [
+      "core/index.ts",
+      "core/toggle.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Switch.tsx",
+      "react/locale.ts",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:0e4b4a46e705b32ea7bf347c63743dfadb86ee1c5eedd2ae25e4e48721ad1989"
+  },
+  "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": "On or off (controlled).",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<SwitchSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "defaultChecked",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "defaultValue",
+      "type": "other",
+      "typeText": "string | number | readonly string[] | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "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"
+    },
+    {
+      "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": "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": "labelPosition",
+      "type": "enum",
+      "values": [
+        "end",
+        "start"
+      ],
+      "typeText": "SwitchLabelPosition | undefined",
+      "required": false,
+      "default": "end",
+      "origin": "derived",
+      "description": "Default `end`: the label after the track. `start` puts the track on the right, for settings rows.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "loading",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Show the busy state and block presses from outside, e.g. while a form saves.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "localeText",
+      "type": "other",
+      "typeText": "Partial<SwitchLocaleText> | 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": "inherited"
+    },
+    {
+      "name": "onChange",
+      "type": "function",
+      "signature": "ChangeEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "onCheckedChange",
+      "type": "function",
+      "signature": "((checked: boolean) => void | Promise<unknown>) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Fires with the new state. Return a promise and the switch stays on the new\r\nsetting with a busy indicator until it resolves, then puts itself back if\r\nit rejects — see [Saving](#saving).",
+      "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,
+      "origin": "inherited"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "typeText": "SwitchSize | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived"
+    },
+    {
+      "name": "step",
+      "type": "other",
+      "typeText": "string | number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "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",
+      "description": "Posted with the form when the switch is on. Default `\"on\"`, as for a checkbox.",
+      "descriptionOrigin": "jsdoc"
+    }
+  ],
+  "inherits": [
+    {
+      "from": "InputHTMLAttributes<HTMLInputElement>",
+      "omitted": [
+        "checked",
+        "defaultChecked",
+        "onChange",
+        "role",
+        "size",
+        "type"
+      ],
+      "passthrough": true
+    }
+  ],
+  "events": [
+    {
+      "name": "onChange",
+      "signature": "ChangeEventHandler<HTMLInputElement> | undefined"
+    },
+    {
+      "name": "onCheckedChange",
+      "signature": "((checked: boolean) => void | Promise<unknown>) | undefined"
+    }
+  ],
+  "slots": [
+    "root",
+    "control",
+    "input",
+    "track",
+    "thumb",
+    "label",
+    "description",
+    "error"
+  ],
+  "states": [
+    {
+      "attr": "data-disabled"
+    },
+    {
+      "attr": "data-invalid"
+    },
+    {
+      "attr": "data-label-position",
+      "values": [
+        "start"
+      ]
+    },
+    {
+      "attr": "data-readonly"
+    },
+    {
+      "attr": "data-required"
+    },
+    {
+      "attr": "data-saving"
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "lg",
+        "sm"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 39,
+    "propsDescribed": 6,
+    "describedPct": 15,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}