@fictjs/ui-primitives 0.1.0

package/docs/components/disclosure/navigation-menu.md

@@ -0,0 +1,43 @@
+# NavigationMenu
+
+Application/navigation menu primitives.
+
+## Components
+
+- `NavigationMenuRoot`
+- `NavigationMenuList`
+- `NavigationMenuItem`
+- `NavigationMenuTrigger`
+- `NavigationMenuContent`
+- `NavigationMenuLink`
+- `NavigationMenuIndicator`
+- `NavigationMenuViewport`
+
+## Minimal Example
+
+```tsx
+import {
+  NavigationMenuRoot,
+  NavigationMenuList,
+  NavigationMenuItem,
+  NavigationMenuTrigger,
+  NavigationMenuContent,
+  NavigationMenuLink,
+} from '@fictjs/ui-primitives'
+
+<NavigationMenuRoot>
+  <NavigationMenuList>
+    <NavigationMenuItem value="docs">
+      <NavigationMenuTrigger>Docs</NavigationMenuTrigger>
+      <NavigationMenuContent>
+        <NavigationMenuLink href="/guide">Guide</NavigationMenuLink>
+      </NavigationMenuContent>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenuRoot>
+```
+
+## Accessibility Notes
+
+- Triggers should expose open/closed state and remain keyboard reachable.
+- Content should contain real link targets, not only generic containers.

package/docs/components/disclosure/tabs.md

@@ -0,0 +1,35 @@
+# Tabs
+
+Accessible tabs primitives with roving focus tab list.
+
+## Components
+
+- `TabsRoot`
+- `TabsList`
+- `TabsTrigger`
+- `TabsContent`
+
+## Key APIs
+
+- `TabsRoot` accepts `id?: string` to stabilize trigger/content id mapping
+- `TabsTrigger` supports `asChild`
+
+## Minimal Example
+
+```tsx
+import { TabsRoot, TabsList, TabsTrigger, TabsContent } from '@fictjs/ui-primitives'
+
+<TabsRoot defaultValue="overview">
+  <TabsList>
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="details">Details</TabsTrigger>
+  </TabsList>
+  <TabsContent value="overview">Overview panel</TabsContent>
+  <TabsContent value="details">Details panel</TabsContent>
+</TabsRoot>
+```
+
+## Accessibility Notes
+
+- Keep `TabsTrigger`/`TabsContent` value pairs unique to avoid broken `aria-controls` links.
+- Use meaningful trigger labels so screen-reader users can navigate tab options quickly.

package/docs/components/feedback/toast.md

@@ -0,0 +1,60 @@
+# Toast
+
+Queued toast primitives with provider-managed lifecycle.
+
+## Components / Hook
+
+- `ToastProvider`
+- `ToastViewport`
+- `ToastRoot`
+- `ToastTitle`
+- `ToastDescription`
+- `ToastAction`
+- `ToastClose`
+- `useToast()`
+
+## Provider API
+
+- `ToastProvider`
+- `duration?: number` default timeout for queued toasts
+- `useToast().show({ title, description, duration? })` enqueues a toast and returns `id`
+- `useToast().dismiss(id)` removes a toast immediately
+
+## Viewport Semantics
+
+- `ToastViewport` renders queued toasts with `aria-live="polite"`
+- Toasts auto-dismiss by duration (item duration overrides provider default)
+
+## Toast Parts
+
+- `ToastRoot` renders title/description and default close action
+- `ToastAction` requires `altText` and maps it to accessible label
+- `ToastClose` is a plain close button primitive for custom templates
+
+## Minimal Example
+
+```tsx
+import { ToastProvider, ToastViewport, useToast } from '@fictjs/ui-primitives'
+
+function SaveButton() {
+  const toast = useToast()
+  return (
+    <button
+      type="button"
+      onClick={() => toast.show({ title: 'Saved', description: 'Changes synced.' })}
+    >
+      Save
+    </button>
+  )
+}
+
+<ToastProvider duration={3000}>
+  <SaveButton />
+  <ToastViewport />
+</ToastProvider>
+```
+
+## Accessibility Notes
+
+- Keep toast title/description concise so live-region announcements stay scannable.
+- `ToastAction` must include meaningful `altText` for assistive technologies.

package/docs/components/form/calendar.md

