@fictjs/ui-primitives 0.1.0

package/docs/README.md

@@ -0,0 +1,39 @@
+# Documentation Index
+
+Start here for all package documentation.
+
+## Getting Started
+
+- `README.md`: package overview, install, quick start, and command map
+- `docs/examples.md`: copyable composition snippets
+- `examples/README.md`: executable demo app and screenshot baseline workflow
+
+## Component Documentation
+
+- `docs/components/core`
+- `docs/components/interaction`
+- `docs/components/overlay`
+- `docs/components/menu`
+- `docs/components/feedback`
+- `docs/components/disclosure`
+- `docs/components/form`
+- `docs/components/layout`
+
+Each component file includes:
+
+- minimal example
+- accessibility notes
+- behavior/API summary
+
+## Engineering and Quality Docs
+
+- `docs/api-reference.md`: full export index
+- `docs/architecture.md`: implementation design and internal patterns
+- `docs/testing.md`: testing strategy and expectations
+- `docs/accessibility.md`: accessibility verification checklist
+- `docs/release.md`: release and publish checklist
+- `CONTRIBUTING.md`: contributor workflow and PR quality expectations
+
+## Source Planning
+
+- `ui-primitives.md`: source planning/scope document used during implementation

package/docs/accessibility.md

@@ -0,0 +1,50 @@
+# Accessibility Checklist
+
+Use this checklist when building or reviewing primitives.
+
+## Global checks
+
+1. Every interactive element is keyboard reachable (`Tab`, `Shift+Tab`, `Enter`, `Space`, arrow keys where applicable).
+2. Focus is always visible and never trapped unless intentionally scoped (`FocusScope`, modal overlays).
+3. Interactive controls expose semantic roles and states (`role`, `aria-*`, `data-state`).
+4. Dismiss flows are complete: Escape, outside click (when expected), and explicit close action.
+5. Dynamic regions (toast/live messages) use polite or assertive live-region semantics.
+6. Hidden helper text is exposed only to assistive tech (`VisuallyHidden`, `AccessibleIcon` labels).
+
+## Overlay and popups
+
+- `Dialog` / `AlertDialog`: trigger uses `aria-haspopup`, content has dialog role, title/description IDs are wired, focus enters content and restores on close.
+- `Popover` / `HoverCard` / `Tooltip`: trigger/content relationships are explicit (`aria-describedby` for tooltip), and hover/focus behavior has deterministic open/close.
+- Modal overlays lock background scroll and block outside interaction where expected.
+
+## Menus and navigation
+
+- Menu roots render proper container roles (`menu`, `menubar`) and items expose matching item roles.
+- Checkbox/radio menu items expose checked state (`aria-checked`) and maintain controlled/uncontrolled behavior.
+- Roving focus handles arrow-key traversal and loop behavior consistently.
+- Navigation content open state is exposed through `data-state` and trigger state attributes.
+
+## Tabs and disclosure
+
+- Tabs: triggers use `role="tab"` + `aria-controls`, content uses `role="tabpanel"` + `aria-labelledby`.
+- Accordion/collapsible triggers expose expanded state and toggle content visibility predictably.
+- `forceMount` variants keep semantic state in sync while hidden (`data-state="closed"` / inactive).
+
+## Form primitives
+
+- Labels are explicitly associated with controls (`for` / `id`).
+- Descriptions and messages are connected through `aria-describedby`.
+- Error messages use alert semantics when they need immediate announcement.
+- Select/combobox/listbox controls provide role/state attributes for active and selected options.
+
+## Feedback primitives
+
+- Toast viewport has live region semantics and close/action controls have explicit labels.
+- Auto-dismiss timing can be overridden and manual dismissal is always possible.
+
+## Verification workflow
+
+1. Run `pnpm test` to verify behavioral and semantic assertions.
+2. Run through keyboard-only flows for each updated primitive.
+3. Validate screen-reader announcements for dialogs, form errors, and toasts.
+4. Use the runnable demo (`pnpm examples:dev`) for manual interaction walkthroughs.

package/docs/api-reference.md

