@alexgorbatchev/shadcn 0.0.47 → 0.0.48

package/llms/components/navigation/ActionsMenu.md

@@ -0,0 +1,143 @@
+# ActionsMenu
+
+Story: @alexgorbatchev/shadcn/navigation/ActionsMenu
+Source: src/components/stories/navigation/ActionsMenu.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/navigation/ActionsMenu.stories.tsx)
+
+## Public imports
+
+```tsx
+import { ActionsMenu, ActionsMenuContextTarget, ActionsMenuContextContent, ActionsMenuTrigger, MenuGroup, MenuItem, MenuLinkItem, MenuLabel, MenuSeparator, MenuSub, MenuSubContent, MenuSubTrigger, Button } from "@alexgorbatchev/shadcn";
+import { Tree, TreeItem, useTree, syncDataLoaderFeature, hotkeysCoreFeature, selectionFeature } from "@alexgorbatchev/shadcn/tree";
+```
+
+## Supporting imports
+
+```tsx
+import type { ReactElement } from "react";
+```
+
+## Default component
+
+```tsx
+ActionsMenu
+```
+
+## Default args
+
+```tsx
+{
+    label: "Track actions",
+    items: (<MenuGroup>
+        <MenuItem onClick={() => fixture_menuAction("track-42")}>Inspect track</MenuItem>
+      </MenuGroup>),
+}
+```
+
+## Examples
+
+Storybook CSF excerpts. Default args and render apply unless overridden. Local helpers, fixtures, decorators, and providers may be required; these are reference excerpts, not standalone consumer modules. Interaction tests are omitted.
+
+### RegisteredTree
+
+```tsx
+{
+    render: () => <RegisteredTreeExample />
+}
+```
+
+### Dropdown
+
+```tsx
+{}
+```
+
+### BothEntryPoints
+
+```tsx
+{
+    args: { contextTarget: <section aria-label="Track"/> },
+    render: (args) => (<ActionsMenu {...args}>
+      <p>Selected track</p>
+      <ActionsMenuTrigger />
+    </ActionsMenu>)
+}
+```
+
+### NativeTableRow
+
+```tsx
+{
+    render: (args) => (<table>
+      <tbody>
+        <ActionsMenu {...args}>
+          <ActionsMenuContextTarget render={<tr ref={fixture_menuTargetRef}/>}>
+            <td>Track title</td>
+            <td>
+              <ActionsMenuTrigger />
+              <ActionsMenuContextContent />
+            </td>
+          </ActionsMenuContextTarget>
+        </ActionsMenu>
+      </tbody>
+    </table>)
+}
+```
+
+### Disabled
+
+```tsx
+{
+    args: { disabled: true, contextTarget: <section aria-label="Protected track"/> }
+}
+```
+
+### Submenu
+
+```tsx
+{
+    args: {
+        trigger: <Button variant="outline"/>,
+        contextTarget: <section aria-label="Playlist track"/>,
+        items: (<>
+        <MenuGroup>
+          <MenuLabel>Track</MenuLabel>
+          <MenuItem disabled>Unavailable action</MenuItem>
+        </MenuGroup>
+        <MenuSeparator />
+        <MenuGroup>
+          <MenuSub>
+            <MenuSubTrigger>Playlist</MenuSubTrigger>
+            <MenuSubContent>
+              <MenuGroup>
+                <MenuItem onClick={() => fixture_menuAction("playlist-7", "track-42")}>Add to favorites</MenuItem>
+              </MenuGroup>
+            </MenuSubContent>
+          </MenuSub>
+        </MenuGroup>
+      </>),
+    },
+    render: (args) => (<ActionsMenu {...args}>
+      <ActionsMenuTrigger>Track options</ActionsMenuTrigger>
+    </ActionsMenu>)
+}
+```
+
+### NativeLink
+
+```tsx
+{
+    args: {
+        size: "sm",
+        items: (<MenuGroup>
+        <MenuLinkItem href="#details" onClick={(event) => {
+                fixture_menuAction(event.currentTarget.hash);
+                event.preventDefault();
+            }}>
+          View details
+        </MenuLinkItem>
+      </MenuGroup>),
+    }
+}
+```

package/llms/components/overlays/ConfirmationDialog.md