@@ -0,0 +1,35 @@
+# Calendar
+
+Headless date grid primitive with month navigation and controlled/uncontrolled value.
+
+## Components
+
+- `CalendarRoot` (alias: `Calendar`)
+- `CalendarHeader`
+- `CalendarTitle`
+- `CalendarPrevButton`
+- `CalendarNextButton`
+- `CalendarGrid`
+
+## Key APIs
+
+- `value/defaultValue/onValueChange` for selected day
+- `month/defaultMonth/onMonthChange` for visible month
+- `showOutsideDays`, `weekStartsOn`, `weekdayFormat`, `locale`
+- `disabled?: (date: Date) => boolean` to block specific dates
+
+## Minimal Example
+
+```tsx
+import { CalendarRoot } from '@fictjs/ui-primitives'
+
+<CalendarRoot
+  defaultMonth={new Date(2026, 0, 1)}
+  onValueChange={date => console.log(date)}
+/>
+```
+
+## Accessibility Notes
+
+- Calendar grid uses `role="grid"` / `role="gridcell"` with `aria-selected`.
+- Keep day labels and surrounding form labels explicit for screen-reader context.

package/docs/components/form/controls.md

@@ -0,0 +1,52 @@
+# Form Controls
+
+Core form-control primitives.
+
+## Components
+
+- `Label`
+- `Checkbox`
+- `RadioGroup` / `RadioItem`
+- `Switch` / `SwitchThumb`
+- `Toggle` / `ToggleGroup` / `ToggleGroupItem`
+
+## Minimal Example
+
+```tsx
+import {
+  Label,
+  Checkbox,
+  RadioGroup,
+  RadioItem,
+  Switch,
+  SwitchThumb,
+  Toggle,
+  ToggleGroup,
+  ToggleGroupItem,
+} from '@fictjs/ui-primitives'
+
+<Label htmlFor="tos">Accept terms</Label>
+<Checkbox id="tos" name="tos" defaultChecked>Accept</Checkbox>
+
+<RadioGroup name="density" defaultValue="comfortable">
+  <RadioItem value="compact">Compact</RadioItem>
+  <RadioItem value="comfortable">Comfortable</RadioItem>
+</RadioGroup>
+
+<Switch name="notifications" defaultChecked>
+  <SwitchThumb />
+</Switch>
+
+<Toggle defaultPressed>Bold</Toggle>
+
+<ToggleGroup type="multiple" defaultValue={['left']}>
+  <ToggleGroupItem value="left">Left</ToggleGroupItem>
+  <ToggleGroupItem value="center">Center</ToggleGroupItem>
+</ToggleGroup>
+```
+
+## Accessibility Notes
+
+- Keep textual labels adjacent to icon-only controls (`Checkbox`, `Switch`, `Toggle`).
+- Radio groups should represent one conceptual choice and use clear item labels.
+- `aria-checked` / `aria-pressed` states are built-in; ensure visual state mirrors them.

package/docs/components/form/date-picker.md

@@ -0,0 +1,44 @@
+# DatePicker
+
+Popover-based date picker composed from `Popover` + `Calendar`.
+
+## Components
+
+- `DatePickerRoot`
+- `DatePickerTrigger`
+- `DatePickerValue`
+- `DatePickerContent`
+- `DatePickerCalendar`
+
+## Key APIs
+
+- `DatePickerRoot`: `value/defaultValue/onValueChange`, `open/defaultOpen/onOpenChange`
+- `DatePickerTrigger`: supports polymorphism and `asChild` through inherited popover trigger semantics
+- `DatePickerContent`: `closeOnSelect` defaults to `true`
+- `DatePickerCalendar`: forwards calendar options while binding to date-picker value/open state
+
+## Minimal Example
+
+```tsx
+import {
+  DatePickerRoot,
+  DatePickerTrigger,
+  DatePickerValue,
+  DatePickerContent,
+  DatePickerCalendar,
+} from '@fictjs/ui-primitives'
+
+<DatePickerRoot>
+  <DatePickerTrigger>
+    <DatePickerValue placeholder="Pick a date" />
+  </DatePickerTrigger>
+  <DatePickerContent>
+    <DatePickerCalendar />
+  </DatePickerContent>
+</DatePickerRoot>
+```
+
+## Accessibility Notes
+
+- Trigger/content wiring is inherited from popover/dialog semantics.
+- Keep explicit labels around date picker fields so users understand date context and format expectations.

package/docs/components/form/form-field.md

