@fictjs/ui-primitives 0.1.0

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

@@ -0,0 +1,62 @@
+# DropdownMenu
+
+Compound dropdown menu built on Popover + roving focus.
+
+## Components
+
+- `DropdownMenuRoot`
+- `DropdownMenuTrigger`
+- `DropdownMenuContent`
+- `DropdownMenuItem`
+- `DropdownMenuCheckboxItem`
+- `DropdownMenuRadioGroup`
+- `DropdownMenuRadioItem`
+- `DropdownMenuSub`
+- `DropdownMenuSubTrigger`
+- `DropdownMenuSubContent`
+- `DropdownMenuLabel`
+- `DropdownMenuSeparator`
+
+## Root API
+
+- `open?: boolean | () => boolean`
+- `defaultOpen?: boolean`
+- `onOpenChange?: (open: boolean) => void`
+
+## Item Semantics
+
+- `DropdownMenuItem` defaults to `role="menuitem"` and closes menu unless `keepOpen`
+- `DropdownMenuCheckboxItem` defaults `keepOpen=true` and exposes `data-checked`
+- `DropdownMenuRadioGroup` + `DropdownMenuRadioItem` provide single-select semantics (`role="menuitemradio"`)
+
+## Content Behavior
+
+- `DropdownMenuContent` renders as `role="menu"` with vertical roving focus
+- Supports `portal?: boolean` through inherited popover content props
+- `DropdownMenuSub*` composes nested menus with side positioning (`right/start` by default)
+
+## Minimal Example
+
+```tsx
+import {
+  DropdownMenuRoot,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+} from '@fictjs/ui-primitives'
+
+<DropdownMenuRoot>
+  <DropdownMenuTrigger>Actions</DropdownMenuTrigger>
+  <DropdownMenuContent side="bottom" align="end">
+    <DropdownMenuItem>Edit</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem>Archive</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenuRoot>
+```
+
+## Accessibility Notes
+
+- Keep menu item roles aligned with behavior (`menuitem`, `menuitemcheckbox`, `menuitemradio`).
+- Use roving focus with visible focus styles so keyboard users can track current item.

package/docs/components/menu/menubar.md

@@ -0,0 +1,38 @@
+# Menubar
+
+Desktop-style menubar primitives with top-level menu activation.
+
+## Components
+
+- `MenubarRoot`
+- `MenubarMenu`
+- `MenubarTrigger`
+- `MenubarContent`
+- `MenubarItem`
+
+## Minimal Example
+
+```tsx
+import {
+  MenubarRoot,
+  MenubarMenu,
+  MenubarTrigger,
+  MenubarContent,
+  MenubarItem,
+} from '@fictjs/ui-primitives'
+
+<MenubarRoot>
+  <MenubarMenu value="file">
+    <MenubarTrigger>File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>New</MenubarItem>
+      <MenubarItem>Open</MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</MenubarRoot>
+```
+
+## Accessibility Notes
+
+- Top-level triggers should remain in a single horizontal tab stop group (`menubar` semantics).
+- Opening one menu should not trap focus permanently; users must escape or choose an item.

package/docs/components/overlay/alert-dialog.md

@@ -0,0 +1,46 @@
+# AlertDialog
+
+Alert dialog wrappers built on top of `Dialog` with modal semantics and `role="alertdialog"` defaults.
+
+## Components
+
+- `AlertDialogRoot`
+- `AlertDialogTrigger`
+- `AlertDialogPortal`
+- `AlertDialogOverlay`
+- `AlertDialogContent`
+- `AlertDialogTitle`
+- `AlertDialogDescription`
+- `AlertDialogAction`
+- `AlertDialogCancel`
+
+## Minimal Example
+
+```tsx
+import {
+  AlertDialogRoot,
+  AlertDialogTrigger,
+  AlertDialogOverlay,
+  AlertDialogContent,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogCancel,
+  AlertDialogAction,
+} from '@fictjs/ui-primitives'
+
+<AlertDialogRoot>
+  <AlertDialogTrigger>Delete</AlertDialogTrigger>
+  <AlertDialogOverlay />
+  <AlertDialogContent>
+    <AlertDialogTitle>Delete item?</AlertDialogTitle>
+    <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
+    <AlertDialogCancel>Cancel</AlertDialogCancel>
+    <AlertDialogAction>Confirm</AlertDialogAction>
+  </AlertDialogContent>
+</AlertDialogRoot>
+```
+
+## Accessibility Notes
+
+- Use concise, high-signal titles/descriptions because `alertdialog` is announced with higher urgency.
+- Keep both cancel and confirm actions keyboard accessible in logical focus order.

package/docs/components/overlay/command-palette.md