@@ -0,0 +1,200 @@
+# API Reference Index
+
+This document lists runtime exports from `@fictjs/ui-primitives`.
+
+Note: each module also exports related TypeScript interfaces/types for props.
+
+## Core
+
+- `Primitive`
+- `PrimitiveElements`
+- `Slot`
+- `Presence`
+- `Portal`
+- `PortalHost`
+- `VisuallyHidden`
+- `Separator`
+- `AccessibleIcon`
+- `IdProvider`
+- `useId`
+
+## Interaction
+
+- `FocusScope`
+- `FocusTrap`
+- `DismissableLayer`
+- `RovingFocusGroup`
+- `RovingFocusItem`
+- `ScrollLock`
+- `LiveRegionProvider`
+- `useAnnouncer`
+- `Announce`
+- `PopperRoot`
+- `PopperAnchor`
+- `PopperContent`
+- `PopperArrow`
+
+## Overlay
+
+- `DialogRoot`
+- `DialogPortal`
+- `DialogTrigger`
+- `DialogOverlay`
+- `DialogContent`
+- `DialogClose`
+- `DialogTitle`
+- `DialogDescription`
+- `AlertDialogRoot`
+- `AlertDialogTrigger`
+- `AlertDialogPortal`
+- `AlertDialogOverlay`
+- `AlertDialogContent`
+- `AlertDialogTitle`
+- `AlertDialogDescription`
+- `AlertDialogAction`
+- `AlertDialogCancel`
+- `PopoverRoot`
+- `PopoverTrigger`
+- `PopoverContent`
+- `PopoverClose`
+- `TooltipProvider`
+- `TooltipRoot`
+- `TooltipTrigger`
+- `TooltipContent`
+- `HoverCardRoot`
+- `HoverCardTrigger`
+- `HoverCardContent`
+- `CommandPaletteRoot`
+- `CommandPaletteTrigger`
+- `CommandPaletteContent`
+- `CommandPaletteInput`
+- `CommandPaletteList`
+- `CommandPaletteItem`
+- `CommandPaletteEmpty`
+- `CommandPaletteGroup`
+- `CommandPaletteSeparator`
+- `CommandPaletteClose`
+
+## Menu
+
+- `DropdownMenuRoot`
+- `DropdownMenuTrigger`
+- `DropdownMenuContent`
+- `DropdownMenuItem`
+- `DropdownMenuCheckboxItem`
+- `DropdownMenuRadioGroup`
+- `DropdownMenuRadioItem`
+- `DropdownMenuSub`
+- `DropdownMenuSubTrigger`
+- `DropdownMenuSubContent`
+- `DropdownMenuLabel`
+- `DropdownMenuSeparator`
+- `ContextMenuRoot`
+- `ContextMenuTrigger`
+- `ContextMenuContent`
+- `ContextMenuItem`
+- `ContextMenuSub`
+- `ContextMenuSubTrigger`
+- `ContextMenuSubContent`
+- `MenubarRoot`
+- `MenubarMenu`
+- `MenubarTrigger`
+- `MenubarContent`
+- `MenubarItem`
+
+## Feedback
+
+- `ToastProvider`
+- `ToastViewport`
+- `ToastRoot`
+- `ToastTitle`
+- `ToastDescription`
+- `ToastAction`
+- `ToastClose`
+- `useToast`
+
+## Disclosure and Navigation
+
+- `CollapsibleRoot`
+- `CollapsibleTrigger`
+- `CollapsibleContent`
+- `AccordionRoot`
+- `AccordionItem`
+- `AccordionTrigger`
+- `AccordionContent`
+- `TabsRoot`
+- `TabsList`
+- `TabsTrigger`
+- `TabsContent`
+- `NavigationMenuRoot`
+- `NavigationMenuList`
+- `NavigationMenuItem`
+- `NavigationMenuTrigger`
+- `NavigationMenuContent`
+- `NavigationMenuLink`
+- `NavigationMenuIndicator`
+- `NavigationMenuViewport`
+
+## Form and Inputs
+
+- `Label`
+- `Checkbox`
+- `RadioGroup`
+- `RadioItem`
+- `Switch`
+- `SwitchThumb`
+- `Toggle`
+- `ToggleGroup`
+- `ToggleGroupItem`
+- `Slider`
+- `RangeSlider`
+- `CalendarRoot`
+- `Calendar`
+- `CalendarHeader`
+- `CalendarTitle`
+- `CalendarPrevButton`
+- `CalendarNextButton`
+- `CalendarGrid`
+- `DatePickerRoot`
+- `DatePickerTrigger`
+- `DatePickerValue`
+- `DatePickerContent`
+- `DatePickerCalendar`
+- `SelectRoot`
+- `SelectTrigger`
+- `SelectValue`
+- `SelectContent`
+- `SelectItem`
+- `ComboboxRoot`
+- `ComboboxInput`
+- `ComboboxList`
+- `ComboboxItem`
+- `Form`
+- `FormField`
+- `FormLabel`
+- `FormControl`
+- `FormDescription`
+- `FormMessage`
+
+## Layout
+
+- `ScrollArea`
+- `ScrollAreaViewport`
+- `ScrollAreaScrollbar`
+- `ScrollAreaThumb`
+- `ResizablePanelGroup`
+- `ResizablePanel`
+- `ResizableHandle`
+- `AspectRatio`
+- `Progress`
+- `Meter`
+- `Skeleton`
+- `KeyboardModeProvider`
+- `FocusVisible`
+- `useKeyboardMode`
+
+## Import Pattern
+
+```ts
+import { DialogRoot, TabsRoot, ToastProvider } from '@fictjs/ui-primitives'
+```

