gbs-add-block 1.2.18 → 1.2.19

package/README.md

@@ -1,4 +1,4 @@
-# GBS Building Blocks 2.0 (v1.2.18)
+# GBS Building Blocks 2.0 (v1.2.19)
 
 Latest and upgraded version of GBS building blocks with headless UI and removed dependencies.
 
@@ -10,7 +10,7 @@ For detailed documentation on usage and props, Please visit: [Building Block Doc
     
 New Beta Components are avilable for testing and feedback, Please visit: [Building Block Documentation v2.0.0 beta](https://gramprokit.vercel.app/2.0.0-beta)
 
-## What's New 🎉 (Ver 1.2.18)
+## What's New 🎉 (Ver 1.2.19)
 
 - Update Candidate for next major change 2.0.0
 

package/index.cjs

@@ -56,12 +56,17 @@ const CONFIG = {
     "Popover",
     "Card",
     "Skeleton",
+    "NumberInput",
+    "RadioGroup",
+    "Switch"
   ],
   // Beta folder names that are not simply the lowercased component name.
   betaFolders: {
     DataGrid: "data-grid",
     DatePicker: "date-picker",
     FileUploader: "file-uploader",
+    NumberInput: "number-input",
+    RadioGroup: "radio-group"
   },
   // Define component dependencies
   dependencies: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gbs-add-block",
-  "version": "1.2.18",
+  "version": "1.2.19",
   "description": "React Component Library",
   "type": "module",
   "files": [

package/source/beta-components/number-input/README.md

@@ -0,0 +1,53 @@
+# NumberInput
+
+A numeric field for React 19 that reads and writes numbers the way the locale
+does, styled to match the Input component. No runtime dependencies besides
+React.
+
+```ts
+import { NumberInput } from "@/components/number-input";
+import "@/components/number-input/styles.css";
+```
+
+```tsx
+<NumberInput label="Quantity" min={1} max={99} value={qty} onValueChange={setQty} />
+
+<NumberInput label="Amount" format="currency" currency="USD" decimals={2} locale="en-US" />
+
+{/* 45% in the field is 0.45 in the value, as Intl and CSS both have it. */}
+<NumberInput label="Discount" format="percent" step={0.01} min={0} max={1} />
+```
+
+**Why not `<input type="number">`:** the wheel silently edits it while the page
+scrolls; an entry it considers invalid reports itself as the empty string, so
+"nothing" and "not a number yet" cannot be told apart and what was typed is
+gone; it understands one notation, so `1.234,56` is not a number to it; and its
+spin buttons cannot be styled. This field is a text input with
+`role="spinbutton"`, which has none of those problems and the same
+announcements.
+
+**Props:** `value` / `defaultValue` / `onValueChange` (`number | null`), `min`,
+`max`, `step`, `largeStep`, `snapToStep`, `decimals`, `locale`, `format`
+(`decimal` `currency` `percent`), `currency`, `useGrouping`, `clampBehavior`
+(`blur` `strict` `none`), `stepper`, `wheel`, `selectOnFocus`, `clearable`,
+`label`, `description`, `error`, `size`, `leading`, `trailing`, `disabled`,
+`readOnly`, `required`, `classNames` (`root` `label` `control` `input`
+`stepper` `description` `error`), `localeText`, `ref` (the `<input>`), and
+every `<input>` attribute.
+
+**Keyboard:** **↑** / **↓** step, **Page Up** / **Page Down** step by
+`largeStep`, **Home** / **End** jump to `min` / `max` where there is one, and
+**Escape** puts back the last committed number.
+
+The field shows a grouped, formatted number at rest and the plain number while
+it has focus, so separators never appear under the caret. An entry that cannot
+be read falls back to the last good value on blur rather than being discarded.
+
+`parseNumber`, `formatNumber`, `toEditText`, `localeParts`, `stepBy`,
+`snapToStep`, `clamp`, `round` and `decimalsOf` are exported from the
+framework-free `core` — the same parsing a server can reuse to accept what the
+field sends.
+
+**`wheel` is off by default.** Turning it on lets the wheel change a focused
+field, which is exactly the behaviour that makes `<input type="number">`
+dangerous in a long form.

package/source/beta-components/number-input/__tests__/core.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it } from "vitest";
+import { formatNumber } from "../core/format";
+import { localeParts, parseNumber, toEditText } from "../core/parse";
+import { clamp, decimalsOf, round, snapToStep, stepBy } from "../core/step";
+
+describe("localeParts", () => {
+  it("reads each locale's notation out of Intl", () => {
+    expect(localeParts("en-US")).toMatchObject({ group: ",", decimal: "." });
+    expect(localeParts("de-DE")).toMatchObject({ group: ".", decimal: "," });
+    expect(localeParts("fr-FR")).toMatchObject({ decimal: "," });
+    expect(localeParts("ar-EG").digits[0]).toBe("٠");
+  });
+});
+
+describe("parseNumber", () => {
+  it("reads the locale's own notation", () => {
+    expect(parseNumber("1,234.56", "en-US")).toBe(1234.56);
+    expect(parseNumber("1.234,56", "de-DE")).toBe(1234.56);
+    // The separator here is a narrow no-break space, not one anybody types.
+    expect(parseNumber("1 234,56", "fr-FR")).toBe(1234.56);
+  });
+
+  it("reads the locale's digits", () => {
+    expect(parseNumber("١٢٣", "ar-EG")).toBe(123);
+  });
+
+  it("ignores currency symbols, percent signs and spare spaces", () => {
+    expect(parseNumber("$1,234.56", "en-US")).toBe(1234.56);
+    expect(parseNumber("45 %", "en-US")).toBe(45);
+    expect(parseNumber("  12  ", "en-US")).toBe(12);
+  });
+
+  it("reads negatives, including the typographic minus", () => {
+    expect(parseNumber("-42", "en-US")).toBe(-42);
+    expect(parseNumber("−42", "en-US")).toBe(-42);
+    expect(parseNumber("-1.234,5", "de-DE")).toBe(-1234.5);
+  });
+
+  it("refuses what is not a number, and keeps that apart from empty", () => {
+    expect(parseNumber("", "en-US")).toBeNull();
+    expect(parseNumber("abc", "en-US")).toBeNull();
+    expect(parseNumber("1.2.3", "en-US")).toBeNull();
+    expect(parseNumber(".", "en-US")).toBeNull();
+    expect(parseNumber("-", "en-US")).toBeNull();
+  });
+
+  it("does not mistake one locale's group separator for another's decimal", () => {
+    // The whole point: the same five characters, two different numbers.
+    expect(parseNumber("1.234", "en-US")).toBe(1.234);
+    expect(parseNumber("1.234", "de-DE")).toBe(1234);
+  });
+});
+
+describe("toEditText", () => {
+  it("gives the plain form, in the locale's decimal separator", () => {
+    expect(toEditText(1234.5, "en-US")).toBe("1234.5");
+    expect(toEditText(1234.5, "de-DE")).toBe("1234,5");
+    expect(toEditText(null, "en-US")).toBe("");
+  });
+
+  it("round-trips through parseNumber", () => {
+    for (const locale of ["en-US", "de-DE", "fr-FR"]) {
+      expect(parseNumber(toEditText(-1234.56, locale), locale)).toBe(-1234.56);
+    }
+  });
+});
+
+describe("formatNumber", () => {
+  it("groups, and respects a fixed number of decimals", () => {
+    expect(formatNumber(1234.5, { locale: "en-US", decimals: 2 })).toBe("1,234.50");
+    expect(formatNumber(1234.5, { locale: "en-US", useGrouping: false })).toBe("1234.5");
+  });
+
+  it("formats money and percentages", () => {
+    expect(formatNumber(1234.5, { locale: "en-US", style: "currency", currency: "USD" })).toBe("$1,234.50");
+    expect(formatNumber(0.45, { locale: "en-US", style: "percent" })).toBe("45%");
+  });
+
+  it("falls back to a plain number when a currency is asked for without a code", () => {
+    // Intl throws on style:"currency" with no currency; a field mid-configuration
+    // should not take the page down with it.
+    expect(formatNumber(12, { locale: "en-US", style: "currency" })).toBe("12");
+  });
+
+  it("has nothing to show for no value", () => {
+    expect(formatNumber(null, { locale: "en-US" })).toBe("");
+  });
+});
+
+describe("decimalsOf and round", () => {
+  it("counts fraction digits, including exponent notation", () => {
+    expect(decimalsOf(1)).toBe(0);
+    expect(decimalsOf(0.25)).toBe(2);
+    expect(decimalsOf(1e-7)).toBe(7);
+  });
+
+  it("rounds the way the number reads, not the way the float sits", () => {
+    expect(round(1.005, 2)).toBe(1.01);
+    expect(round(2.675, 2)).toBe(2.68);
+    expect(round(-1.005, 2)).toBe(-1.01);
+  });
+});
+
+describe("stepBy", () => {
+  it("adds a step without floating-point drift", () => {
+    expect(stepBy(0.1, 1, { step: 0.2 })).toBe(0.3);
+    expect(stepBy(0.3, -1, { step: 0.1 })).toBe(0.2);
+    expect(stepBy(1.1, 1, { step: 0.1 })).toBe(1.2);
+  });
+
+  it("starts an empty field at min, or one step from zero", () => {
+    expect(stepBy(null, 1, { step: 1 })).toBe(1);
+    expect(stepBy(null, -1, { step: 1 })).toBe(-1);
+    expect(stepBy(null, 1, { step: 1, min: 5 })).toBe(5);
+    expect(stepBy(null, -1, { step: 1, min: 5 })).toBe(5);
+  });
+
+  it("stops at the limits", () => {
+    expect(stepBy(9, 1, { step: 5, max: 10 })).toBe(10);
+    expect(stepBy(1, -1, { step: 5, min: 0 })).toBe(0);
+  });
+
+  it("treats a step of zero as one, rather than freezing", () => {
+    expect(stepBy(3, 1, { step: 0 })).toBe(4);
+  });
+});
+
+describe("snapToStep", () => {
+  it("counts the grid from min", () => {
+    expect(snapToStep(7, { step: 5, min: 0 })).toBe(5);
+    expect(snapToStep(8, { step: 5, min: 0 })).toBe(10);
+    expect(snapToStep(7, { step: 5, min: 1 })).toBe(6);
+  });
+
+  it("works in fractions", () => {
+    expect(snapToStep(0.27, { step: 0.05, min: 0 })).toBe(0.25);
+  });
+
+  it("stays inside the limits", () => {
+    expect(snapToStep(99, { step: 10, min: 0, max: 95 })).toBe(95);
+  });
+});
+
+describe("clamp", () => {
+  it("pulls a value inside whichever limits exist", () => {
+    expect(clamp(5, 0, 10)).toBe(5);
+    expect(clamp(-1, 0, 10)).toBe(0);
+    expect(clamp(11, 0, 10)).toBe(10);
+    expect(clamp(11, undefined, undefined)).toBe(11);
+  });
+});

package/source/beta-components/number-input/core/format.ts

@@ -0,0 +1,37 @@
+import type { NumberFormatOptions } from "./types";
+
+const formats = new Map<string, Intl.NumberFormat>();
+
+/**
+ * Cached `Intl.NumberFormat`. Building one costs about as much as formatting a
+ * hundred numbers, and a grid of amounts formats thousands.
+ */
+export function numberFormat(options: NumberFormatOptions = {}): Intl.NumberFormat {
+  const { locale, style = "decimal", currency, decimals, useGrouping = true } = options;
+  const key = [locale ?? "", style, currency ?? "", decimals ?? "", useGrouping].join("|");
+  const cached = formats.get(key);
+  if (cached) return cached;
+
+  const format = new Intl.NumberFormat(locale, {
+    style: style === "currency" && !currency ? "decimal" : style,
+    currency: style === "currency" ? currency : undefined,
+    useGrouping,
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  });
+  formats.set(key, format);
+  return format;
+}
+
+/**
+ * The number as it is read rather than edited: grouped, with its currency
+ * symbol or percent sign.
+ *
+ * `style="percent"` follows `Intl` and multiplies by 100, so a field showing
+ * 45% holds 0.45. That is the convention every chart and CSS property already
+ * uses, and having one component disagree is worse than the surprise.
+ */
+export function formatNumber(value: number | null, options: NumberFormatOptions = {}): string {
+  if (value === null || !Number.isFinite(value)) return "";
+  return numberFormat(options).format(value);
+}

package/source/beta-components/number-input/core/index.ts

@@ -0,0 +1,4 @@
+export { formatNumber, numberFormat } from "./format";
+export { localeParts, parseNumber, toEditText, type NumberLocaleParts } from "./parse";
+export { clamp, decimalsOf, round, snapToStep, stepBy } from "./step";
+export type * from "./types";

package/source/beta-components/number-input/core/parse.ts

@@ -0,0 +1,118 @@
+/**
+ * Reading numbers the way the person in front of the screen writes them.
+ *
+ * This is the reason the component exists. `<input type="number">` understands
+ * one notation, roughly the C locale's, so a German typing `1.234,56` or an
+ * Egyptian typing `١٢٣٤` hands it something it calls invalid — and an invalid
+ * number input reports its value as the empty string, which loses what was
+ * typed as well as the meaning.
+ *
+ * Every part of a locale's notation is discovered from `Intl` rather than
+ * listed here: format a known number, look at the pieces that come back, and
+ * you have that locale's group separator, decimal separator, minus sign and
+ * digits, for any locale the runtime supports.
+ */
+
+export interface NumberLocaleParts {
+  group: string;
+  decimal: string;
+  minus: string;
+  /** The locale's digits, ASCII 0-9 in order. Latin digits for most locales. */
+  digits: readonly string[];
+}
+
+const partsCache = new Map<string, NumberLocaleParts>();
+
+function partValue(parts: Intl.NumberFormatPart[], type: Intl.NumberFormatPartTypes, fallback: string) {
+  return parts.find((part) => part.type === type)?.value ?? fallback;
+}
+
+/** The notation one locale uses, read out of `Intl` once and kept. */
+export function localeParts(locale?: string): NumberLocaleParts {
+  const key = locale ?? "";
+  const cached = partsCache.get(key);
+  if (cached) return cached;
+
+  const format = new Intl.NumberFormat(locale);
+  const sample = format.formatToParts(-12345.6);
+  const digits = Array.from({ length: 10 }, (_, index) =>
+    format.format(index).replace(/\s/g, ""),
+  );
+
+  const parts: NumberLocaleParts = {
+    group: partValue(sample, "group", ","),
+    decimal: partValue(sample, "decimal", "."),
+    minus: partValue(sample, "minusSign", "-"),
+    digits,
+  };
+  partsCache.set(key, parts);
+  return parts;
+}
+
+/** Turns a locale's digits into 0-9, leaving everything else alone. */
+function toAsciiDigits(text: string, digits: readonly string[]): string {
+  if (digits[0] === "0") return text;
+  let result = "";
+  for (const character of text) {
+    const index = digits.indexOf(character);
+    result += index === -1 ? character : String(index);
+  }
+  return result;
+}
+
+/**
+ * Reads what was typed, in the notation of `locale`.
+ *
+ * Returns `null` for anything that is not a number, including an empty field —
+ * the component keeps those apart by looking at the text, so an unreadable
+ * entry never silently becomes "nothing".
+ *
+ * Currency symbols, percent signs and stray spaces are ignored, so a pasted
+ * `"$1,234.56"` or `"45 %"` is read rather than rejected. Only one sign and one
+ * decimal separator are accepted: `"1.2.3"` is not a number in any locale.
+ */
+export function parseNumber(text: string, locale?: string): number | null {
+  const parts = localeParts(locale);
+  let value = toAsciiDigits(text.trim(), parts.digits);
+  if (value === "") return null;
+
+  // Every kind of space, including the narrow no-break space French and German
+  // use as a group separator, and the ordinary one people type by hand.
+  value = value.replace(/\s/gu, "");
+
+  const negative =
+    value.startsWith(parts.minus) || value.startsWith("-") || value.startsWith("−");
+  if (negative) value = value.replace(/^(-|−|-)/u, "").replace(parts.minus, "");
+
+  // Group separators go; the locale's decimal separator becomes a point. Doing
+  // it in this order matters where one locale's group is another's decimal.
+  if (parts.group !== "") value = value.split(parts.group).join("");
+  if (parts.decimal !== ".") value = value.split(parts.decimal).join(".");
+
+  // Whatever is left that is not a digit or the one point — currency symbols,
+  // percent signs, stray letters — is dropped, but a second point is not a
+  // typo to guess at.
+  const cleaned = value.replace(/[^0-9.]/gu, "");
+  if (cleaned === "" || cleaned === ".") return null;
+  if (cleaned.indexOf(".") !== cleaned.lastIndexOf(".")) return null;
+
+  const parsed = Number(cleaned);
+  if (!Number.isFinite(parsed)) return null;
+  return negative ? -parsed : parsed;
+}
+
+/**
+ * The text a number is edited as: the locale's decimal separator, no grouping
+ * and no currency symbol.
+ *
+ * Editing text and reading text are different jobs. Separators inserted while
+ * someone is typing move the caret out from under their fingers, so the field
+ * shows the plain form while it has focus and the formatted one the rest of
+ * the time.
+ */
+export function toEditText(value: number | null, locale?: string): string {
+  if (value === null || Number.isNaN(value)) return "";
+  const parts = localeParts(locale);
+  const text = String(value);
+  return parts.decimal === "." ? text : text.replace(".", parts.decimal);
+}

package/source/beta-components/number-input/core/step.ts

@@ -0,0 +1,73 @@
+import type { StepOptions } from "./types";
+
+/** How many fraction digits a number is written with. */
+export function decimalsOf(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  const text = String(value);
+  const exponent = text.indexOf("e-");
+  if (exponent !== -1) {
+    const digits = text.slice(0, exponent).split(".")[1]?.length ?? 0;
+    return digits + Number(text.slice(exponent + 2));
+  }
+  return text.split(".")[1]?.length ?? 0;
+}
+
+/**
+ * Rounds to `decimals` places without the drift of `toFixed` on binary
+ * fractions: 1.005 rounds up, as anyone reading the number expects.
+ */
+export function round(value: number, decimals: number): number {
+  if (!Number.isFinite(value)) return value;
+  const factor = 10 ** decimals;
+  // The epsilon nudge is what keeps 1.005 * 100 = 100.49999999999999 from
+  // rounding down to 1.00.
+  return Math.round((value + Number.EPSILON * Math.sign(value)) * factor) / factor;
+}
+
+export function clamp(value: number, min?: number, max?: number): number {
+  let result = value;
+  if (min !== undefined && result < min) result = min;
+  if (max !== undefined && result > max) result = max;
+  return result;
+}
+
+/**
+ * The value one press of an arrow or a stepper button produces.
+ *
+ * Arithmetic runs on integers scaled by the number of decimals involved, so
+ * `0.1 + 0.2` gives `0.3` rather than `0.30000000000000004` — a field that
+ * shows that after two presses looks broken, and rounding afterwards would
+ * only hide it one place further down.
+ *
+ * An empty field follows `<input type="number">`: the first press lands on
+ * `min` if there is one, and otherwise one step away from zero.
+ */
+export function stepBy(
+  value: number | null,
+  direction: 1 | -1,
+  { step, min, max }: StepOptions,
+): number {
+  const size = Math.abs(step) || 1;
+  if (value === null) return clamp(min ?? size * direction, min, max);
+
+  const scale = 10 ** Math.max(decimalsOf(value), decimalsOf(size));
+  const next = (Math.round(value * scale) + Math.round(size * scale) * direction) / scale;
+  return clamp(round(next, decimalsOf(1 / scale)), min, max);
+}
+
+/**
+ * Moves a value onto the step grid, counting from `min` where there is one.
+ *
+ * Only used when a field is asked to enforce its step (`snapToStep`). Typing is
+ * left alone until then: correcting 7 to 5 while someone is still typing 75
+ * would be unusable.
+ */
+export function snapToStep(value: number, { step, min, max }: StepOptions): number {
+  const size = Math.abs(step);
+  if (!Number.isFinite(size) || size === 0) return clamp(value, min, max);
+  const base = min ?? 0;
+  const scale = 10 ** Math.max(decimalsOf(size), decimalsOf(base), decimalsOf(value));
+  const steps = Math.round((Math.round(value * scale) - Math.round(base * scale)) / Math.round(size * scale));
+  const snapped = (Math.round(base * scale) + steps * Math.round(size * scale)) / scale;
+  return clamp(round(snapped, decimalsOf(size)), min, max);
+}

package/source/beta-components/number-input/core/types.ts

@@ -0,0 +1,32 @@
+export type NumberSize = "sm" | "md" | "lg";
+
+/** Plain number, an amount of money, or a percentage. */
+export type NumberStyle = "decimal" | "currency" | "percent";
+
+/** When a value outside `min`/`max` is pulled back into range. */
+export type ClampBehavior = "blur" | "strict" | "none";
+
+export interface NumberFormatOptions {
+  /** BCP 47 tag. Left out, the runtime's own locale is used. */
+  locale?: string;
+  /** Default `decimal`. */
+  style?: NumberStyle;
+  /** ISO 4217 code, required by `style="currency"`. */
+  currency?: string;
+  /** Exact number of fraction digits to show, and to round to when committing. */
+  decimals?: number;
+  /** Thousands separators. Default true. */
+  useGrouping?: boolean;
+}
+
+export interface StepOptions {
+  step: number;
+  min?: number;
+  max?: number;
+}
+
+export interface NumberInputLocaleText {
+  increment: string;
+  decrement: string;
+  clear: string;
+}

package/source/beta-components/number-input/index.ts

@@ -0,0 +1,5 @@
+export { NumberInput } from "./react/NumberInput";
+export type { NumberInputProps } from "./react/NumberInput";
+export { defaultNumberInputText } from "./react/locale";
+export type { NumberInputSlot } from "./react/props";
+export * from "./core";