@@ -0,0 +1,54 @@
+# CommandPalette
+
+Dialog-based command palette for searchable action lists.
+
+## Components
+
+- `CommandPaletteRoot`
+- `CommandPaletteTrigger`
+- `CommandPaletteContent`
+- `CommandPaletteInput`
+- `CommandPaletteList`
+- `CommandPaletteItem`
+- `CommandPaletteEmpty`
+- `CommandPaletteGroup`
+- `CommandPaletteSeparator`
+- `CommandPaletteClose`
+
+## Key APIs
+
+- `CommandPaletteRoot`: controlled/uncontrolled `open`, `value`, and `query` state
+- `CommandPaletteInput`: drives filtering query and supports keyboard entry into list
+- `CommandPaletteItem`: supports `as/asChild`, `keywords`, `keepOpen`, and selection callbacks
+- `CommandPaletteEmpty`: renders only when no items match current query
+
+## Minimal Example
+
+```tsx
+import {
+  CommandPaletteRoot,
+  CommandPaletteTrigger,
+  CommandPaletteContent,
+  CommandPaletteInput,
+  CommandPaletteList,
+  CommandPaletteItem,
+  CommandPaletteEmpty,
+} from '@fictjs/ui-primitives'
+
+<CommandPaletteRoot>
+  <CommandPaletteTrigger>Open Command Menu</CommandPaletteTrigger>
+  <CommandPaletteContent>
+    <CommandPaletteInput placeholder="Type a command" />
+    <CommandPaletteList>
+      <CommandPaletteItem value="profile">Profile</CommandPaletteItem>
+      <CommandPaletteItem value="settings">Settings</CommandPaletteItem>
+      <CommandPaletteEmpty>No results</CommandPaletteEmpty>
+    </CommandPaletteList>
+  </CommandPaletteContent>
+</CommandPaletteRoot>
+```
+
+## Accessibility Notes
+
+- Built on dialog semantics, so focus and dismissal behavior follows overlay contracts.
+- Keep command labels concise and unique for predictable keyboard filtering.

package/docs/components/overlay/dialog.md

@@ -0,0 +1,69 @@
+# Dialog
+
+Compound modal/non-modal dialog primitives.
+
+## Components
+
+- `DialogRoot`
+- `DialogTrigger`
+- `DialogPortal`
+- `DialogOverlay`
+- `DialogContent`
+- `DialogTitle`
+- `DialogDescription`
+- `DialogClose`
+
+Supports controlled/uncontrolled state via `open/defaultOpen/onOpenChange`.
+
+## Root API
+
+- `DialogRoot`
+- `id?: string` optional deterministic base id for content/title/description wiring
+- `open?: boolean | () => boolean` controlled state
+- `defaultOpen?: boolean` uncontrolled initial state
+- `onOpenChange?: (open: boolean) => void`
+- `modal?: boolean` default `true`
+
+## Composition API
+
+- `DialogTrigger` / `DialogClose` support `asChild`
+- `DialogContent` supports `onEscapeKeyDown`, `onPointerDownOutside`, `onFocusOutside`, `onInteractOutside`
+- Outside handlers are interceptable: calling `event.preventDefault()` blocks dismissal
+
+## Content Behavior
+
+- `DialogContent` defaults to `role="dialog"`
+- `forceMount` keeps content mounted while closed (state reflects via `data-state`)
+- `portal?: boolean` defaults to `true`; set `false` for inline rendering/testing
+- Escape and outside interactions are handled via `DismissableLayer`
+- Modal mode enables `ScrollLock` + focus trap semantics
+
+## Accessibility Contract
+
+- Trigger exposes `aria-haspopup="dialog"` and `aria-controls`
+- Content wires `aria-labelledby` and `aria-describedby` to `DialogTitle` / `DialogDescription`
+- `DialogClose` emits close semantics through `onOpenChange`
+
+## Minimal Example
+
+```tsx
+import {
+  DialogRoot,
+  DialogTrigger,
+  DialogOverlay,
+  DialogContent,
+  DialogTitle,
+  DialogDescription,
+  DialogClose,
+} from '@fictjs/ui-primitives'
+
+<DialogRoot>
+  <DialogTrigger>Open settings</DialogTrigger>
+  <DialogOverlay />
+  <DialogContent>
+    <DialogTitle>Settings</DialogTitle>
+    <DialogDescription>Update your preferences.</DialogDescription>
+    <DialogClose>Done</DialogClose>
+  </DialogContent>
+</DialogRoot>
+```

package/docs/components/overlay/hover-card.md

