@moldable-ai/ui 0.2.26 → 0.2.31

package/src/components/ui/inspector.md

@@ -1,11 +1,51 @@
 # Inspector
 
-Secondary property controls for the current selection.
+## Purpose
 
-Compose `Inspector`, `InspectorHeader`, `InspectorContent`,
-`InspectorSection`, and aligned `InspectorRow` pairs. Controls should usually
-use compact sizes.
+The inspector primitives compose a secondary property pane for the current
+selection. The root is an `aside`; its header stays fixed while
+`InspectorContent` scrolls and includes bottom chat clearance.
 
-The inspector must remain subordinate to the primary pane. Collapse it when
-width is constrained, group related properties, and avoid placing primary
-workflow actions inside it.
+## Usage
+
+```tsx
+import {
+  Input,
+  Inspector,
+  InspectorContent,
+  InspectorHeader,
+  InspectorLabel,
+  InspectorRow,
+  InspectorSection,
+  InspectorValue,
+} from '@moldable-ai/ui'
+
+;<Inspector>
+  <InspectorHeader>Inspector</InspectorHeader>
+  <InspectorContent>
+    <InspectorSection title="Appearance">
+      <InspectorRow>
+        <InspectorLabel htmlFor="document-title">Title</InspectorLabel>
+        <InspectorValue>
+          <Input id="document-title" controlSize="small" />
+        </InspectorValue>
+      </InspectorRow>
+    </InspectorSection>
+  </InspectorContent>
+</Inspector>
+```
+
+`InspectorSection` accepts optional `title` and `actions`; it omits its header
+when neither is present. `InspectorRow` aligns a label and value in two
+columns. `InspectorLabel` renders a compact native label, and
+`InspectorValue` contains the control or read-only value.
+
+## Quality bar
+
+- Keep the inspector subordinate to the primary pane and collapse it when
+  width is constrained.
+- Group related properties into short sections and use section actions only
+  for local operations.
+- Connect each `InspectorLabel` to its control with `htmlFor` and `id`.
+- Use compact control sizes and keep unpredictable values truncatable.
+- Keep primary workflow actions out of the inspector.

package/src/components/ui/item.md

@@ -23,7 +23,7 @@ import {
 } from '@moldable-ai/ui'
 
 ;<ItemGroup>
-  <Item size="sm">
+  <Item role="listitem" size="sm">
     <ItemMedia variant="icon">
       <FileText />
     </ItemMedia>
@@ -53,8 +53,10 @@ Use `asChild` when the whole item is a link or another interactive primitive. Av
 
 ## API summary
 
-- `ItemGroup`: `role="list"` container.
-- `Item`: `variant="default"`, `"outline"`, or `"muted"`; `size="default"` or `"sm"`; optional `asChild`.
+- `ItemGroup`: `role="list"` container. Give each direct `Item`
+  `role="listitem"`.
+- `Item`: `variant="default"`, `"outline"`, or `"muted"`;
+  `size="default"` or `"sm"`; optional `asChild`.
 - `ItemMedia`: `variant="default"`, `"icon"`, or `"image"`.
 - `ItemContent`: flexible title/description column.
 - `ItemTitle`, `ItemDescription`: primary and secondary text.

package/src/components/ui/kbd.md

@@ -0,0 +1,30 @@
+# Kbd
+
+## Purpose
+
+`Kbd` displays a keyboard key or shortcut hint. `KbdGroup` lays out several
+keys as one shortcut. These components are visual labels only; they do not
+register keyboard handlers.
+
+## Usage
+
+```tsx
+import { Kbd, KbdGroup } from '@moldable-ai/ui'
+
+;<KbdGroup aria-label="Command K">
+  <Kbd>⌘</Kbd>
+  <Kbd>K</Kbd>
+</KbdGroup>
+```
+
+Both components accept native `<kbd>` props and `className`. `Kbd` applies the
+keycap treatment and sizes unclassified SVG children; `KbdGroup` supplies only
+an inline flex layout.
+
+## Guidance
+
+- Show shortcuts only when the command really supports them.
+- Keep key names brief and use the same notation throughout the app.
+- Add an accessible label when modifier glyphs may not be announced clearly.
+- Keep `Kbd` non-interactive; place click behavior on a real button or link.
+- Do not use shortcut hints as the only way to discover an action.

package/src/components/ui/label.md