@@ -0,0 +1,39 @@
+# Form Field Structure
+
+Semantic form field primitives.
+
+## Components
+
+- `Form`
+- `FormField`
+- `FormLabel`
+- `FormControl`
+- `FormDescription`
+- `FormMessage`
+
+## Minimal Example
+
+```tsx
+import {
+  Form,
+  FormField,
+  FormLabel,
+  FormControl,
+  FormDescription,
+  FormMessage,
+} from '@fictjs/ui-primitives'
+
+<Form>
+  <FormField name="email">
+    <FormLabel>Email</FormLabel>
+    <FormControl as="input" type="email" required />
+    <FormDescription>Use your work email.</FormDescription>
+    <FormMessage>Invalid email format.</FormMessage>
+  </FormField>
+</Form>
+```
+
+## Accessibility Notes
+
+- `FormLabel` and `FormControl` id wiring is automatic; avoid overriding ids unless necessary.
+- Keep `FormMessage` contextual and specific because it is announced with alert semantics.

package/docs/components/form/inputs.md

@@ -0,0 +1,99 @@
+# Advanced Inputs
+
+Interactive input primitives.
+
+## Components
+
+- `Slider`
+- `RangeSlider`
+- `CalendarRoot` / `Calendar*`
+- `DatePickerRoot` / `DatePicker*`
+- `SelectRoot` / `SelectTrigger` / `SelectValue` / `SelectContent` / `SelectItem`
+- `ComboboxRoot` / `ComboboxInput` / `ComboboxList` / `ComboboxItem`
+
+## Slider / RangeSlider
+
+- Controlled + uncontrolled support via `value/defaultValue/onValueChange`
+- `Slider` maps to native range input semantics
+- `RangeSlider` maintains ordered tuple `[start, end]`
+
+## Select
+
+- `SelectRoot` supports both controlled and uncontrolled `value` and `open`
+- `SelectTrigger` toggles listbox visibility (`aria-haspopup="listbox"`)
+- `SelectContent` supports `forceMount` for always-mounted popups
+- `SelectItem` commits value and closes popup by default
+
+## Combobox
+
+- `ComboboxInput` drives query and opens list on focus/input
+- `ComboboxItem` performs simple text filtering against current query
+- Selecting an item commits value, syncs query, and closes list
+
+## Calendar / DatePicker
+
+- `CalendarRoot` manages selected date and visible month state
+- `DatePickerRoot` composes popover trigger/content around calendar interactions
+- `DatePickerCalendar` closes picker on selection by default (`closeOnSelect=true`)
+
+## Minimal Example
+
+```tsx
+import {
+  Slider,
+  RangeSlider,
+  SelectRoot,
+  SelectTrigger,
+  SelectValue,
+  SelectContent,
+  SelectItem,
+  ComboboxRoot,
+  ComboboxInput,
+  ComboboxList,
+  ComboboxItem,
+  CalendarRoot,
+  DatePickerRoot,
+  DatePickerTrigger,
+  DatePickerValue,
+  DatePickerContent,
+  DatePickerCalendar,
+} from '@fictjs/ui-primitives'
+
+<Slider min={0} max={100} defaultValue={40} />
+<RangeSlider min={0} max={100} defaultValue={[20, 80]} />
+
+<SelectRoot defaultValue="apple">
+  <SelectTrigger>
+    <SelectValue placeholder="Pick one" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="apple">Apple</SelectItem>
+    <SelectItem value="orange">Orange</SelectItem>
+  </SelectContent>
+</SelectRoot>
+
+<ComboboxRoot>
+  <ComboboxInput placeholder="Search user" />
+  <ComboboxList>
+    <ComboboxItem value="alice">Alice</ComboboxItem>
+    <ComboboxItem value="bob">Bob</ComboboxItem>
+  </ComboboxList>
+</ComboboxRoot>
+
+<CalendarRoot defaultMonth={new Date(2026, 0, 1)} />
+
+<DatePickerRoot>
+  <DatePickerTrigger>
+    <DatePickerValue placeholder="Pick a date" />
+  </DatePickerTrigger>
+  <DatePickerContent>
+    <DatePickerCalendar />
+  </DatePickerContent>
+</DatePickerRoot>
+```
+
+## Accessibility Notes
+
+- For select/combobox, keep option text concise and distinct to avoid ambiguous announcements.
+- If you force-mount popup content, keep hidden-state signaling consistent.
+- Range-like controls should include external labels that describe scale and intent.