@@ -0,0 +1,25 @@
+# HoverCard
+
+Interactive hover content with separate open/close delays.
+
+## Components
+
+- `HoverCardRoot`
+- `HoverCardTrigger`
+- `HoverCardContent`
+
+## Minimal Example
+
+```tsx
+import { HoverCardRoot, HoverCardTrigger, HoverCardContent } from '@fictjs/ui-primitives'
+
+<HoverCardRoot openDelay={100} closeDelay={150}>
+  <HoverCardTrigger>@fictjs</HoverCardTrigger>
+  <HoverCardContent side="bottom">Project profile preview</HoverCardContent>
+</HoverCardRoot>
+```
+
+## Accessibility Notes
+
+- Hover-only disclosure is insufficient; this primitive also opens on focus for keyboard users.
+- Keep hover card content supplemental and non-blocking for primary task flow.

package/docs/components/overlay/popover.md

@@ -0,0 +1,36 @@
+# Popover
+
+Floating, dismissable content anchored to a trigger.
+
+## Components
+
+- `PopoverRoot`
+- `PopoverTrigger`
+- `PopoverContent`
+- `PopoverClose`
+
+## Key APIs
+
+- `PopoverRoot` accepts `id?: string` for deterministic trigger/content aria wiring
+- `PopoverTrigger` and `PopoverClose` support `asChild`
+- `PopoverContent` supports `onEscapeKeyDown`, `onPointerDownOutside`, `onFocusOutside`, `onInteractOutside`
+- Outside handlers are interceptable: calling `event.preventDefault()` blocks dismissal
+
+## Minimal Example
+
+```tsx
+import { PopoverRoot, PopoverTrigger, PopoverContent, PopoverClose } from '@fictjs/ui-primitives'
+
+<PopoverRoot>
+  <PopoverTrigger>Open filters</PopoverTrigger>
+  <PopoverContent side="bottom" align="start">
+    Filter options
+    <PopoverClose>Close</PopoverClose>
+  </PopoverContent>
+</PopoverRoot>
+```
+
+## Accessibility Notes
+
+- Popover content should expose an appropriate role (`dialog` by default in this implementation).
+- Provide a deterministic close action in addition to outside dismissal.

package/docs/components/overlay/tooltip.md

@@ -0,0 +1,28 @@
+# Tooltip
+
+Hover/focus tooltip primitives with open delay.
+
+## Components
+
+- `TooltipProvider`
+- `TooltipRoot`
+- `TooltipTrigger`
+- `TooltipContent`
+
+## Minimal Example
+
+```tsx
+import { TooltipProvider, TooltipRoot, TooltipTrigger, TooltipContent } from '@fictjs/ui-primitives'
+
+<TooltipProvider delayDuration={200}>
+  <TooltipRoot>
+    <TooltipTrigger>Hover me</TooltipTrigger>
+    <TooltipContent side="top">Helpful hint</TooltipContent>
+  </TooltipRoot>
+</TooltipProvider>
+```
+
+## Accessibility Notes
+
+- Tooltip text should supplement, not replace, the control's accessible name.
+- Keep tooltip content short and avoid interactive controls inside tooltip surfaces.

package/docs/examples.md