package/docs/architecture.md

@@ -0,0 +1,113 @@
+# Architecture Notes
+
+This document describes the design and implementation structure of `@fictjs/ui-primitives`.
+
+## Goals
+
+- Provide headless primitives with minimal assumptions about styling
+- Keep accessibility and interaction semantics explicit and testable
+- Support controlled and uncontrolled patterns consistently
+- Compose small primitives into larger compound components
+
+## Repository Structure
+
+- `src/components/core`: foundational composition primitives
+- `src/components/interaction`: focus, dismissal, positioning, live regions
+- `src/components/overlay`: dialog/popover/tooltip/hover-card/command-palette
+- `src/components/menu`: dropdown/context/menubar patterns
+- `src/components/disclosure`: tabs/accordion/collapsible/navigation menu
+- `src/components/form`: form controls, calendar/date-picker, and structured field helpers
+- `src/components/layout`: layout and visual utility primitives
+- `src/internal`: shared internals used across components
+
+## Core Implementation Patterns
+
+### Runtime and hooks foundation
+
+- Components are built on top of `@fictjs/runtime` signals/effects/context.
+- Cross-cutting event and timing behavior is standardized with `@fictjs/hooks` (for example `useEventListener` and `useDebounceFn`).
+- This keeps lifecycle cleanup centralized and reduces duplicated low-level DOM/timer logic.
+
+### Compound component + context
+
+Many features are implemented as root + parts using context.
+
+Examples:
+
+- `DialogRoot` + `DialogTrigger` + `DialogContent`
+- `TabsRoot` + `TabsList` + `TabsTrigger` + `TabsContent`
+- `SelectRoot` + `SelectTrigger` + `SelectContent` + `SelectItem`
+
+### Controlled and uncontrolled state
+
+Shared helper:
+
+- `src/internal/state.ts` -> `createControllableState`
+
+This ensures consistent behavior for `value/defaultValue/onChange` style APIs.
+
+### Accessor-safe reads
+
+Shared helper:
+
+- `src/internal/accessor.ts` -> `read`
+
+This unifies plain values and accessor functions (`T | () => T`) across props.
+
+### Id and ref composition
+
+Shared helpers:
+
+- `src/internal/ids.ts` -> `createId`, `useId`, and `IdProvider` for deterministic aria wiring
+- `src/internal/ref.ts` -> composed refs across parent and child consumers
+
+Most root primitives accept explicit `id` props so teams can force stable SSR/hydration wiring.
+
+## Interaction Stack Design
+
+### Focus management
+
+- `FocusScope` handles auto-focus, trap/loop behavior, and restore-focus semantics.
+- Modal overlays use focus scoping as part of their lifecycle.
+
+### Dismiss behavior
+
+- `DismissableLayer` centralizes Escape, outside pointer, and outside focus dismissal.
+- Only the top-most active layer can dismiss to avoid nested-layer conflicts.
+- Outside interactions are interceptable (`onEscapeKeyDown`, `onPointerDownOutside`, `onFocusOutside`, `onInteractOutside`).
+
+### Positioning
+
+- `PopperRoot`, `PopperAnchor`, and `PopperContent` provide anchor-based placement.
+- Overlay and menu primitives compose on top of Popper where needed.
+
+### Portal strategy
+
+- `Portal` and `PortalHost` support default body portaling or scoped containers.
+- Overlay components default to portal rendering but can opt into inline rendering.
+
+## Accessibility Strategy
+
+- Prefer native semantics first, then add ARIA for composite widgets.
+- Maintain explicit state attributes (`aria-*`, `data-state`) for testability.
+- Include keyboard/pointer parity for open/close and navigation behavior.
+- Use live regions for async feedback (`Toast`, `LiveRegionProvider`).
+- Ensure `asChild` composition keeps semantics explicit at call sites.
+
+See `docs/accessibility.md` for review checklist details.
+
+## Testing Strategy
+
+- Behavior-level tests live in `test/` (Vitest + JSDOM).
+- Focus on state transitions, keyboard/pointer interactions, and semantic attributes.
+- Avoid snapshot-only confidence; assert behavior and cleanup paths directly.
+
+See `docs/testing.md` for contributor expectations.
+
+## Demo and Baseline Screenshots
+
+- Executable demo app lives in `examples/`.
+- Automated baseline capture script lives in `scripts/capture-examples.mjs`.
+- Baselines are stored in `examples/screenshots/baseline`.
+
+This supports visual sanity checks alongside behavioral tests.

