@djangocfg/ui-core 2.1.540 → 2.1.542

package/README.md

@@ -51,7 +51,7 @@ import { UiProviders, Button, Card } from '@djangocfg/ui-core';
 | Group | Examples |
 |---|---|
 | `components/data/` | Avatar · Badge · Card · Table · BalancedText · Skeleton |
-| `components/forms/` | Button · Input · Textarea · Select · Switch · Checkbox · Slider · Form · DateField · TimeField · DateTimeField |
+| `components/forms/` | Button · Input · Textarea · Select · Switch · Checkbox · Slider · Form · DateField · TimeField · DateTimeField · MoneyField |
 | `components/feedback/` | Alert · Toast · Banner · Progress · Spinner |
 | `components/overlay/` | Dialog · Drawer · Popover · Tooltip · HoverCard · Sheet · ContextMenu · DropdownMenu |
 | `components/navigation/` | Sidebar · Tabs · Breadcrumb · Pagination · NavigationMenu · Command · Disclosure |
@@ -64,6 +64,8 @@ import { UiProviders, Button, Card } from '@djangocfg/ui-core';
 Imports stay flat — group folders are organisational. Native-engine date/time
 fields (`DateField` / `TimeField` / `DateTimeField`) have their own reference in
 [`forms/datetime-field/README.md`](src/components/forms/datetime-field/README.md).
+`MoneyField` carries an amount as integer minor units, not a float — see
+[`forms/money-field/README.md`](src/components/forms/money-field/README.md).
 
 ## Hooks (`/hooks`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.540",
+  "version": "2.1.542",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -119,6 +119,8 @@
   "files": [
     "dist",
     "src",
+    "!src/**/*.stories.tsx",
+    "!src/components/_gallery.tsx",
     "README.md",
     "LICENSE"
   ],
@@ -128,14 +130,14 @@
     "check:contrast": "node scripts/check-preset-contrast.mjs"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.540",
+    "@djangocfg/i18n": "^2.1.542",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
     "next": ">=14.0.0",
-    "react": "^19.2.4",
+    "react": "^19.0.0",
     "react-device-detect": "^2.2.3",
-    "react-dom": "^19.2.4",
+    "react-dom": "^19.0.0",
     "react-hook-form": "^7.69.0",
     "react-router": ">=7",
     "tailwindcss": "^4.1.18",
@@ -151,6 +153,7 @@
     }
   },
   "dependencies": {
+    "@chenglou/pretext": "^0.0.8",
     "@hookform/resolvers": "^5.4.0",
     "@radix-ui/react-accordion": "^1.2.16",
     "@radix-ui/react-alert-dialog": "^1.1.19",
@@ -202,17 +205,17 @@
     "tailwind-merge": "^3.6.0",
     "vaul": "1.1.2"
   },
-  "optionalDependencies": {
-    "@chenglou/pretext": "^0.0.8"
-  },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.540",
-    "@djangocfg/typescript-config": "^2.1.540",
+    "@djangocfg/eslint-config": "^2.1.542",
+    "@djangocfg/i18n": "^2.1.542",
+    "@djangocfg/typescript-config": "^2.1.542",
+    "@storybook/react-vite": "^10.5.0",
     "@types/node": "^24.13.3",
     "@types/react": "19.2.15",
     "@types/react-dom": "19.2.3",
     "lucide-react": "^0.545.0",
     "next": "^16.2.10",