@@ -0,0 +1,155 @@
+# Usage Examples
+
+Examples below use TSX syntax with `@fictjs/ui-primitives`.
+
+For a runnable end-to-end demo, see `examples/README.md`.
+
+## Dialog (controlled)
+
+```tsx
+import { createSignal } from '@fictjs/runtime/advanced'
+import {
+  DialogRoot,
+  DialogTrigger,
+  DialogOverlay,
+  DialogContent,
+  DialogTitle,
+  DialogDescription,
+  DialogClose,
+} from '@fictjs/ui-primitives'
+
+const open = createSignal(false)
+
+<DialogRoot open={() => open()} onOpenChange={next => open(next)}>
+  <DialogTrigger>Edit profile</DialogTrigger>
+  <DialogOverlay class="overlay" />
+  <DialogContent>
+    <DialogTitle>Profile</DialogTitle>
+    <DialogDescription>Update your display settings.</DialogDescription>
+    <DialogClose>Done</DialogClose>
+  </DialogContent>
+</DialogRoot>
+```
+
+## Dropdown Menu (checkbox + radio)
+
+```tsx
+import {
+  DropdownMenuRoot,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+} from '@fictjs/ui-primitives'
+
+<DropdownMenuRoot>
+  <DropdownMenuTrigger>Preferences</DropdownMenuTrigger>
+  <DropdownMenuContent side="bottom" align="start">
+    <DropdownMenuCheckboxItem defaultChecked>Show line numbers</DropdownMenuCheckboxItem>
+    <DropdownMenuRadioGroup defaultValue="compact">
+      <DropdownMenuRadioItem value="compact">Compact</DropdownMenuRadioItem>
+      <DropdownMenuRadioItem value="comfortable">Comfortable</DropdownMenuRadioItem>
+    </DropdownMenuRadioGroup>
+  </DropdownMenuContent>
+</DropdownMenuRoot>
+```
+
+## Toast (hook + viewport)
+
+```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 were persisted.' })}
+    >
+      Save
+    </button>
+  )
+}
+
+<ToastProvider duration={4000}>
+  <SaveButton />
+  <ToastViewport />
+</ToastProvider>
+```
+
+## Tabs (controlled)
+
+```tsx
+import { createSignal } from '@fictjs/runtime/advanced'
+import { TabsRoot, TabsList, TabsTrigger, TabsContent } from '@fictjs/ui-primitives'
+
+const tab = createSignal('account')
+
+<TabsRoot value={() => tab()} onValueChange={next => tab(next)}>
+  <TabsList>
+    <TabsTrigger value="account">Account</TabsTrigger>
+    <TabsTrigger value="security">Security</TabsTrigger>
+  </TabsList>
+  <TabsContent value="account">Account settings</TabsContent>
+  <TabsContent value="security" forceMount>
+    Security settings
+  </TabsContent>
+</TabsRoot>
+```
+
+## Form Field (label + message wiring)
+
+```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>
+```
+
+## Select + Combobox
+
+```tsx
+import {
+  SelectRoot,
+  SelectTrigger,
+  SelectValue,
+  SelectContent,
+  SelectItem,
+  ComboboxRoot,
+  ComboboxInput,
+  ComboboxList,
+  ComboboxItem,
+} from '@fictjs/ui-primitives'
+
+<SelectRoot defaultValue="apple">
+  <SelectTrigger>
+    <SelectValue placeholder="Choose fruit" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="apple">Apple</SelectItem>
+    <SelectItem value="orange">Orange</SelectItem>
+  </SelectContent>
+</SelectRoot>
+
+<ComboboxRoot>
+  <ComboboxInput placeholder="Search assignee" />
+  <ComboboxList>
+    <ComboboxItem value="alice">Alice</ComboboxItem>
+    <ComboboxItem value="bob">Bob</ComboboxItem>
+  </ComboboxList>
+</ComboboxRoot>
+```

package/docs/release.md

@@ -0,0 +1,60 @@
+# Release Checklist
+
+Use this checklist for publishing `@fictjs/ui-primitives`.
+
+## 1. Pre-release validation
+
+Run all quality gates:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm examples:build
+```
+
+If visual or interaction behavior changed:
+
+```bash
+pnpm examples:screenshots
+```
+
+## 2. Documentation validation
+
+Confirm docs are updated for behavior/API changes:
+
+- `README.md`
+- `docs/components/*`
+- `docs/api-reference.md` (if exports changed)
+- `docs/testing.md` / `docs/accessibility.md` where relevant
+- `examples/README.md` if demo workflow changed
+
+## 3. Versioning
+
+Bump version in `package.json` using your preferred release process.
+
+Example (patch):
+
+```bash
+pnpm version patch
+```
+
+## 4. Publish
+
+Publish from a clean git state.
+
+```bash
+pnpm publish --access public --provenance --no-git-checks
+```
+
+Notes:
+
+- Package already includes `publishConfig.access=public` and `provenance=true`.
+- Remove `--no-git-checks` if your release environment enforces clean checks automatically.
+
+## 5. Post-publish
+
+- Verify package on npm registry
+- Verify install in a clean consumer app
+- Tag release in git and attach release notes

package/docs/testing.md

@@ -0,0 +1,36 @@
+# Testing Notes
+
+This package uses Vitest + JSDOM and focuses on behavior-level tests instead of snapshot-only assertions.
+
+## Current coverage focus
+
+- Controlled vs uncontrolled state for core compound components
+- Open/close semantics for overlay/menu/disclosure primitives
+- Accessibility state attributes (`aria-*`, `role`, `data-state`)
+- Keyboard and pointer dismissal boundaries
+- Queue and timeout lifecycle for Toast
+
+## Run locally
+
+```bash
+pnpm test
+pnpm test:coverage
+```
+
+For demo-level visual checks:
+
+```bash
+pnpm examples:build
+pnpm examples:screenshots
+```
+
+See also:
+
+- `docs/accessibility.md` for manual a11y verification contracts
+- `docs/examples.md` for copyable composition patterns
+
+## When adding components
+
+1. Add at least one uncontrolled test and one controlled test.
+2. Add one accessibility-semantic assertion (`role`, `aria-*`, or keyboard behavior).
+3. Add one cleanup/dispose or close-path assertion.