package/docs/components/core/accessible-icon.md

@@ -0,0 +1,23 @@
+# AccessibleIcon
+
+Wraps an icon with a hidden text label.
+
+## Props
+
+- `label`: required accessible text
+- `children`: icon node
+
+## Minimal Example
+
+```tsx
+import { AccessibleIcon } from '@fictjs/ui-primitives'
+
+<AccessibleIcon label="Close dialog">
+  <svg width="16" height="16" aria-hidden="true"><path d="M2 2 L14 14 M14 2 L2 14" /></svg>
+</AccessibleIcon>
+```
+
+## Accessibility Notes
+
+- `label` is required and should describe the icon action, not visual shape.
+- Keep the nested icon decorative (`aria-hidden="true"`) so only one accessible name is announced.

package/docs/components/core/id.md

@@ -0,0 +1,26 @@
+# Id Utilities
+
+`useId` and `IdProvider` provide deterministic id generation for aria wiring and SSR-safe composition.
+
+## API
+
+- `useId(id?: string, prefix?: string): string`
+- `IdProvider` with `prefix?: string`
+
+## Minimal Example
+
+```tsx
+import { IdProvider, useId } from '@fictjs/ui-primitives'
+
+function Field() {
+  const id = useId(undefined, 'profile-field')
+  return <input id={id} aria-describedby={`${id}-hint`} />
+}
+
+<IdProvider prefix="settings">{<Field />}</IdProvider>
+```
+
+## Notes
+
+- Prefer explicit `id` on root primitives when you need hard guarantees for SSR/hydration parity.
+- `IdProvider` helps keep generated ids deterministic within a subtree.

package/docs/components/core/portal.md

@@ -0,0 +1,30 @@
+# Portal / PortalHost
+
+- `Portal` renders subtree into a target container (default `document.body`)
+- `PortalHost` sets a container context for nested portals
+
+## Props
+
+### Portal
+
+- `container`: HTMLElement or accessor
+- `disabled`: render inline when true
+
+### PortalHost
+
+- `container`: HTMLElement or accessor
+
+## Minimal Example
+
+```tsx
+import { Portal } from '@fictjs/ui-primitives'
+
+<Portal>
+  <div role="dialog" aria-modal="true">Portaled content</div>
+</Portal>
+```
+
+## Accessibility Notes
+
+- Portaling changes DOM position, not semantics; always provide explicit role/aria on the content.
+- Ensure focus entry/restore and dismiss behavior are handled by surrounding primitives (e.g. `Dialog`).

package/docs/components/core/presence.md

@@ -0,0 +1,27 @@
+# Presence
+
+`Presence` conditionally mounts children based on `present`, while supporting force mount.
+
+## Props
+
+- `present`: boolean/accessor, default `true`
+- `forceMount`: boolean/accessor, default `false`
+- `children`: node or render function receiving `{ present }`
+
+## Minimal Example
+
+```tsx
+import { createSignal } from '@fictjs/runtime/advanced'
+import { Presence } from '@fictjs/ui-primitives'
+
+const open = createSignal(false)
+
+<Presence present={() => open()}>
+  <div data-state={() => (open() ? 'open' : 'closed')}>Conditional panel</div>
+</Presence>
+```
+
+## Accessibility Notes
+
+- When `present` is false, content is unmounted and removed from the accessibility tree.
+- If using `forceMount`, also expose hidden/closed state (`data-state`, `aria-hidden`, etc.) intentionally.

package/docs/components/core/primitive.md