@@ -70,8 +70,38 @@ Storybook CSF excerpts. Default args and render apply unless overridden. Local h
 {
     args: {
         onConfirm: async () => {
-            throw new Error("Could not remove image");
+            throw new Error("Private removal diagnostic");
         },
     }
 }
 ```
+
+### AuthoredFailureAndRetry
+
+```tsx
+{
+    args: {
+        onConfirm: fn(),
+        renderError: () => "The image is in use. Close the editor and retry.",
+    }
+}
+```
+
+### LongDescription
+
+```tsx
+{
+    args: { description: "Review this irreversible image removal carefully. ".repeat(300) }
+}
+```
+
+### Pending
+
+```tsx
+{
+    beforeEach: () => {
+        fixture_confirmation.pending = Promise.withResolvers<void>();
+    },
+    args: { onConfirm: fn(() => fixture_confirmation.pending.promise) }
+}
+```

package/llms/components/overlays/FormDialog.md

@@ -0,0 +1,102 @@
+# FormDialog
+
+Story: @alexgorbatchev/shadcn/components/overlays/FormDialog
+Source: src/components/stories/overlays/FormDialog.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/overlays/FormDialog.stories.tsx)
+
+## Public imports
+
+```tsx
+import { FormDialog, Input, Button } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import { useState, type ReactElement } from "react";
+```
+
+## Default component
+
+```tsx
+FormDialog
+```
+
+## Default args
+
+```tsx
+{
+    open: false,
+    onOpenChange: fn(),
+    title: "Edit project",
+    description: "Change the project name.",
+    submitLabel: "Save project",
+    onSubmit: fn((event) => event.preventDefault()),
+    children: <Input aria-label="Project name" defaultValue="Example"/>,
+}
+```
+
+## Default render
+
+```tsx
+function Example(args): ReactElement {
+    const [open, setOpen] = useState(false);
+    return (<>
+        <Button onClick={() => setOpen(true)}>Edit project</Button>
+        <FormDialog {...args} open={open} onOpenChange={(next) => {
+            args.onOpenChange(next);
+            setOpen(next);
+        }}/>
+      </>);
+}
+```
+
+## Examples
+
+Storybook CSF excerpts. Default args and render apply unless overridden. Local helpers, fixtures, decorators, and providers may be required; these are reference excerpts, not standalone consumer modules. Interaction tests are omitted.
+
+### Submit
+
+```tsx
+{}
+```
+
+### Busy
+
+```tsx
+{
+    args: { isBusy: true }
+}
+```
+
+### ConsentOnly
+
+```tsx
+{
+    args: {
+        onSubmit: undefined,
+        submitLabel: undefined,
+        primaryAction: <Button onClick={fixture_formDialogAction}>Review changes</Button>,
+    }
+}
+```
+
+### DoneOnly
+
+```tsx
+{
+    args: { onSubmit: undefined, submitLabel: undefined, cancelLabel: "Done" }
+}
+```
+
+### LongContent
+
+```tsx
+{
+    args: {
+        children: Array.from({ length: 60 }, (_, index) => <p key={index}>Project detail {index + 1}</p>),
+        error: "Save failed. Retry after checking the project.",
+    }
+}
+```

package/llms/setup.md

@@ -360,7 +360,7 @@ Compose `QuestionnaireItem`, `QuestionnaireTitle`, and answer controls inside `Q
 
 # Inline editing and ratings
 
-`InlineEdit` mounts an edit session with a controlled `value`, `onValueChange`, `onCommit`, and `onCancel`. Mount it in place of the displayed label. Its input focuses and selects its text by default; `shouldSelectOnMount={false}` preserves the initial caret. Enter or blur commits once, Escape cancels without committing, and asynchronous saves disable the input until completion. Rejected saves display an error and allow retry.
+`InlineEdit` mounts an edit session with a controlled `value`, `onValueChange`, `onCommit`, and `onCancel`. Mount it in place of the displayed label. Its input focuses and selects its text by default; `shouldSelectOnMount={false}` preserves the initial caret. Enter or blur commits once, Escape cancels without committing, and asynchronous saves disable the input until completion. Set `hasChanges={false}` to cancel an unchanged edit before calling `onCommit`; the caller owns normalization and comparison. It defaults to true, so creation sessions can commit their initial value. Rejected saves display a generic error and allow retry; `renderError` can map the unknown failure to application-authored guidance.
 
 `VirtualTable` renders a bounded, dynamically measured set of native table rows using TanStack Virtual. Supply `items`, stable `getItemKey`, `header`, `label`, and `renderRow`; spread the supplied measurement props onto each native row. Optional `columns` accepts a `TableColumnGroup`; responsive columns keep their widths aligned with cells that share their `visibleFrom`. `maxHeight` defaults to `65vh`, `estimateRowHeight` to 80 pixels, and `overscan` to five rows. `retainedKeys` keeps editing rows mounted; the focused row is retained automatically. Filtering and selection belong to the consumer.
 
@@ -370,6 +370,10 @@ Column `meta.filter` offers a column in `DataGridFilters`, hidden columns includ
 
 Import `DataGridSelectHeader` and `DataGridSelectCell` from `@alexgorbatchev/shadcn/data-grid`. Pass the current `useTable` result as `table` to both controls, and pass `row` and an accessible `label` to each cell. The header selects selectable filtered rows across all pages and preserves selections hidden by filters. It shows a mixed state when some of those rows are selected and disables itself when none are selectable. Its default label is "Select all filtered rows"; provide `label` to name the scope in your application. Cells follow native row selection rules, including disabled rows and partially selected parents. The controls observe selection changes without requiring the parent table selector to include selection state.
 