package/docs/components/interaction/dismissable-layer.md

@@ -0,0 +1,28 @@
+# DismissableLayer
+
+Provides common dismissal semantics used by overlays.
+
+## Events
+
+- `onEscapeKeyDown`
+- `onInteractOutside`
+- `onPointerDownOutside`
+- `onFocusOutside`
+- `onDismiss`
+
+Only the top-most mounted layer responds.
+
+## Minimal Example
+
+```tsx
+import { DismissableLayer } from '@fictjs/ui-primitives'
+
+<DismissableLayer onDismiss={() => console.log('dismissed')}>
+  <div role="dialog">Layer content</div>
+</DismissableLayer>
+```
+
+## Accessibility Notes
+
+- Dismiss paths should include explicit close controls in addition to outside/Escape behavior.
+- Only the top-most layer responds; stack layered popups intentionally.

package/docs/components/interaction/focus-scope.md

@@ -0,0 +1,27 @@
+# FocusScope / FocusTrap
+
+`FocusScope` manages keyboard focus within a subtree.
+
+## Features
+
+- optional focus trapping with Tab cycling
+- optional auto focus on mount
+- optional focus restore on unmount
+
+`FocusTrap` is `FocusScope` with `trapped=true`.
+
+## Minimal Example
+
+```tsx
+import { FocusScope } from '@fictjs/ui-primitives'
+
+<FocusScope trapped loop autoFocus restoreFocus>
+  <button type="button">First</button>
+  <button type="button">Second</button>
+</FocusScope>
+```
+
+## Accessibility Notes
+
+- Use focus trapping only for modal contexts.
+- Keep at least one tabbable control inside the scope for predictable keyboard flow.

package/docs/components/interaction/live-region.md

@@ -0,0 +1,26 @@
+# LiveRegion / Announce
+
+Screen-reader announcement primitives.
+
+## API
+
+- `LiveRegionProvider`
+- `useAnnouncer()`
+- `Announce`
+
+Two regions are maintained: polite and assertive.
+
+## Minimal Example
+
+```tsx
+import { Announce, LiveRegionProvider } from '@fictjs/ui-primitives'
+
+<LiveRegionProvider>
+  <Announce politeness="polite" message="Saved successfully" />
+</LiveRegionProvider>
+```
+
+## Accessibility Notes
+
+- Use `polite` for non-urgent updates and `assertive` only for urgent interruptions.
+- Keep announcements short and specific to reduce repeated verbosity in screen readers.

package/docs/components/interaction/popper.md

@@ -0,0 +1,30 @@
+# Popper
+
+Lightweight floating positioning primitives.
+
+## Components
+
+- `PopperRoot`
+- `PopperAnchor`
+- `PopperContent`
+- `PopperArrow`
+
+Supports side/alignment offsets and updates on resize/scroll.
+
+## Minimal Example
+
+```tsx
+import { PopperAnchor, PopperContent, PopperRoot } from '@fictjs/ui-primitives'
+
+<PopperRoot>
+  <PopperAnchor>
+    <button type="button">Open</button>
+  </PopperAnchor>
+  <PopperContent side="bottom" align="start">Floating content</PopperContent>
+</PopperRoot>
+```
+
+## Accessibility Notes
+
+- Popper only positions; you still need roles, labels, and dismissal semantics in the floating content.
+- Keep anchor/content relationship explicit with `aria-controls` or `aria-describedby` where applicable.

package/docs/components/interaction/roving-focus.md

@@ -0,0 +1,27 @@
+# RovingFocusGroup
+
+Implements roving `tabIndex` behavior for composite widgets.
+
+## Components
+
+- `RovingFocusGroup`
+- `RovingFocusItem`
+
+Supports arrow navigation, `Home`, `End`, and optional looping.
+
+## Minimal Example
+
+```tsx
+import { RovingFocusGroup, RovingFocusItem } from '@fictjs/ui-primitives'
+
+<RovingFocusGroup orientation="horizontal" loop>
+  <RovingFocusItem as="button">Bold</RovingFocusItem>
+  <RovingFocusItem as="button">Italic</RovingFocusItem>
+  <RovingFocusItem as="button">Underline</RovingFocusItem>
+</RovingFocusGroup>
+```
+
+## Accessibility Notes
+
+- Use roving focus for composite widgets where one tab stop controls many arrow-key targets.
+- Ensure orientation matches expected arrow-key behavior for assistive technology users.