+    "storybook": "^10.5.0",
     "typescript": "^5.9.3"
   },
   "publishConfig": {

package/src/components/data/BalancedText/hooks/useMaxLinesWidth.ts

@@ -8,32 +8,13 @@
 
 'use client';
 
+import { walkLineRanges } from '@chenglou/pretext';
 import * as React from 'react';
 import type { PreparedTextWithSegments } from '../../../../lib/pretext';
 
-// We replicate the structure of `useBalancedWidth` so that pretext stays an
-// optionalDependency: import the runtime lazily via require, mirror the
-// minimal `walkLineRanges` surface.
-interface WalkLineRange {
-  width: number;
-  start: number;
-  end: number;
-}
-interface PretextWalker {
-  walkLineRanges(
-    prepared: PreparedTextWithSegments,
-    maxWidth: number,
-    visit: (line: WalkLineRange) => void,
-  ): void;
-}
-
-let cached: PretextWalker | null = null;
-function getPretext(): PretextWalker {
-  if (cached) return cached;
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  cached = require('@chenglou/pretext') as PretextWalker;
-  return cached;
-}
+// Imported statically: `@chenglou/pretext` is ESM-only, so the previous lazy
+// `require` resolved in no runtime — under Vite/ESM `require` is not defined
+// and the first render threw `require is not defined`.
 
 export function useMaxLinesWidth(
   prepared: PreparedTextWithSegments | null,
@@ -43,8 +24,6 @@ export function useMaxLinesWidth(
   return React.useMemo(() => {
     if (!prepared || !maxLines || maxLines <= 0 || maxWidth <= 0) return 0;
 
-    const { walkLineRanges } = getPretext();
-
     // Natural line count at maxWidth. If it's already within the cap, defer
     // to `useBalancedWidth` (returning 0 means "don't use my value").
     let naturalCount = 0;

package/src/components/forms/button-download/index.tsx

@@ -63,7 +63,7 @@ export interface DownloadButtonProps extends Omit<ButtonProps, 'onClick'> {
   /**
    * Optional request body for POST requests
    */
-  body?: any
+  body?: unknown
 }
 
 type DownloadStatus = 'idle' | 'downloading' | 'success' | 'error'

package/src/components/forms/datetime-field/date-time-field.tsx

@@ -162,7 +162,7 @@ export const DateTimeField = React.forwardRef<HTMLInputElement, DateTimeFieldPro
             // flip the whole popover ABOVE the field when there's no room below.
             // `collisionPadding` just keeps it off the very edge.
             className="w-auto p-0"
-            align="start"
+            align={align}
             collisionPadding={12}
           >
             <Calendar

package/src/components/forms/editable/index.tsx

@@ -41,14 +41,14 @@ export interface EditableRootProps
   children?: React.ReactNode;
 }
 
-export interface EditablePreviewProps extends React.ComponentPropsWithoutRef<"span"> {}
+export type EditablePreviewProps = React.ComponentPropsWithoutRef<"span">;
 
 export interface EditableInputProps extends Omit<React.ComponentPropsWithoutRef<"input">, "value" | "defaultValue"> {
   /** Density — matches the standalone Input's `inputSize`. Default: 'default'. */
   inputSize?: 'default' | 'sm';
 }
 
-export interface EditableTextareaProps extends Omit<React.ComponentPropsWithoutRef<"textarea">, "value" | "defaultValue"> {}
+export type EditableTextareaProps = Omit<React.ComponentPropsWithoutRef<"textarea">, "value" | "defaultValue">;
 
 // =============================================================================
 // Context
@@ -163,7 +163,11 @@ const Editable = React.forwardRef<HTMLDivElement, EditableRootProps>(
       setEditing(false);
     }, [setValue, onValueCancel, setEditing]);
 
-    const startEditing = React.useCallback(() => {
+    // NOT exposed on the context below — consumers enter edit mode through
+    // `setIsEditing(true)`, which skips this snapshot of `previousValueRef`.
+    // Kept because it documents the intended enter-edit path; wiring it up is a
+    // behaviour change (cancel would then restore the value at edit-start).
+    const _startEditing = React.useCallback(() => {
       if (disabled || readOnly) return;
       previousValueRef.current = resolvedValue;
       setEditing(true);

package/src/components/forms/input/index.tsx

@@ -35,6 +35,18 @@ export interface InputProps extends React.ComponentProps<"input"> {
    * - `sm` — 36px, smaller text (inline edits, dense rows, settings chips).
    */
   inputSize?: 'default' | 'sm';
+  /**
+   * Drop the field chrome — border, surface, rounding, focus ring — for an
+   * input that sits inside a control that draws them itself (`InputGroup`).
+   *
+   * A wrapper cannot do this from the outside: `focus-visible:ring-0` and
+   * `focus-visible:ring-1` are the same specificity, so which one wins is
+   * decided by their order in the generated stylesheet, not by the order they
+   * are passed to `cn()`. Suppression like that works until a Tailwind version
+   * reorders its output. Omitting the rules is the only stable way to not have
+   * them.
+   */
+  bare?: boolean;
 }
 
 /**
@@ -49,9 +61,19 @@ export interface InputProps extends React.ComponentProps<"input"> {
  * and a tight 1px solid ring of the same colour doubles it to a clean ~2px
  * edge (NO blurry translucent halo). `:focus-visible` only, so mouse users on
  * other controls don't get rings. This is the sharp Vercel/Linear look.
+ *
+ * Split in two so an input inside `InputGroup` can omit the chrome rather than
+ * override it — see `bare`.
  */
-const INPUT_BASE =
-  "flex w-full rounded-[var(--radius)] border border-border bg-input shadow-sm transition-[color,background-color,border-color,box-shadow] file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50";
+/** Everything an input needs regardless of who draws its edge. */
+const INPUT_CORE =
+  "flex w-full transition-[color,background-color,border-color,box-shadow] file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50";
+
+/** The field's own edge: border, surface, rounding, and the focus treatment. */
+const INPUT_CHROME =
+  "rounded-[var(--radius)] border border-border bg-input shadow-sm focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring";
+
+const INPUT_BASE = cn(INPUT_CORE, INPUT_CHROME);
 
 const INPUT_SIZE: Record<NonNullable<InputProps['inputSize']>, string> = {
   default: "h-10 px-3 py-2 text-base md:text-sm",
@@ -59,8 +81,10 @@ const INPUT_SIZE: Record<NonNullable<InputProps['inputSize']>, string> = {
 };
 
 /** Resolve the full input class for a given size. */
-export const inputClass = (size: NonNullable<InputProps['inputSize']> = 'default') =>
-  cn(INPUT_BASE, INPUT_SIZE[size]);
+export const inputClass = (
+  size: NonNullable<InputProps['inputSize']> = 'default',
+  bare = false,
+) => cn(bare ? INPUT_CORE : INPUT_BASE, INPUT_SIZE[size], bare && 'h-full px-0');
 
 /** Default-size input styling — kept as a named export for reuse (e.g. Editable). */
 export const INPUT_CLASS = inputClass('default');
@@ -71,9 +95,12 @@ export const INPUT_CLASS = inputClass('default');
  */
 export const TEXTAREA_CLASS = cn(INPUT_BASE, 'min-h-[60px] px-3 py-2 text-sm');
 
+/** `TEXTAREA_CLASS` without the field's own edge — for use inside `InputGroup`. */
+export const TEXTAREA_BARE_CLASS = cn(INPUT_CORE, 'min-h-[60px] py-3 text-sm');
+
 const Input = React.forwardRef<HTMLInputElement, InputProps>(
-  ({ className, type, storageKey, storageType, storageTtl, inputSize = 'default', onChange, defaultValue, value, ...props }, ref) => {
-    const resolvedClass = cn(inputClass(inputSize), className);
+  ({ className, type, storageKey, storageType, storageTtl, inputSize = 'default', bare = false, onChange, defaultValue, value, ...props }, ref) => {
+    const resolvedClass = cn(inputClass(inputSize, bare), className);
     const storageOptions: UseStoredValueOptions | undefined =
       storageKey ? { storage: storageType ?? 'local', ttl: storageTtl } : undefined;
 

package/src/components/forms/input-group/index.tsx

@@ -14,7 +14,12 @@ function InputGroup({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="input-group"
       role="group"
       className={cn(
-        "group/input-group border-input dark:bg-input/30 shadow-xs relative flex w-full items-center rounded-[var(--radius)] border outline-none transition-[color,box-shadow]",
+        // `border-border` and `bg-input`, the same pair `Input` resolves to. The
+        // group had `border-input`, which in the light theme is the *fill*
+        // token (97% L) rather than the edge one (86%) — so its border was
+        // nearly invisible next to a plain field's, and a focused money input
+        // showed a crisp inner rectangle inside a ghost of an outer one.
+        "group/input-group border-border bg-input shadow-xs relative flex w-full items-center rounded-[var(--radius)] border outline-none transition-[color,background-color,border-color,box-shadow]",
         // Matches `Input`'s default size (h-10), not its `sm` one.
         //
         // This was `h-9`, which made a grouped input a row shorter than a bare
@@ -29,13 +34,28 @@ function InputGroup({ className, ...props }: React.ComponentProps<"div">) {
         "h-10 has-[>textarea]:h-auto",
 
         // Variants based on alignment.
+        //
+        // Each side gets its inset from EITHER the addon or the control, never
+        // both and never neither. With an addon the addon supplies the edge
+        // gap and the control only needs to clear it (pl-2); with no addon the
+        // control has to stand in for it (pl-3, matching `Input`'s own px-3).
+        //
+        // The `not-has-` half is load-bearing: `bare` strips the control's
+        // padding, so a group without an addon on a side used to leave its text
+        // flush against the border — visible on any addon-less group, and on a
+        // MoneyField with `showSymbol={false}`.
         "has-[>[data-align=inline-start]]:[&>input]:pl-2",
+        "not-has-[>[data-align=inline-start]]:[&>input]:pl-3",
         "has-[>[data-align=inline-end]]:[&>input]:pr-2",
+        "not-has-[>[data-align=inline-end]]:[&>input]:pr-3",
         "has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col has-[>[data-align=block-start]]:[&>input]:pb-3",
         "has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-end]]:[&>input]:pt-3",
 
-        // Focus state.
-        "has-[[data-slot=input-group-control]:focus-visible]:ring-ring has-[[data-slot=input-group-control]:focus-visible]:ring-1",
+        // Focus state. Border AND ring, the same pair `Input` uses on its own
+        // — the group is standing in for a field's edge, so it has to draw the
+        // whole treatment. Ring alone left the group's border its resting grey
+        // while the control inside lit up, which reads as two nested fields.
+        "has-[[data-slot=input-group-control]:focus-visible]:border-ring has-[[data-slot=input-group-control]:focus-visible]:ring-ring has-[[data-slot=input-group-control]:focus-visible]:ring-1",
 
         // Error state.
         "has-[[data-slot][aria-invalid=true]]:ring-destructive/20 has-[[data-slot][aria-invalid=true]]:border-destructive dark:has-[[data-slot][aria-invalid=true]]:ring-destructive/40",
@@ -154,17 +174,14 @@ const InputGroupInput = React.forwardRef<
   return (
     <Input
       ref={ref}
+      bare
       data-slot="input-group-control"
-      className={cn(
-        // `focus-visible:border-transparent` alongside `ring-0`: the group
-        // draws the focus ring for the whole control, and `INPUT_BASE` also
-        // turns the input's own border to `--ring` on focus. Suppressing only
-        // the ring left that border visible, so a focused money field showed a
-        // rectangle inside a rectangle — the addon sitting outside the inner
-        // one, which is exactly what the group exists to prevent.
-        "flex-1 rounded-none border-0 bg-transparent shadow-none focus-visible:border-transparent focus-visible:ring-0 dark:bg-transparent",
-        className
-      )}
+      // `bare` omits the field chrome instead of overriding it. Cancelling it
+      // from here needed `focus-visible:ring-0` to beat `focus-visible:ring-1`
+      // at equal specificity — decided by stylesheet order, not by `cn()` — so
+      // a focused money field drew a rectangle inside a rectangle whenever the
+      // order went the other way.
+      className={cn("flex-1", className)}
       {...props}
     />
   )
@@ -177,11 +194,9 @@ function InputGroupTextarea({
 }: React.ComponentProps<"textarea">) {
   return (
     <Textarea
+      bare
       data-slot="input-group-control"
-      className={cn(
-        "flex-1 resize-none rounded-none border-0 bg-transparent py-3 shadow-none focus-visible:ring-0 dark:bg-transparent",
-        className
-      )}
+      className={cn("flex-1 resize-none", className)}
       {...props}
     />
   )

package/src/components/forms/mask-input/index.tsx

@@ -237,7 +237,11 @@ const MaskInput = React.forwardRef<HTMLInputElement, MaskInputProps>(
         if (!data) return;
 
         const start = input.selectionStart ?? 0;
-        const end = input.selectionEnd ?? 0;
+        // NOTE: only the selection START is consulted. A non-collapsed
+        // selection (`selectionEnd !== start`) is validated as if the caret sat
+        // at its left edge, so typing over a selection checks the wrong mask
+        // slot. handleKeyDown below does handle `start !== end`; this path does
+        // not. Left as-is — fixing it changes input behaviour.
 
         // Determine which mask position we're at
         let maskPos = 0;
@@ -382,7 +386,7 @@ const MaskInput = React.forwardRef<HTMLInputElement, MaskInputProps>(
           updateValue(newRaw);
         }
       },
-      [maskParts, maskChar, onKeyDown, updateValue]
+      [maskParts, onKeyDown, updateValue]
     );
 
     const computeNextEmptyCaret = React.useCallback(() => {
@@ -424,7 +428,7 @@ const MaskInput = React.forwardRef<HTMLInputElement, MaskInputProps>(
         setIsFocused(false);
         onBlur?.(event);
         if (cleanOnBlur) {
-          const { complete, raw } = applyMask(rawValue, maskParts, maskChar);
+          const { complete } = applyMask(rawValue, maskParts, maskChar);
           if (!complete) {
             updateValue("");
           }

package/src/components/forms/money-field/README.md

@@ -0,0 +1,79 @@
+# MoneyField
+
+An amount input that formats as you type and reports **minor units** — cents,
+not dollars.
+
+```tsx
+const [price, setPrice] = useState(1999);   // $19.99
+
+<MoneyField currency="USD" value={price} onValueChange={setPrice} />
+```
+
+## The value is an integer
+
+`value` and `onValueChange` carry minor units. A field that hands back `19.99`
+hands back a number that does not exist in binary floating point: totals drift
+by a cent, and the bug surfaces in an invoice rather than in a test. `1999` is
+exact.
+
+This matches `@djangocfg/payments`, which moves `MinorUnits` for the same
+reason — a value goes from this field to a charge with no conversion between.
+
+## Entry is till-style
+
+Digits fill from the right: `1` `9` `9` reads $1.99. The caret never has to sit
+"before the decimal point", which is the state that makes most currency inputs
+confusing.
+
+Every keystroke rewrites the whole display, so the caret is restored by **digit
+count, not string offset**. Inserting a thousands separator shifts every
+character after it, and an offset-based restore moves the caret a place — the
+single most common defect in a currency input.
+
+## Separators come from `Intl`
+
+The decimal mark is a comma across most of Europe. Guessing it means `1.234` is
+read as either 1.234 or 1234 depending on the user, with nothing on screen to
+say which happened. Pass `locale` to pin it; otherwise the runtime's is used.
+
+## Zero-decimal currencies
+
+¥500 is five hundred yen, not five. `currencyFractionDigits()` and
+`minorUnitFactor()` are exported for callers that need the same rule:
+
+```ts
+minorUnitFactor('USD')          // 100
+minorUnitFactor('JPY')          // 1
+currencyFractionDigits('JPY')   // 0
+```
+
+The zero-decimal list mirrors `@djangocfg/payments`' `domain/money.ts`. It is
+duplicated rather than imported because `ui-core` sits **below** `payments` in
+the dependency direction and may not depend on it.
+
+## Props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `value` | `number` | Amount in minor units (controlled). |
+| `defaultValue` | `number` | Uncontrolled initial amount, minor units. |
+| `onValueChange` | `(minorUnits: number) => void` | |
+| `currency` | `string` | ISO 4217. Drives symbol, decimals, minor-unit factor. Default `USD`. |
+| `locale` | `string` | BCP 47. Defaults to the runtime's. |
+| `showSymbol` | `boolean` | Default `true`. Set false when the label carries the unit. |
+| `max` | `number` | Minor units. Entry beyond it is ignored, not clamped after the fact. |
+| `groupClassName` | `string` | Applied to the group, to size the whole control. |
+
+## Accessibility
+
+The currency symbol is `aria-hidden` — a screen reader announcing "dollar sign"
+on entry is noise. The accessible name has to come from a label you associate
+yourself:
+
+```tsx
+<label htmlFor={id}>Price</label>
+<MoneyField id={id} … />
+```
+
+Text is left-aligned so it hugs the symbol. Right alignment belongs to a column
+of amounts in a table; pass `className="text-right"` there.