@dashforge/tw 1.5.2 → 1.7.0

package/CHANGELOG.md

@@ -12,6 +12,208 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 > duplicated intentionally — no shared "lowest common denominator" headless
 > layer.
 
+## [1.7.0] — 2026-09-22
+
+### Added
+
+- **`<Checkbox required>` and `<Switch required>`** — the last two
+  bridge-integrated field components in the package that did not
+  accept `required` (the other twelve — Autocomplete, DatePicker,
+  DateRangePicker, DateTimePicker, NumberField, OTPField, RadioGroup,
+  Select, Slider, TextField, Textarea, TimePicker — already did).
+  Fixes BUG 21 in `libs/dashforge/README-BUG.md`. Both components now
+  render a `*` marker at the end of the label (styled via a new
+  `requiredMark` slot in the variants recipe, colour tokens matching
+  `textField.variants.ts` `requiredMark`) and set `aria-required="true"`
+  on the underlying Radix Root button via a **ref + `useEffect`
+  post-mount DOM setter** (Radix v1.3.3's own internal
+  context-then-re-emit path for `aria-required` was verified to strip
+  the attribute in production browser builds, though jsdom did not
+  catch that; the ref-based fallback is Radix-version-agnostic). HTML5
+  `required` is still passed through to Radix so
+  `Radix.CheckboxBubbleInput` picks it up for native form validation.
+  The `requiredMark` slot accepts a `className` via `slotProps` for
+  per-instance overrides, and via `theme.components.<Name>.slotProps`
+  for design-system-wide overrides. Presentational only, per the
+  library-wide convention: form-submit enforcement still requires
+  `rules={{ required: … }}` or a resolver rule. Seven regression tests
+  in `src/components/_shared/checkboxSwitchRequired.test.tsx` pin the
+  marker, the aria-required attribute, the no-render-when-omitted
+  invariant, and the slot override plumbing.
+
+### Fixed
+
+- **14 field components now honour `bridge.shouldUnregister`** (BUG 22
+  cross-package fix). Autocomplete, Checkbox, DatePicker,
+  DateRangePicker, DateTimePicker, NumberField, OTPField, RadioGroup,
+  Select, Slider, Switch, TextField, Textarea, TimePicker — the
+  unmount cleanup that previously ran unconditionally
+  (`queueMicrotask` schedule of `bridge.unregister(name)`) now bails
+  out first with `if (!cap?.shouldUnregister) return;`. When
+  `bridge.shouldUnregister` is `false` (the new Dashforge default,
+  set in `DashFormProvider`) the field's row in `formState.values`
+  survives the unmount, which is what `<Stepper>` and tab-swap
+  patterns need. Requires `@dashforge/ui-core@≥1.2.0` (new bridge
+  field) and `@dashforge/forms@≥1.2.0` (bridge population). The
+  StrictMode-safe `queueMicrotask` + `isMountedRef` pattern is
+  preserved verbatim; the change only decides *whether* to run the
+  scheduled cleanup.
+
+## [1.6.0] — 2026-09-15
+
+Minor release: three bug fixes (BUG 6 Dialog `actions` slot,
+BUG 9 tooltip DOM leak, BUG 13 pointer cursor across every
+interactive `<button>`), one runtime-rete for the DashForm mode
+misuse (BUG 2 wiring on Autocomplete / Select / RadioGroup /
+DatePicker via the new `useWarnIfControlledInFormMode` hook from
+`@dashforge/ui-core@1.1.0`), and one type-only refactor of
+`AutocompleteProps` into a discriminated union so form-mode and
+standalone-mode props stop compiling together.
+
+Requires `@dashforge/ui-core@^1.1.0` at runtime for the new hook.
+
+### Fixed
+
+- **Every interactive `<button>` in the package now shows the pointer
+  cursor on hover** (BUG 13). `buttonVariants.base` lacked
+  `cursor-pointer`, and the browser UA stylesheet leaves `<button>`
+  at `cursor: default` — so every `<Button>`, `<IconButton>`, and
+  `Button` in `variant="link"` mode read as "unclickable" to the
+  person hovering. Same shape found in the same-pass audit on
+  `tabs.variants.ts` (Radix.Tabs.Trigger),
+  `checkbox.variants.ts` (Radix.Checkbox.Root), and
+  `radioGroup.variants.ts` (Radix.RadioGroup.Item) — all four are
+  Radix primitives that surface as `<button>` under the hood. Fixed
+  by adding `cursor-pointer` on each interactive base/slot; the
+  existing `disabled:pointer-events-none` /
+  `data-[disabled]:cursor-not-allowed` state resets already handle
+  disabled instances, and `loading` on `<Button>` still overrides
+  to `cursor-wait` (tailwind-variants precedence). New test file
+  `_shared/cursorPointerAffordance.test.tsx` (7 assertions) pins
+  both the recipe-level class string and the rendered-DOM
+  `className` for `<Button>` and `<IconButton>`, so a future edit
+  that strips the class fails loudly. See `README-BUG.md § BUG 13`.
+
+### Added
+
+- **`<Dialog>` gained an `actions` prop** (`ReactNode`) that renders
+  a right-aligned footer row below the body and above the close
+  button. The variant + `slotProps.actions` entry already existed
+  in the package but had never been rendered — declared API that
+  did nothing (README-BUG § BUG 6). The alignment (`flex justify-end
+  gap-2 pt-2`) is the design-system decision encoded in
+  `dialog.variants.ts:52` and had been surfaced consistently in
+  hand-rolled action rows across consumer forms; the prop lets
+  consumers drop that boilerplate. Additive — existing dialogs
+  without `actions` render identically to before.
+
+- **Dev-mode warning when controlled / uncontrolled props are passed
+  to a bridge-integrated field inside a `<DashFormProvider>`** — the
+  runtime rete for README-BUG § BUG 2. Applied to `<Autocomplete>`,
+  `<Select>`, `<RadioGroup>` and `<DatePicker>` (the four
+  highest-usage field components; 10 more follow in a consistency
+  pass). Each component calls the new `useWarnIfControlledInFormMode`
+  hook from `@dashforge/ui-core` with its name and the destructured
+  controlled props; the hook warns once per
+  `(componentName, name, propKey)` triple with a message naming the
+  offending prop and the correct API (`<DashForm defaultValues={{
+  [name]: … }} />`). Zero cost in production — the effect body is
+  guarded by `process.env.NODE_ENV !== 'production'`.
+
+  Works alongside the existing type-surface split on `Autocomplete`
+  (which catches `rules + defaultValue` at compile time). The two
+  reties are complementary: types cover the `rules`-carrying case
+  before compile, the runtime warning covers the common case
+  (`rules`-less) on first render.
+
+### Changed
+
+- **`<Autocomplete>` — `AutocompleteProps` split into a discriminated
+  union of two mode variants** (form / standalone) to close the
+  type-surface bug where controlled/uncontrolled value props
+  (`value`, `defaultValue`, `onValueChange`) were accepted alongside
+  `rules` and silently ignored at runtime in form mode. The runtime
+  behaviour is unchanged (form-mode initial values still come from
+  `<DashForm defaultValues={...}>` via the bridge); the fix is
+  purely at the TypeScript layer:
+
+  - `AutocompleteFormMixin` marks form mode via optional `rules`;
+    the controlled/uncontrolled props are typed `never`.
+  - `AutocompleteStandaloneMixin` marks standalone mode via optional
+    `value` / `defaultValue` / `onValueChange`; `rules` is typed
+    `never`.
+  - Consumer surface `AutocompleteProps<TOption>` still exports as a
+    single name — the discrimination is transparent at import sites.
+
+  Consumer misuse audit (dash, docs-lab, kits) surfaced zero existing
+  callers with the mixed-mode pattern, so no downstream code
+  changes are required. Type-regression pinned by
+  `autocomplete.props.type-test.ts` (compile-only, three
+  `@ts-expect-error` markers). See `libs/dashforge/README-BUG.md`
+  § BUG 2 for the full context.
+
+### Fixed
+
+- **`<TextField>`, `<NumberField>` and `<Textarea>` no longer leak
+  the `tooltip` prop onto the rendered `<input>` / `<textarea>` as
+  an unknown HTML attribute.** These three components spread
+  `{...rest}` onto their DOM element after destructuring `merged`,
+  and `tooltip` was not in the destructured keys, so its value
+  landed on the DOM as `tooltip="…"` (the object form of the prop
+  stringified to `"[object Object]"`). React 19 forwards lowercase
+  unknown attrs silently, so nothing signalled it in dev — it took
+  a Playwright strict-mode failure to notice. Fix: three one-line
+  destructure edits consuming `tooltip` before the `...rest` catch.
+  Regression guard in
+  `libs/dashforge/tw/src/components/_shared/tooltipDomLeak.test.tsx`.
+  See README-BUG § BUG 9 — the report's original "all nine field
+  components" scope was corrected to these three after verification
+  (the other six do not spread `{...rest}` onto any DOM element and
+  therefore cannot leak structurally; Autocomplete was empirically
+  probed as an anchor).
+
+- **`<Autocomplete multiple>` — the control no longer overflows its
+  own width by ~6px** (a regression introduced by the BUG 3 chevron
+  wrap fix earlier in this Unreleased block). The controls group
+  and the input inside it both went from `min-w-[6rem]` to
+  `min-w-0`, so the input can shrink under pressure and the
+  `shrink-0` clear + chevron buttons always fit inside the group.
+  The previous floor combined with the shrink-0 buttons produced an
+  intrinsic min-content-size of ~156px and pushed the chevron 6px
+  past the group's right edge when chips had consumed most of the
+  outer wrapper — which turned into a horizontal scrollbar inside
+  a `<Dialog>` (whose body is `overflow-y-auto` and so computes
+  `overflow-x: auto`). The BUG 3 invariant is preserved: the
+  chevron stays on the same row as the input, never orphaned.
+  Fixes README-BUG § BUG 5.
+
+- **`<Autocomplete multiple>` — the chevron no longer wraps onto its
+  own line on narrow fields.** Multi mode's outer `flex-wrap`
+  context (needed so chip rows can grow vertically) used to let the
+  chevron drop onto an orphan row whenever the row width fell below
+  ~400px with two or more chips, producing a 90px-tall control with
+  an empty band. The fix keeps the `flex-wrap` on the outer wrapper
+  (so chips still wrap freely) but nests the input, clear `×` and
+  chevron in a `flex-nowrap` inner row of their own — that inner
+  row is structurally indivisible, so the chevron can never orphan.
+  Single-mode DOM is unchanged. See `libs/dashforge/README-BUG.md`
+  § BUG 3 for the full context and the DOM verification.
+- **`<Autocomplete>` — the listbox is now portaled** to `document.body`
+  via `RadixPopover.Portal`, so ancestor `overflow: hidden` /
+  `overflow: auto` containers can no longer clip it. Fixes the
+  fault-line that made "multi-select in a modal form" unusable
+  (`<Dialog><DashForm><Autocomplete multiple/></DashForm></Dialog>`
+  clipped the dropdown at the dialog body's scroll boundary, and the
+  same happened inside any `overflow-hidden` card such as the
+  `inventory-kit` `SectionCard`). See `libs/dashforge/README-BUG.md`
+  § BUG 1 for the full context. Width is still tied to the anchor
+  (via Radix's `--radix-popover-trigger-width` CSS var), keyboard
+  model / `aria-controls` / `aria-activedescendant` / `preventBlur`
+  on options are unchanged, and Radix's focus management is
+  intentionally disabled so focus stays on the input as before.
+  Downstream `overflowVisible`-prop workarounds can be removed
+  when this ships.
+
 ## [1.5.2] — 2026-08-30
 
 ### Fixed

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dashforge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.