@@ -0,0 +1,29 @@
+# Label
+
+## Purpose
+
+`Label` gives a form control a visible, clickable name. It wraps the Radix
+label primitive and accepts its props.
+
+## Usage
+
+```tsx
+import { Input, Label } from '@moldable-ai/ui'
+
+;<div className="space-y-2">
+  <Label htmlFor="project-name">Project name</Label>
+  <Input id="project-name" name="projectName" />
+</div>
+```
+
+## Guidance
+
+- Pair `htmlFor` with a unique control `id`, or nest the control when that is
+  the clearer native relationship.
+- Use a short noun phrase and keep instructions or validation outside the
+  label.
+- Keep a visible label for text fields; a placeholder is not a replacement.
+- Mark optional or required state consistently and expose it to assistive
+  technology on the control.
+- The built-in styles respond to disabled peer or group state; set the actual
+  control's `disabled` attribute as well.

package/src/components/ui/list.md

@@ -81,8 +81,8 @@ const [selected, setSelected] = useState<ReadonlySet<string>>(
 
 - Arrow Up/Down moves through a vertical list; Arrow Left/Right moves through a horizontal list.
 - Home and End move to the first and last available item.
-- Space changes selection.
-- Enter changes selection and invokes `onAction`.
+- Space changes selection when selection is enabled.
+- Enter changes selection when enabled and invokes `onAction`.
 - A single pointer click changes selection. A double click invokes `onAction`.
 - Disabled items are skipped during keyboard navigation and cannot be selected or activated.
 - Interactive descendants such as buttons and links keep their own pointer behavior. They do not select or activate the containing item.

package/src/components/ui/material.md

@@ -1,13 +1,14 @@
 # Material
 
-Adaptive material for navigation and control chrome.
+`Material` provides an adaptive sampled layer for navigation and control
+chrome. `MaterialGroup` gives a related control cluster one shared layer.
 
 ```tsx
-<Material asChild variant="regular" elevation="none">
+<Material asChild variant="medium" elevation="none">
   <Toolbar>{/* context and actions */}</Toolbar>
 </Material>
 
-<MaterialGroup variant="regular" shape="capsule" spacing="compact">
+<MaterialGroup variant="thin" shape="capsule" spacing="compact">
   <IconButton label="Previous" variant="ghost">
     <ChevronLeft />
   </IconButton>
@@ -19,15 +20,25 @@ Adaptive material for navigation and control chrome.
 
 ## Variants
 
-- `regular` provides a frosted, legible control or navigation layer.
-- `clear` is less frosted and is only for compact controls floating over
-  photos, maps, video, or another richly colored canvas.
+- Standard thicknesses are `ultra-thick`, `thick`, `medium`, `thin`, and
+  `ultra-thin`, ordered from most filled to most transparent. They all use the
+  standard material blur; thickness controls translucency.
+- `regular` is a compatibility alias for `medium` and remains the default.
+- `clear` is a compatibility alias for `ultra-thin`.
 
-Both variants start with an opaque fallback. Backdrop sampling is enabled only
-when the renderer supports it. Reduced transparency and forced colors keep the
-fallback opaque.
+Every variant starts with an opaque fallback. Backdrop sampling is enabled only
+when the renderer supports it.
 
-## Grouping
+## Shape, elevation, and grouping
+
+- `shape` is `rounded`, `capsule`, or `circle`; it defaults to `rounded`.
+- `elevation` is `none`, `panel`, or `overlay`; it defaults to `none` and
+  controls shadow independently of thickness.
+- `interactive` adds hover and press feedback when the material surface itself
+  is the control.
+- `asChild` applies `Material` to its single child through a Radix slot.
+- `MaterialGroup` supports `spacing="compact" | "default" | "comfortable"`
+  and defaults to `default`.
 
 `MaterialGroup` creates one sampled layer for a related cluster. Put ordinary
 ghost or transparent controls inside it. Do not wrap each child in another
@@ -42,8 +53,10 @@ do not read as one group.
   temporary control layers.
 - Keep documents, calendars, tables, forms, cards, sheets, and primary content
   canvases opaque.
-- Prefer `regular`. A `clear` surface needs stable contrast across every part
-  of the media behind it.
+- Prefer a named standard thickness when the hierarchy is known. Use the
+  compatibility aliases only where their existing semantics are intentional.
+- Thin and ultra-thin surfaces need stable contrast across every part of the
+  content behind them.
 - Use `interactive` only when the material surface itself is the control.
 - Do not animate blur or saturation. Shared motion tokens provide restrained
   press feedback and remove it when reduced motion is requested.

package/src/components/ui/menu-items.md

@@ -0,0 +1,60 @@
+# Menu Items
+
+## Purpose
+
+`menu-items.tsx` is the internal adapter shared by `DropdownMenu` and
+`ContextMenu` when their declarative `items` API is used. It coordinates the
+host-native request and portable fallback, formats shortcut labels, renders
+portable row contents, and removes conflicting authored content.
+
+App code should use `DropdownMenu` or `ContextMenu`, not import these helpers
+directly.
+
+## Declarative usage
+
+```tsx
+import { Button, DropdownMenu, DropdownMenuTrigger } from '@moldable-ai/ui'
+
+;<DropdownMenu
+  items={[
+    {
+      id: 'rename',
+      label: 'Rename',
+      shortcut: { key: 'r', modifiers: ['cmd'] },
+    },
+    { id: 'divider', kind: 'separator' },
+    { id: 'delete', label: 'Move to trash', destructive: true },
+  ]}
+  onSelectItem={(id) => runCommand(id)}
+>
+  <DropdownMenuTrigger asChild>
+    <Button
+      type="button"
+      variant="outline"
+      size="sm"
+      className="cursor-pointer"
+    >
+      Actions
+    </Button>
+  </DropdownMenuTrigger>
+</DropdownMenu>
+```
+
+## Internal contract
+
+- `useDeclarativeMenuState` supports controlled or uncontrolled portable-open
+  state. While a native request is active, `nativeOpen` is true and
+  `portableOpen` is forced false.
+- A completed native request passes `selectedId` to `onSelectItem`.
+  Cancellation does nothing. A fallback result or request failure opens the
+  portable menu unless the caller supplies its own `onFallback`.
+- `formatMenuShortcut` renders modifiers in array order as `⌘`, `⇧`, `⌥`, and
+  `⌃`, then uppercases a one-character key. It is display metadata only.
+- `MenuItemContents` renders an optional Lucide icon, the label, and a `Kbd`
+  shortcut. Separators are handled by the owning menu.
+- Content detection and removal recurse through fragments. When declarative
+  items and authored content are both provided, the owning menu reports the
+  conflict in development and declarative items win.
+
+Keep item IDs stable and labels concise. Do not execute a command from shortcut
+metadata, and do not mix declarative items with authored menu content.

package/src/components/ui/menubar.md

@@ -0,0 +1,58 @@
+# Menubar
+
+## Purpose
+
+`Menubar` presents a persistent row of related command menus, such as File,
+Edit, and View. Use it for command families that benefit from repeated
+keyboard access; use `DropdownMenu` for a single contextual action menu.
+
+## Usage
+
+```tsx
+import {
+  Menubar,
+  MenubarContent,
+  MenubarItem,
+  MenubarMenu,
+  MenubarShortcut,
+  MenubarTrigger,
+} from '@moldable-ai/ui'
+
+;<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger className="cursor-pointer">File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem onSelect={createDocument}>
+        New document
+        <MenubarShortcut>⌘N</MenubarShortcut>
+      </MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>
+```
+
+## API summary
+
+- `Menubar`, `MenubarMenu`, and `MenubarTrigger` form the required shell.
+- `MenubarContent` is portalled and defaults to `align="start"`,
+  `alignOffset={-4}`, and `sideOffset={8}`.
+- `MenubarItem` supports `inset` and
+  `variant="default" | "destructive"`.
+- Checkbox items, radio groups/items, groups, labels, separators, shortcuts,
+  and submenus are exported for structured command sets.
+- `MenubarLabel` and `MenubarSubTrigger` support `inset`.
+- Components otherwise accept the corresponding Radix menubar props.
+
+## Guidance
+
+- Keep top-level trigger labels short and conventional.
+- Use checkbox and radio items for menu-owned state, and `onSelect` for
+  commands.
+- Put destructive commands last or in a separated group; do not rely on color
+  alone to communicate risk.
+- `MenubarShortcut` is display text only and does not register a handler.
+- Radix supplies menu roles, focus movement, typeahead, Escape dismissal, and
+  submenu navigation. Preserve those semantics and give icon-only content an
+  accessible name.
+- Keep submenus shallow and use `Popover` or `Dialog` for arbitrary form
+  controls.

package/src/components/ui/message-scroller-primitive.md

@@ -0,0 +1,70 @@
+# Message Scroller Primitive
+
+## Purpose
+
+`message-scroller-primitive.tsx` is the unstyled React wiring for the
+in-repository transcript controller and scroll-ownership policy. The public
+`MessageScroller*` components wrap this module with layout, button, and
+animation styles; app code should use those wrappers.
+
+## Anatomy
+
+```tsx
+<MessageScroller.Provider autoScroll>
+  <MessageScroller.Root>
+    <MessageScroller.Viewport>
+      <MessageScroller.Content>
+        <MessageScroller.Item messageId="turn-1" scrollAnchor>
+          {/* message */}
+        </MessageScroller.Item>
+      </MessageScroller.Content>
+    </MessageScroller.Viewport>
+    <MessageScroller.Button direction="end" />
+  </MessageScroller.Root>
+</MessageScroller.Provider>
+```
+
+This local-only example uses the `MessageScroller` object exported by the
+primitive module. `Provider` must wrap every root, item, button, and hook.
+
+## Primitive contract
+
+- Provider defaults: `autoScroll={false}`, `defaultScrollPosition="end"`,
+  `scrollEdgeThreshold={8}`, `scrollPreviousItemPeek={64}`, and
+  `scrollMargin={0}`. Changing `defaultScrollPosition` resets the one-time
+  initial-position decision for the next content mutation.
+- `Viewport` forwards scroll, wheel, touch, and scroll-key events after
+  notifying the controller. It defaults to a focusable messages region and
+  observes viewport size changes.
+- `Content` defaults to an additions-only live log, observes direct child
+  mutations and size changes, and appends a hidden internal spacer.
+- `Item` registers `messageId` elements and writes anchor data used for
+  initial placement, new-turn anchoring, targeted scrolling, and visibility.
+- `Button` supports `direction="start" | "end"`, `behavior`, and a `render`
+  element or render function. Defaults are end, smooth, and `type="button"`.
+  Inactive buttons are inert with `tabIndex={-1}`; preventing the click event's
+  default also prevents the scroll command.
+
+## Controller and policy behavior
+
+The controller is the sole owner of programmatic transcript movement. The
+policy distinguishes following the end, free reading, an anchored turn, and a
+settling commanded jump. Wheel, touch, scroll-key, scrollbar, or other motion
+away from a declared target gives control to the reader immediately.
+
+It also:
+
+- keeps a followed end pinned during growth;
+- reanchors a streaming turn after resize;
+- preserves the first visible row when older items are prepended;
+- restores a stable visible leaf when content above collapses;
+- grows the internal spacer so late items can reach the requested alignment;
+- exposes edge state as `data-scrollable` and active programmatic movement as
+  `data-autoscrolling` on root and viewport;
+- observes visibility only while `useMessageScrollerVisibility` has
+  subscribers.
+
+For finer reading-position stability inside a complex item, mark stable
+descendants with `data-message-scroll-anchor`. Do not manipulate the
+controller, spacer, data attributes, or scroll position from a competing
+effect; extend the wrapper API when new behavior is required.

package/src/components/ui/message-scroller.md

@@ -0,0 +1,86 @@
+# Message Scroller
+
+## Purpose
+
+`MessageScroller` is the styled, public transcript scroller. It keeps streamed
+content stable, preserves the reader's position when history is prepended or
+content above changes size, supports turn anchors, and exposes jump and
+visibility state.
+
+## Usage
+
+```tsx
+import {
+  MessageScroller,
+  MessageScrollerButton,
+  MessageScrollerContent,
+  MessageScrollerItem,
+  MessageScrollerProvider,
+  MessageScrollerViewport,
+} from '@moldable-ai/ui'
+
+;<MessageScrollerProvider autoScroll defaultScrollPosition="end">
+  <MessageScroller>
+    <MessageScrollerViewport>
+      <MessageScrollerContent className="gap-3 p-3">
+        {messages.map((message) => (
+          <MessageScrollerItem
+            key={message.id}
+            messageId={message.id}
+            scrollAnchor={message.role === 'user'}
+          >
+            {renderMessage(message)}
+          </MessageScrollerItem>
+        ))}
+      </MessageScrollerContent>
+    </MessageScrollerViewport>
+    <MessageScrollerButton />
+  </MessageScroller>
+</MessageScrollerProvider>
+```
+
+## API summary
+
+- `MessageScrollerProvider` is required. Defaults are `autoScroll={false}`,
+  `defaultScrollPosition="end"`, `scrollEdgeThreshold={8}`,
+  `scrollPreviousItemPeek={64}`, and `scrollMargin={0}`.
+- Initial position can be `start`, `end`, or `last-anchor`. The last option
+  anchors the newest marked turn only when enough transcript follows it;
+  otherwise it lands at the end.
+- `MessageScrollerViewport` is a focusable `role="region"` labelled
+  “Messages” by default. `preserveScrollOnPrepend` defaults to true.
+- `MessageScrollerContent` defaults to `role="log"` and
+  `aria-relevant="additions"`. It accepts `spacerClassName` for the internal
+  positioning spacer.
+- `MessageScrollerItem` accepts `messageId` and `scrollAnchor` (false by
+  default). IDs enable targeted scrolling and visibility reporting; mark the
+  start of each new turn as an anchor.
+- `MessageScrollerButton` defaults to an end jump with smooth behavior,
+  `variant="secondary"`, and `size="icon-sm"`. It becomes inert and leaves
+  the tab order when that edge is not scrollable. `direction="start"` creates
+  the corresponding top jump.
+
+## Hooks and behavior
+
+- `useMessageScroller()` returns `scrollToStart`, `scrollToEnd`, and
+  `scrollToMessage`. Targeted scrolls accept `align`, `behavior`, and
+  `scrollMargin`; alignment defaults to `start` and behavior to `auto`.
+- `useMessageScrollerScrollable()` returns `{ start, end }`.
+- `useMessageScrollerVisibility()` returns `currentAnchorId` and ordered
+  `visibleMessageIds`.
+- Hooks must be descendants of the provider.
+- Reader input takes ownership immediately. With `autoScroll`, content follows
+  the end only while follow mode is active; a newly appended turn anchor is
+  held near the top with the configured previous-item peek.
+
+## Guidance
+
+- Give every navigable item a stable `messageId`; do not use an array index.
+- Mark only meaningful turn starts as `scrollAnchor`.
+- Keep one viewport as the owning vertical scroll region and give its flex
+  ancestors `min-h-0`.
+- Preserve the default region label or supply a more specific `aria-label`.
+- Keep the content's log semantics and busy state accurate while streaming or
+  loading history.
+- Do not add a second effect that writes `scrollTop`; all movement must go
+  through the scroller API so it cannot fight the reader.

package/src/components/ui/navigation-button-group.md

@@ -17,9 +17,10 @@ consistent compact treatment.
 - `canGoBack` and `canGoForward` disable unavailable directions.
 - `onBack` and `onForward` perform caller-owned navigation.
 - `backLabel` and `forwardLabel` customize accessible names.
-- `size` accepts the `IconButton` size scale.
-- `variant` is `ghost` or `outline`.
-- Native `ButtonGroup` props apply to the group.
+- `size` accepts the `IconButton` size scale and defaults to `sm`.
+- `variant` is `ghost` or `outline` and defaults to `ghost`.
+- Remaining `ButtonGroup` props apply to the root except `children` and
+  `orientation`; the component owns two buttons in a horizontal group.
 
 ## Keyboard and accessibility
 

package/src/components/ui/navigation-menu.md

@@ -0,0 +1,52 @@
+# Navigation Menu
+
+`NavigationMenu` presents a compact row of destinations, with optional
+disclosure panels for grouped links. Use it for navigation, not for commands
+or form actions.
+
+```tsx
+import {
+  NavigationMenu,
+  NavigationMenuContent,
+  NavigationMenuItem,
+  NavigationMenuLink,
+  NavigationMenuList,
+  NavigationMenuTrigger,
+} from '@moldable-ai/ui'
+
+;<NavigationMenu viewport={false}>
+  <NavigationMenuList>
+    <NavigationMenuItem>
+      <NavigationMenuTrigger>Projects</NavigationMenuTrigger>
+      <NavigationMenuContent>
+        <NavigationMenuLink href="/projects/recent" active>
+          Recent
+        </NavigationMenuLink>
+        <NavigationMenuLink href="/projects/shared">Shared</NavigationMenuLink>
+      </NavigationMenuContent>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenu>
+```
+
+## API
+
+- `NavigationMenu` exposes the Radix root props plus `viewport`. The shared
+  viewport is rendered by default; set `viewport={false}` for a panel attached
+  to each item.
+- `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`,
+  `NavigationMenuContent`, `NavigationMenuLink`, and
+  `NavigationMenuIndicator` expose their corresponding Radix props.
+- `NavigationMenuLink` accepts `active` for the current destination.
+- `NavigationMenuViewport` and `navigationMenuTriggerStyle` are exported for
+  custom composition.
+
+## Quality and accessibility
+
+- Use real destinations and preserve link semantics with `href`.
+- Give every trigger and icon-only link an accessible name.
+- Mark only the current destination active.
+- Keep labels short and disclosure panels easy to scan.
+- Preserve the keyboard and focus behavior supplied by Radix; do not make
+  essential destinations available only on pointer hover.
+- Use `Menubar`, `DropdownMenu`, or ordinary buttons for actions.

package/src/components/ui/number-input.md

@@ -17,3 +17,11 @@ Use in inspectors and settings where the numeric value matters. Use `Slider`
 when relative adjustment matters more than exact entry. Always supply a visible
 label or `aria-label`. Treat `null` as empty input and validate domain-specific
 constraints outside the component.
+
+`value`/`onValueChange` provide controlled state; `defaultValue` provides
+uncontrolled initial state. `variant` is `default` or `filled`, and `size` is
+`sm`, `default`, or `lg`. Both default to `default`. Steppers are shown by
+default; set `steppers={false}` to hide them. They use a finite numeric `step`
+(falling back to `1`), start an empty value from zero, and clamp their result
+to finite `min`/`max` values. Typed input still relies on native numeric
+validity and caller validation.

package/src/components/ui/pagination.md

@@ -0,0 +1,51 @@
+# Pagination
+
+`Pagination` links between pages in a bounded result set.
+
+```tsx
+import {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from '@moldable-ai/ui'
+
+;<Pagination>
+  <PaginationContent>
+    <PaginationItem>
+      <PaginationPrevious href="?page=1" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="?page=2" isActive>
+        2
+      </PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="?page=3" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
+## API
+
+- `Pagination` renders a centered `nav` named “pagination”.
+- `PaginationContent` and `PaginationItem` render the list structure.
+- `PaginationLink` renders an anchor. `isActive` applies the outlined state
+  and `aria-current="page"`; `size` uses the shared button size scale.
+- `PaginationPrevious` and `PaginationNext` provide responsive text and
+  accessible labels.
+- `PaginationEllipsis` is a decorative gap marker, not a link.
+
+## Quality and accessibility
+
+- Supply a real `href` for every available page and keep the current location
+  marked with `isActive`.
+- Keep page order stable and show enough neighboring pages to retain context.
+- At a range boundary, omit the unavailable link or implement
+  `aria-disabled`, remove it from Tab order, and prevent navigation; anchors
+  do not support the native `disabled` attribute.
+- Do not use pagination for infinite loading or a small list that fits in one
+  view.

package/src/components/ui/panel.md

@@ -9,3 +9,9 @@ bounded content groups inside a pane.
 
 The group and its containing shell need a definite height. Long content belongs
 in `PanelContent`, and chat-safe padding belongs on that scrolling region.
+
+`PanelGroup` defaults to horizontal and accepts `orientation="vertical"`.
+`Panel` supports `surface="default" | "muted" | "sidebar" | "transparent"`
+and `border="none" | "all" | "inline" | "block"`. Surface defaults to
+`default`; border defaults to `none`. The structural components otherwise
+accept native props for their rendered `section`, `header`, `div`, or `footer`.

package/src/components/ui/popover.md

@@ -21,11 +21,14 @@ Use `Popover` for a small, interactive surface anchored to a control. Use
 
 Sizes are `content`, `sm`, `default`, and `lg`. Content is capped to the
 collision-aware available width and height and scrolls when necessary.
-`material="regular"` is the standard temporary overlay. Use `clear` only above
-media or a richly colored canvas where the stronger sampled effect has a clear
-layering purpose.
+Content defaults to `size="default"`, `align="center"`, `sideOffset={4}`, and
+`material="regular"`. The `material` prop accepts every `MaterialVariant`:
+the five named thicknesses plus the `regular` and `clear` compatibility
+aliases. Use a thin surface only where the content behind it keeps text and
+controls legible.
 
-`PopoverClose`, `PopoverPortal`, and `PopoverArrow` are available when the
-composition needs them. Provide an accessible name on an icon-only close
-action. Keep required instructions and critical actions discoverable without
-hover.
+`PopoverContent` is already portalled. `PopoverAnchor`, `PopoverClose`, and
+`PopoverArrow` are available when the composition needs them;
+`PopoverPortal` is exported for custom primitive composition. Provide an
+accessible name on an icon-only trigger or close action. Keep required
+instructions and critical actions discoverable without hover.