@turkish-technology/spar
0.3.2
Patch Changes
- #273
0cfccc1Thanks @harun-demir! - Spar is now developed and published from the takeoff-v2 repository. The package'srepositoryfield and its README links point there, and the README's LICENSE link works again. No code changes.
[0.3.1] - 2026-11-05
Dialog, Popover, DropdownMenu, Select
Fixed
- Nested floating layers no longer dismiss their parent. Picking an option
in a
Select, or pressing inside aPopoverorDropdownMenu, that is rendered inside aDialogContent(or another layer) closed the parent, because nested content is portaled todocument.bodyand the outside check only looked at the parent's DOM node. An interaction that starts in a layer's React subtree, portaled children included, now counts as inside, for pointer and focus events alike. This applies to any React portal rendered from inside the layer, not only Spar layers: pressing in a toast or a third-party overlay rendered from insideDialogContentno longer callsonPointerDownOutsideor dismisses the dialog. Genuine outside presses still dismiss, and consumeronPointerDownCapture/onFocusCapturehandlers on the content are composed, not replaced.
[0.3.0] - 2026-09-16
Accordion
Fixed
- Arrow, Home and End keys skip disabled items. Navigation previously tried to focus the disabled trigger and stalled there; it now moves to the next enabled trigger, wraps around, and Home/End land on the first/last enabled item.
- Keyboard navigation follows DOM order and keeps working after an item is inserted between existing ones or replaced by another (shared item registry fix, also used by Radio, Select and Tabs).
Breadcrumb
Fixed
- Consumer
onClick/onKeyDownonBreadcrumb.Linkare composed, not replaced. They run first, andpreventDefault()skipsonPress/onNavigate; Enter callsonPressexactly once. - Disabled links only block the activation keys. Enter/Space are prevented;
every other key still reaches the consumer
onKeyDown.
Button
Fixed
- Inert anchors no longer navigate. While
disabledorisLoading, a non-native element cancels the click's default action, andas='a'additionally dropshref.
Checkbox
Added
indeterminateprop. Layers the mixed state overchecked/defaultCheckedwithout owning the value, giving uncontrolled checkboxes a first-class way to enter and leave the indeterminate state; a toggle still firesonChange(true)and advances the internal state underneath.
Dialog
Fixed
- Render-prop
open()andtoggle()no longer bypassdisabled. Calling them from a disabledDialog.Triggeris a no-op and does not fireonOpenChange;close()remains available.
DropdownMenu
Fixed
onEscapeKeyDown,onPointerDownOutsideandonFocusOutsidenow honourevent.preventDefault(). The Escape handler runs before the menu acts on the key and the veto is read from the native event; outside pointer-down and outside focus no longer close unconditionally. For modal menus, preventing default inonFocusOutsideskips the focus recapture; for non-modal menus it keeps the menu open.
Popover
Fixed
onOpenAutoFocuscan now veto the open-time auto-focus. The handler receives a cancelable event before focus moves into the content;event.preventDefault()skips the focus move (previously it fired after focusing with a non-cancelable event).onFocusOutside/onInteractOutsidecan now keep the popover open on the focus path. Nativefocusinis not cancelable, so handlers receive a cancelablefocusoutsideFocusEventdispatched on the newly focused element;event.preventDefault()prevents the close, matching the pointer path.Popover.Triggernow receives the documented${id}-triggerid. A consumer-suppliedidprop still overrides it.
Radio
Fixed
Radio.Itemrenders a<span role="radio">by default instead of<label>. ARIA in HTML allows no role on<label>, so every item failed axe'saria-allowed-role; the item's text still names the radio and the native input staysaria-hidden. Selectors such aslabel[role="radio"]need updating.- The selected value reaches native form data exactly once. The root's extra
<input type="hidden">was removed; each item's visually hidden<input type="radio">is the only native representation and still carriesrequiredfor native validity. onChangefires only when the value actually changes. Clicking orselect()-ing the already-checked item no longer re-emits the same value.- A
readOnlygroup no longer changes its value from the keyboard. Arrow keys and Home/End still move focus. aria-readonlymoved from the items to the radiogroup, the only role that permits it.- The group stays reachable when the checked item is disabled. The first enabled item becomes the tab stop.
- Toggling
disabledon a middle item keeps the arrow-key order. Re-enabled items resume their DOM position instead of moving to the end.
Changed
- Consumer
onKeyDown/onFocus/onBluronRadioandonClick/onKeyDown/onFocusonRadio.Itemare composed with the built-in handlers. The consumer handler runs first;event.preventDefault()vetoes the built-in navigation or selection. - Enter selects the focused item when
selectOnFocusisfalse, matching the documented Space/Enter behavior.
Select
Fixed
onEscapeKeyDowncan now veto the close. The handler receives the native event, and the close checks that same event'sdefaultPreventedinstead of the synthetic snapshot.onCloseAutoFocusis now called. Fires when the listbox closes from inside (Escape, Enter/Space, Tab, item click) right before focus returns to the trigger;preventDefault()keeps focus where it is. Not called for outside-pointer dismissal, which moves no focus.- Initially-open selects receive focus. With
defaultOpenor a controlledopenon mount, the listbox is focused after mount so Escape, arrows and Enter work without reopening.
Changed
Select.Separatoris presentational by default. Rendersrole="presentation"+aria-hidden="true"so alistboxno longer failsaria-required-children; passrole='separator'to restore separator semantics.
Tabs
Fixed
onValueChangeno longer fires on mount. The automatic first-tab selection (uncontrolled, novalue/defaultValue) is derived from the first tab in DOM order instead of being written through the change handler, so consumers only hear about user-driven changes. It also follows the next first tab if the selected one unmounts instead of leaving nothing selected.onValueChangeonly fires when the value actually changes. Clicking, pressing Enter/Space on, or navigating back onto the already selected tab no longer re-reports the same value.- Enter and Space respect
disabledon non-button triggers. In manual activation mode a focused disabledTabs.Triggerrendered withas(e.g.as='div') could still be selected from the keyboard.
Tooltip
Fixed
onEscapeKeyDownnow fires for Escape on the trigger and honourspreventDefault. The callback never ran while focus was on the trigger and the documented veto was ignored; it now runs before the internal close for Escape on the trigger, inside the content, or anywhere in the document, andpreventDefault()on the received event keeps the tooltip open.- Consumer
onKeyDownonTooltip.Contentis composed with the internal Escape handler instead of replacing it.
Changed
- Removed the unused
onPointerDownOutside,onOpenAutoFocusandonCloseAutoFocusprops fromTooltip.Content. They were never called and were forwarded to the DOM, producing unknown-prop warnings (type-level breaking change only).
[0.2.3] - 2026-09-12
Dialog
Fixed
preventDefault()inonEscapeKeyDownnow keeps the dialog open. The handler receives the nativeKeyboardEvent, but the close check read the React event, which never sees apreventDefaultmade on the native one, so the veto was ignored.- Closing moves focus back to the element that opened the dialog.
DialogContentcleared the stored element on close beforeDialogcould read it, sorestoreFocus(on by default) never restored focus.
[0.2.2] - 2026-09-08
Input — Masking
Added
Input.Fieldnow accepts amaskprop. A mask can be a shape pattern (blocks,delimiter/delimiters,numericOnly,letterOnly,uppercase/lowercase), a regex pattern (regex), one of the built-in presets ({ date: true },{ time: true },{ number: true }), or a customMaskResolverfunction. Omittingmaskleaves the field's behaviour unchanged.onValueChange(value, meta)onInput.Field, fired only whilemaskis set. It reports the masked value plusraw,completedandisometadata, and also fires for changes the mask applies itself (delimiter-aware deletes, undo) that never surface as a DOMchangeevent. Prefer it overonChangeon a masked field.useMaskhook exported for building masked inputs outsideInput.Field, along withUseMaskOptions/UseMaskReturn.- Built-in mask factories exported —
createDateMask,createNumberMaskandcreateTimeMask— so a preset can be composed, wrapped or extended with the same tools userland has. - Mask types exported from the package root:
Mask,MaskPattern,MaskPreset,MaskResolver,MaskResolverContext,MaskResolverResult,MaskChangeMeta, and the per-kind option interfaces.
Fixed
- Corrected caret mapping, delimiter-aware deletes, IME composition handling and regex bounds in the masking engine.
Input.Fieldmay now set its owndisabled,requiredandreadOnlyinstead of always deferring to the surroundingFieldcontext.
[0.2.1] - 2026-07-14
DropdownMenu / Select — Scrollable Viewport
Added
DropdownMenu.Viewport— an optional scrollable wrapper insideDropdownMenu.Contentfor long menus.Select.Viewport— the matching scrollable part forSelect.Content, implemented as a pure styling wrapper so both components behave the same.
Fixed
- The highlighted item is now kept in view from
DropdownMenu.Contentusing nativescrollIntoView. - Documented
Content'saligndefault correctly as'center'.
[0.2.0] - 2026-06-24
First stable release of the 0.2 line, promoting the 0.2.0-beta series to the
latest dist-tag (previously latest was 0.1.4). It bundles all changes since
0.1.4 — the Field primitive and form-control integration, the Accordion rework,
the Select API simplification, and the Label/Field optional rename — together
with the new Toast component below.
Toast — New Component
Added
- New headless
Toastprimitive for accessible, imperatively-driven notifications.createToaster()returns a controller that canupdate,dismiss,clear, and wrap apromise; the render-prop<Toaster>component renders the live queue, and theToastnamespace (Toast.Root,Toast.Title,Toast.Description,Toast.Action,Toast.Close) composes each item.useToastContextexposes per-item state. - Configurable
placement,duration,maxVisibleToasts,overlapstacking, and default toasttype. - Available as a tree-shakeable sub-path export:
@turkish-technology/spar/toast, matching the per-component export convention used by the rest of the library.
[0.2.0-beta.2] - 2026-06-17
Label — isOptional Renamed to optional
Changed
Label'sisOptionalprop renamed tooptionalto drop the redundantisprefix and align with the other boolean state props (required,disabled,readOnly,invalid). The emitteddata-optionalattribute is unchanged, so styling hooks keep working.
Migration
- Replace
<Label isOptional>with<Label optional>.
Field — optional Prop Added
Added
Fieldroot now accepts anoptionalprop, mirroring the other field state props. It propagates through Field context to nested controls and theFieldLabel, and is exposed viadata-optionalfor styling.
[0.2.0-beta.1] - 2026-05-20
Select — Initial Render Label Bug Fix
Fixed
- The trigger now shows the selected item's
labelon the very first paint whendefaultValue(or controlledvalue) is set. Previously the trigger flashed the placeholder until the user opened the dropdown once, because items were registered in a regular effect (post-paint) and the root context value did not depend on the items map, so consumers never re-rendered after registration. - Item registration moved from
useEffecttouseLayoutEffect(with an SSR fallback) so registration commits before paint. itemsadded to the root context-valueuseMemodependency list so that changes to the registry trigger a re-render ofSelect.Trigger.Select.Item's registration effect dependency list narrowed to the stableregisterItemcallback (instead of the whole context object) to avoid the re-entrant render loop that the above changes would otherwise introduce.
Select — API Simplification (SelectValue & SelectItemText Removed)
Removed
Select.Value(SelectValue) — The standalone value-display component has been removed. The trigger now computes and renders the selected item's text internally.Select.ItemText(SelectItemText) — The item text wrapper component has been removed. Its only purpose was to register text for typeahead and value display via DOM reading; this is now handled entirely by thelabelprop onSelect.Item.
Changed
Select.Trigger— Now accepts aplaceholderprop (shown when no value is selected) and renders the selected item'slabelautomatically. Supports render-prop children with a newlabelfield inSelectTriggerRenderPropsfor custom display layouts.Select.Item— Thelabelprop is now the sole mechanism for registering display text used in typeahead filtering and in the trigger's value display. Previously this was exposed astextValue; it has been renamed tolabelto match the native HTML<option label>attribute and to read naturally next to the item's children.aria-labelledbyon trigger — No longer references a value node id (which no longer exists). When wrapped in aField, it references the Field label id only. Standalone triggers rely onaria-labeldirectly.
Why
The SelectValue and SelectItemText sub-components added indirection without
meaningful benefit. SelectValue was a passive display node whose content was
already derivable from context; SelectItemText existed solely to read DOM text
for typeahead — a concern better served by an explicit label prop. Removing
both flattens the component tree, reduces the compound-component surface area,
and makes the API easier to learn:
// Before
<Select.Trigger>
<Select.Value placeholder='Choose…' />
</Select.Trigger>
<Select.Item value='x'>
<Select.ItemText>Premium</Select.ItemText>
</Select.Item>
// After
<Select.Trigger placeholder='Choose…' />
<Select.Item value='x' label='Premium'>Premium</Select.Item>
Migration
- Move the
placeholderprop from<Select.Value>to<Select.Trigger>. - Remove
<Select.Value>from inside the trigger. - Replace
<Select.ItemText>Text</Select.ItemText>inside each item with alabel='Text'prop on<Select.Item>and render the text as direct children. - Rename any existing
textValueprops on<Select.Item>tolabel. The behavior is identical; this rename aligns the API with native HTML<option label>. - If you used render-prop children on Trigger for custom layouts, the render
props now include
label(the display text of the selected item) instead oftextValue. - If you styled the placeholder/value text via a
Select.Valueselector, move those styles toSelect.Trigger. The trigger now carries[data-placeholder]when no value is selected, so empty-state styling lives on the trigger itself.
[0.2.0-beta.0] - 2026-05-17
First beta of the 0.2 line. Significant work since 0.1.4 including the Field
primitive, Switch / Radio / Checkbox / Select integration with Field, Accordion
API rework, and form prop standardization. Published under the beta dist-tag;
latest remains 0.1.4. See git history for the full set of changes.
[0.0.1] - 2025-10-16
Added
- Initial release of @turkish-technology/spar
- Headless React components with TypeScript support
- Components:
- Accordion
- Breadcrumb
- Button
- Checkbox
- Collapsible
- DropdownMenu
- Input
- Label
- Popover
- Radio
- Select
- Switch
- Tabs
- Tooltip
- Full accessibility (WCAG 2.2 AA) support
- React 19 compatibility
- ESM and CommonJS builds
- TypeScript definitions
- Tree-shakeable exports