@@ -0,0 +1,22 @@
+# Primitive
+
+`Primitive` is the polymorphic base element wrapper for all headless components.
+
+## API
+
+- `as`: intrinsic element tag, default `div`
+- `asChild`: when `true`, merges props into the child vnode via `Slot`
+
+## Minimal Example
+
+```tsx
+<Primitive as="button" type="button">Open</Primitive>
+<Primitive asChild>
+  <a href="/docs">Docs</a>
+</Primitive>
+```
+
+## Accessibility Notes
+
+- `as` and `asChild` can change semantics; choose an element with correct native role/keyboard behavior.
+- Avoid replacing native buttons/links with generic tags unless you fully re-implement accessibility semantics.

package/docs/components/core/separator.md

@@ -0,0 +1,25 @@
+# Separator
+
+Semantic separator primitive.
+
+## Props
+
+- `orientation`: `horizontal | vertical`
+- `decorative`: when true, uses presentation semantics
+
+## Minimal Example
+
+```tsx
+import { Separator } from '@fictjs/ui-primitives'
+
+<div>
+  <span>Section A</span>
+  <Separator orientation="horizontal" />
+  <span>Section B</span>
+</div>
+```
+
+## Accessibility Notes
+
+- Use non-decorative separators for meaningful structure so assistive tech can announce boundaries.
+- Set `decorative` for purely visual dividers to avoid extra noise for screen readers.

package/docs/components/core/slot.md

@@ -0,0 +1,25 @@
+# Slot
+
+`Slot` provides `asChild` behavior by cloning a single child vnode and merging props.
+
+Merged behavior:
+
+- event handlers are composed (`child` then `slot`)
+- `class` / `className` values are concatenated
+- `style` objects are shallow-merged
+- refs are composed
+
+## Minimal Example
+
+```tsx
+import { Slot } from '@fictjs/ui-primitives'
+
+<Slot class="button-like" onClick={() => {}}>
+  <a href="/docs">Open docs</a>
+</Slot>
+```
+
+## Accessibility Notes
+
+- The child keeps its native semantics; verify merged props do not conflict with existing keyboard behavior.
+- Keep a single interactive target inside `Slot` to avoid nested-focusable anti-patterns.

package/docs/components/core/visually-hidden.md

@@ -0,0 +1,21 @@
+# VisuallyHidden
+
+Renders accessible text for assistive tech while keeping it visually hidden.
+
+Supports `as` to change element tag.
+
+## Minimal Example
+
+```tsx
+import { VisuallyHidden } from '@fictjs/ui-primitives'
+
+<button type="button">
+  <svg aria-hidden="true" />
+  <VisuallyHidden>Search</VisuallyHidden>
+</button>
+```
+
+## Accessibility Notes
+
+- Use for supplemental text, not large hidden content blocks.
+- Pair with visible affordances so sighted keyboard users still understand the control.

package/docs/components/disclosure/accordion.md

@@ -0,0 +1,33 @@
+# Accordion
+
+Accordion primitives built on collapsible behavior.
+
+## Components
+
+- `AccordionRoot`
+- `AccordionItem`
+- `AccordionTrigger`
+- `AccordionContent`
+
+## Minimal Example
+
+```tsx
+import {
+  AccordionRoot,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from '@fictjs/ui-primitives'
+
+<AccordionRoot type="single" defaultValue="account" collapsible>
+  <AccordionItem value="account">
+    <AccordionTrigger>Account</AccordionTrigger>
+    <AccordionContent>Account details</AccordionContent>
+  </AccordionItem>
+</AccordionRoot>
+```
+
+## Accessibility Notes
+
+- `AccordionTrigger` should remain a button-like control so `aria-expanded` semantics stay valid.
+- Preserve heading hierarchy around triggers/content when embedding in structured pages.

package/docs/components/disclosure/collapsible.md

@@ -0,0 +1,29 @@
+# Collapsible
+
+Expandable/collapsible section primitives.
+
+## Components
+
+- `CollapsibleRoot`
+- `CollapsibleTrigger`
+- `CollapsibleContent`
+
+## Minimal Example
+
+```tsx
+import {
+  CollapsibleRoot,
+  CollapsibleTrigger,
+  CollapsibleContent,
+} from '@fictjs/ui-primitives'
+
+<CollapsibleRoot defaultOpen>
+  <CollapsibleTrigger>Toggle section</CollapsibleTrigger>
+  <CollapsibleContent>Collapsible body</CollapsibleContent>
+</CollapsibleRoot>
+```
+
+## Accessibility Notes
+
+- Trigger state should be exposed via `aria-expanded` (provided by primitive).
+- When using `forceMount`, keep hidden-state signaling consistent (`data-state`, optional `aria-hidden`).