package/docs/components/interaction/scroll-lock.md

@@ -0,0 +1,22 @@
+# ScrollLock
+
+Locks `document.body` scroll while mounted.
+
+- supports nested locks with internal reference counting
+- compensates scrollbar width via `padding-right`
+
+## Minimal Example
+
+```tsx
+import { ScrollLock } from '@fictjs/ui-primitives'
+
+<div>
+  <ScrollLock enabled />
+  <div role="dialog" aria-modal="true">Modal body</div>
+</div>
+```
+
+## Accessibility Notes
+
+- Scroll lock is not a complete modal solution; combine with focus trap and dismissal handling.
+- Verify nested overlays unlock scroll only after the final lock is removed.

package/docs/components/layout/layout.md

@@ -0,0 +1,61 @@
+# Layout and P2 Primitives
+
+## Components
+
+- `ScrollArea`, `ScrollAreaViewport`, `ScrollAreaScrollbar`, `ScrollAreaThumb`
+- `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle`
+- `AspectRatio`
+- `Progress`, `Meter`
+- `Skeleton`
+- `KeyboardModeProvider`, `FocusVisible`, `useKeyboardMode`
+
+## Minimal Example
+
+```tsx
+import {
+  ScrollArea,
+  ScrollAreaViewport,
+  ScrollAreaScrollbar,
+  ScrollAreaThumb,
+  ResizablePanelGroup,
+  ResizablePanel,
+  ResizableHandle,
+  AspectRatio,
+  Progress,
+  Meter,
+  Skeleton,
+  KeyboardModeProvider,
+  FocusVisible,
+} from '@fictjs/ui-primitives'
+
+<ScrollArea>
+  <ScrollAreaViewport style={{ maxHeight: '120px' }}>Long content...</ScrollAreaViewport>
+  <ScrollAreaScrollbar orientation="vertical">
+    <ScrollAreaThumb />
+  </ScrollAreaScrollbar>
+</ScrollArea>
+
+<ResizablePanelGroup direction="horizontal">
+  <ResizablePanel defaultSize={40}>Left</ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel defaultSize={60}>Right</ResizablePanel>
+</ResizablePanelGroup>
+
+<AspectRatio ratio={16 / 9}>
+  <img src="/placeholder.jpg" alt="Preview" />
+</AspectRatio>
+
+<Progress value={65} max={100} />
+<Meter value={0.7} min={0} max={1} low={0.3} high={0.8} optimum={0.9} />
+<Skeleton loading>Loading card...</Skeleton>
+
+<KeyboardModeProvider>
+  <FocusVisible as="button">Focusable action</FocusVisible>
+</KeyboardModeProvider>
+```
+
+## Accessibility Notes
+
+- Custom scroll/resize affordances should preserve keyboard access and visible focus states.
+- `Progress` and `Meter` should have nearby textual context explaining value meaning.
+- `Skeleton` placeholders are visual only; pair with status messaging for assistive tech when needed.

package/docs/components/menu/context-menu.md

@@ -0,0 +1,44 @@
+# ContextMenu
+
+Context menu primitives opened from right-click position.
+
+## Components
+
+- `ContextMenuRoot`
+- `ContextMenuTrigger`
+- `ContextMenuContent`
+- `ContextMenuItem`
+- `ContextMenuSub`
+- `ContextMenuSubTrigger`
+- `ContextMenuSubContent`
+
+## Key APIs
+
+- `ContextMenuTrigger` and `ContextMenuItem` support `asChild`
+- `ContextMenuContent` supports `onEscapeKeyDown`, `onPointerDownOutside`, `onFocusOutside`, `onInteractOutside`
+- Outside handlers are interceptable: calling `event.preventDefault()` blocks dismissal
+- `ContextMenuSub*` composes nested menus with side positioning (`right/start` by default)
+
+## Minimal Example
+
+```tsx
+import {
+  ContextMenuRoot,
+  ContextMenuTrigger,
+  ContextMenuContent,
+  ContextMenuItem,
+} from '@fictjs/ui-primitives'
+
+<ContextMenuRoot>
+  <ContextMenuTrigger>Right-click here</ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem>Rename</ContextMenuItem>
+    <ContextMenuItem>Delete</ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenuRoot>
+```
+
+## Accessibility Notes
+
+- Pair right-click entry with an alternate keyboard path in your product UX.
+- Menu items should have clear action labels and predictable close behavior.