+`ActionsMenu` shares one `items` definition between a dropdown action and an optional context menu. Supply an accessible `label`; the default trigger is a ghost icon button. `size="sm"` displays the label, and `variant`, `disabled`, and `trigger` customize the action. Supplying `contextTarget` composes the native context trigger with that element and adds its popup. Compose items with `MenuItem`, `MenuLinkItem`, checkbox/radio parts, groups, labels, separators, shortcuts, and submenu parts; dropdown and context menus share these implementations. `MenuLinkItem` retains its native anchor and menu keyboard semantics.
+
+For nested layouts, compose `ActionsMenuTrigger`, `ActionsMenuContextTarget`, and `ActionsMenuContextContent` explicitly inside `ActionsMenu`. The dropdown trigger owns its local native dropdown root and popup; the context target and content share an independent context root. A tree row can use `TreeItem render={<ActionsMenuContextTarget />}` and put the trigger in its action slot. For a table row, render the context target as the actual `tr`, then place the dropdown trigger and context content inside a `td`: native popup portals insert focus guards at their declaration, which must remain valid table children.
+
 `TreeItem linkProps` places the registered tree item, roving focus, and native drag handlers on an anchor. Pass `href` and anchor events directly, or compose a router link through `linkProps.render`. The outer `render` and `ref` remain available for row overlays; disclosure and `endEnhancer` controls remain siblings of the link. Enter and modified clicks retain native link behavior, while tree arrows retain navigation and expansion behavior. Optional `dropHint={{ content, open, side }}` displays caller-controlled drag feedback without adding a focus target.
 
 Embedded actions, links, menus, editable fields, and media controls retain their own keyboard behavior. Registered anchor and button rows still participate in tree navigation; rename and search inputs retain their completion and cancellation shortcuts.
@@ -380,9 +384,11 @@ Embedded actions, links, menus, editable fields, and media controls retain their
 
 `DialogContent size="wide"` uses a desktop maximum width of 576px; `size="narrow"` uses 192px, and the default uses 384px. Dialogs remain bounded by the viewport. `FieldGroup columns={2}` arranges fields in two columns on desktop and one on mobile.
 
+`FormDialog` supplies a controlled dialog with a fixed heading and footer around a scrolling body. Supply `open`, `onOpenChange`, `title`, and children; `description`, `size`, and `density` are optional. With `onSubmit`, the body and actions use a native form: the caller handles `preventDefault`, validation, submission, and pending state. `submitLabel` adds the stock submit button, with optional `submitVariant` and `submitDisabled`; `primaryAction` supplies a custom action instead. Without `onSubmit`, custom actions can request consent without introducing a form. Without a primary action, `cancelLabel="Done"` gives a close-only footer. `isBusy` blocks native dismissal and disables the stock actions; callers disable their own inputs and custom actions. Pass already-rendered safe guidance through `error`.
+
 `ImagePicker` displays a 256px square preview with upload and unset buttons. Supply the existing `src`, a staged `file` (`undefined` for the existing image, `null` for removal), and `onFileChange`/`onClear` callbacks. It accepts PNG, JPEG, and GIF files and releases local preview URLs when they change or unmount. The consumer owns saving and removal confirmation.
 
-`ConfirmationDialog` uses an alert dialog with Cancel and a destructive confirmation button. Supply `open`, `onOpenChange`, `title`, `description`, `confirmLabel`, and `onConfirm`. It waits for asynchronous work, keeps the dialog open on failure, and prevents cancellation while that work is pending.
+`ConfirmationDialog` uses an alert dialog with Cancel and a destructive confirmation button. Supply `open`, `onOpenChange`, `title`, `description`, `confirmLabel`, and `onConfirm`. It waits for asynchronous work, keeps the dialog open on failure, and prevents cancellation while that work is pending. Its body scrolls within the viewport while the heading and actions stay visible. Failures display generic guidance by default; `renderError` maps unknown failures to application-authored messages.
 
 # Split views
 

package/llms.txt

@@ -431,6 +431,7 @@ Generated from the public package exports and Storybook sources.
 ## navigation
 
 - [AccountMenu](./llms/components/navigation/AccountMenu.md)
+- [ActionsMenu](./llms/components/navigation/ActionsMenu.md)
 - [Breadcrumb](./llms/components/navigation/Breadcrumb.md)
 - [Command](./llms/components/navigation/Command.md)
 - [ContextMenu](./llms/components/navigation/ContextMenu.md)
@@ -449,6 +450,7 @@ Generated from the public package exports and Storybook sources.
 - [ConfirmationDialog](./llms/components/overlays/ConfirmationDialog.md)
 - [Dialog](./llms/components/overlays/Dialog.md)
 - [Drawer](./llms/components/overlays/Drawer.md)
+- [FormDialog](./llms/components/overlays/FormDialog.md)
 - [HoverCard](./llms/components/overlays/HoverCard.md)
 - [Popover](./llms/components/overlays/Popover.md)
 - [Sheet](./llms/components/overlays/Sheet.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexgorbatchev/shadcn",
-  "version": "0.0.47",
+  "version": "0.0.48",
   "description": "Sharp, monospace React components with compact and comfortable densities.",
   "license": "MIT",
   "repository": {