@alexgorbatchev/shadcn 0.0.19 → 0.0.21

package/llms/components/overlays/HoverCard.md

@@ -0,0 +1,276 @@
+# HoverCard
+
+Story: @alexgorbatchev/shadcn/components/overlays/HoverCard
+Source: src/components/stories/overlays/HoverCard.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/overlays/HoverCard.stories.tsx)
+
+## Public imports
+
+```tsx
+import { HoverCard, HoverCardContent, HoverCardTrigger, DirectionProvider, DensityProvider, Avatar, AvatarFallback, AvatarImage, Button } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import type { ComponentProps, ReactElement } from "react";
+import { useState } from "react";
+```
+
+## Default component
+
+```tsx
+HoverCard
+```
+
+## Default args
+
+```tsx
+{ onOpenChange: fn() }
+```
+
+## 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.
+
+### Default
+
+```tsx
+{
+    render: (args) => (<HoverCard {...args}>
+      <HoverCardTrigger href="#profile" delay={0} closeDelay={0}>
+        Alex's profile
+      </HoverCardTrigger>
+      <HoverCardContent>
+        <p>Builds accessible component libraries.</p>
+      </HoverCardContent>
+    </HoverCard>)
+}
+```
+
+### StateCallback
+
+```tsx
+{
+    render: (args) => (<HoverCard {...args}>
+      <HoverCardTrigger href="#profile" delay={0} closeDelay={0}>
+        Alex's profile
+      </HoverCardTrigger>
+      <HoverCardContent density="compact" className={contentClassName}>
+        <p>Builds accessible component libraries.</p>
+      </HoverCardContent>
+    </HoverCard>)
+}
+```
+
+### RightToLeftEndAligned
+
+```tsx
+{
+    render: (args) => <RTLProfilePreview {...args} align="end"/>
+}
+```
+
+### RightToLeftInlineStart
+
+```tsx
+{
+    render: (args) => <RTLProfilePreview {...args} side="inline-start"/>
+}
+```
+
+### RightToLeftInlineEnd
+
+```tsx
+{
+    render: (args) => <RTLProfilePreview {...args} side="inline-end"/>
+}
+```
+
+### Bottom
+
+```tsx
+{
+    render: (args) => <ProfilePreview {...args}/>
+}
+```
+
+### Top
+
+```tsx
+{
+    render: (args) => <ProfilePreview {...args} side="top"/>
+}
+```
+
+### Left
+
+```tsx
+{
+    render: (args) => <ProfilePreview {...args} side="left"/>
+}
+```
+
+### Right
+
+```tsx
+{
+    render: (args) => <ProfilePreview {...args} side="right"/>
+}
+```
+
+### EndAligned
+
+```tsx
+{
+    render: (args) => <ProfilePreview {...args} align="end"/>
+}
+```
+
+### CompactPortal
+
+```tsx
+{
+    render: (args) => (<DensityProvider density="compact">
+      <ProfilePreview {...args}/>
+    </DensityProvider>)
+}
+```
+
+### TriggerDelays
+
+```tsx
+{
+    render: (args) => (<HoverCard {...args}>
+      <HoverCardTrigger href="#profile" delay={200} closeDelay={250}>
+        Delayed profile
+      </HoverCardTrigger>
+      <HoverCardContent>Delayed preview</HoverCardContent>
+    </HoverCard>)
+}
+```
+
+### KeyboardNavigation
+
+```tsx
+{
+    render: (args) => (<>
+      <ProfilePreview {...args}/>
+      <a href="#next">Next destination</a>
+    </>)
+}
+```
+
+### RightToLeft
+
+```tsx
+{
+    render: (args) => (<DirectionProvider direction="rtl">
+      <div dir="rtl" className="flex justify-center py-32">
+        <HoverCard {...args}>
+          <HoverCardTrigger href="#profile" delay={0} closeDelay={0}>
+            ملف أليكس
+          </HoverCardTrigger>
+          <HoverCardContent align="start" alignOffset={0}>
+            <p>يبني مكتبات مكونات قابلة للوصول.</p>
+          </HoverCardContent>
+        </HoverCard>
+      </div>
+    </DirectionProvider>)
+}
+```
+
+### Payload
+
+```tsx
+{
+    render: () => (<HoverCard<string>>
+      {({ payload }) => (<div className="flex justify-center gap-8 py-32">
+          <HoverCardTrigger<string> href="#alex" delay={0} closeDelay={0} payload="Alex">
+            Preview Alex
+          </HoverCardTrigger>
+          <HoverCardTrigger<string> href="#blair" delay={0} closeDelay={0} payload="Blair">
+            Preview Blair
+          </HoverCardTrigger>
+          <HoverCardContent>Profile: {payload?.toUpperCase()}</HoverCardContent>
+        </div>)}
+    </HoverCard>)
+}
+```
+
+### CancelledOpening
+
+```tsx
+{
+    render: (args) => (<HoverCard {...args}>
+      <HoverCardTrigger href="#profile" delay={0} closeDelay={0}>
+        Alex's profile
+      </HoverCardTrigger>
+      <HoverCardContent>
+        <p>Builds accessible component libraries.</p>
+      </HoverCardContent>
+    </HoverCard>),
+    args: { onOpenChange: fn((_open, details) => details.cancel()) }
+}
+```
+
+### CancelledClosing
+
+```tsx
+{
+    render: (args) => <ProfilePreview {...args}/>,
+    args: {
+        onOpenChange: fn((open, details) => {
+            if (!open)
+                details.cancel();
+        }),
+    }
+}
+```
+
+### PointerTransfer
+
+```tsx
+{
+    render: (args) => <ProfilePreview {...args} closeDelay={200}/>
+}
+```
+
+### NativeRenderAndRefs
+
+```tsx
+{
+    render: (args) => (<HoverCard {...args}>
+      <HoverCardTrigger href="#profile" delay={0} closeDelay={0} render={<a />} ref={triggerRef}>
+        Rendered profile
+      </HoverCardTrigger>
+      <HoverCardContent render={<section aria-label="Profile details"/>} ref={popupRef}>
+        Native preview
+      </HoverCardContent>
+    </HoverCard>)
+}
+```
+
+### Controlled
+
+```tsx
+{
+    render: function Render(args) {
+        const [isOpen, setIsOpen] = useState(false);
+        return (<>
+        <Button onClick={() => setIsOpen(!isOpen)}>Toggle preview</Button>
+        <HoverCard {...args} triggerId="controlled-profile" open={isOpen} onOpenChange={(open, details) => {
+                args.onOpenChange?.(open, details);
+                setIsOpen(open);
+            }}>
+          <HoverCardTrigger id="controlled-profile" href="#profile" delay={0} closeDelay={0}>
+            Controlled profile
+          </HoverCardTrigger>
+          <HoverCardContent>Controlled preview</HoverCardContent>
+        </HoverCard>
+        <output aria-label="Preview state">{String(isOpen)}</output>
+      </>);
+    }
+}
+```

package/llms/components/overlays/Popover.md

@@ -0,0 +1,286 @@
+# Popover
+
+Story: @alexgorbatchev/shadcn/components/overlays/Popover
+Source: src/components/stories/overlays/Popover.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/overlays/Popover.stories.tsx)
+
+## Public imports
+
+```tsx
+import { Popover, PopoverTrigger, PopoverContent, PopoverHeader, PopoverTitle, PopoverDescription, Button, DirectionProvider, DensityProvider, Field, FieldGroup, FieldLabel, Input } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import type { ComponentProps, ReactElement } from "react";
+import { useId, useRef, useState } from "react";
+import { Popover as PopoverPrimitive } from "@base-ui/react/popover";
+```
+
+## Default component
+
+```tsx
+Popover
+```
+
+## Default args
+
+```tsx
+{ onOpenChange: fn(), onOpenChangeComplete: fn() }
+```
+
+## Default render
+
+```tsx
+(args) => (<Popover {...args}>
+      <PopoverTrigger render={<Button variant="outline"/>}>Project details</PopoverTrigger>
+      <PopoverContent>
+        <PopoverHeader>
+          <PopoverTitle>Local workspace</PopoverTitle>
+          <PopoverDescription>All services are running.</PopoverDescription>
+        </PopoverHeader>
+      </PopoverContent>
+    </Popover>)
+```
+
+## 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.
+
+### Default
+
+```tsx
+{}
+```
+
+### Open
+
+```tsx
+{
+    args: { defaultOpen: true }
+}
+```
+
+### Modal
+
+```tsx
+{
+    args: { modal: true }
+}
+```
+
+### NativeCallbacks
+
+```tsx
+{
+    render: (args) => (<Popover {...args}>
+      <PopoverTrigger render={<Button />}>Callback popup</PopoverTrigger>
+      <PopoverContent className={(state) => (state.open ? "min-w-80" : "min-w-0")}>
+        <PopoverTitle className={() => "h-12"}>Callback title</PopoverTitle>
+        <PopoverDescription className={() => "min-h-10"}>Callback description</PopoverDescription>
+      </PopoverContent>
+    </Popover>)
+}
+```
+
+### MotionPreference
+
+```tsx
+{}
+```
+
+### RightToLeftStartAligned
+
+```tsx
+{
+    render: (args) => (<DirectionProvider direction="rtl">
+      <div dir="rtl" className="flex justify-center py-32">
+        <Popover {...args}>
+          <PopoverTrigger render={<Button />}>RTL placement</PopoverTrigger>
+          <PopoverContent align="start">
+            <PopoverTitle>RTL details</PopoverTitle>
+          </PopoverContent>
+        </Popover>
+      </div>
+    </DirectionProvider>)
+}
+```
+
+### Payload
+
+```tsx
+{
+    render: () => (<Popover<string>>
+      {({ payload }) => (<>
+          <PopoverTrigger<string> payload="Alex" render={<Button />}>
+            View Alex
+          </PopoverTrigger>
+          <PopoverTrigger<string> payload="Blair" render={<Button />}>
+            View Blair
+          </PopoverTrigger>
+          <PopoverContent>
+            <PopoverTitle>Profile: {payload?.toUpperCase()}</PopoverTitle>
+          </PopoverContent>
+        </>)}
+    </Popover>)
+}
+```
+
+### StartAligned
+
+```tsx
+{
+    render: (args) => <PlacementExample {...args}/>
+}
+```
+
+### CenterAligned
+
+```tsx
+{
+    render: (args) => <PlacementExample {...args} align="center"/>
+}
+```
+
+### EndAligned
+
+```tsx
+{
+    render: (args) => <PlacementExample {...args} align="end"/>
+}
+```
+
+### RightToLeftEndAligned
+
+```tsx
+{
+    render: (args) => <PlacementExample {...args} align="end" direction="rtl"/>
+}
+```
+
+### Top
+
+```tsx
+{
+    render: (args) => <PlacementExample {...args} side="top"/>
+}
+```
+
+### Left
+
+```tsx
+{
+    render: (args) => <PlacementExample {...args} side="left"/>
+}
+```
+
+### Right
+
+```tsx
+{
+    render: (args) => <PlacementExample {...args} side="right"/>
+}
+```
+
+### NativeForm
+
+```tsx
+{
+    render: (args) => <DimensionsFormExample {...args}/>
+}
+```
+
+### RTLNativeForm
+
+```tsx
+{
+    render: (args) => <DimensionsFormExample {...args} direction="rtl"/>
+}
+```
+
+### CancelledOpening
+
+```tsx
+{
+    args: { onOpenChange: fn((_open, details) => details.cancel()) }
+}
+```
+
+### CancelledClosing
+
+```tsx
+{
+    render: (args) => <PlacementExample {...args}/>,
+    args: {
+        onOpenChange: fn((open, details) => {
+            if (!open)
+                details.cancel();
+        }),
+    }
+}
+```
+
+### CompactPortal
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        return (<DensityProvider density="compact">
+        <Popover {...args}>
+          <PopoverTrigger render={<Button />}>Placement details</PopoverTrigger>
+          <PopoverContent>
+            <PopoverTitle>Aligned popup</PopoverTitle>
+            <Field>
+              <FieldLabel htmlFor={id}>Project ID</FieldLabel>
+              <Input id={id} readOnly defaultValue="project-42"/>
+            </Field>
+          </PopoverContent>
+        </Popover>
+      </DensityProvider>);
+    }
+}
+```
+
+### CustomFocusAndNativeRender
+
+```tsx
+{
+    render: function Render(args) {
+        const inputRef = useRef<HTMLInputElement>(null);
+        const finalRef = useRef<HTMLButtonElement>(null);
+        const id = useId();
+        return (<>
+        <Button ref={finalRef}>Return destination</Button>
+        <Popover {...args}>
+          <PopoverTrigger render={<Button />}>Custom focus popup</PopoverTrigger>
+          <PopoverContent initialFocus={inputRef} finalFocus={finalRef} ref={popupRef} render={<section />}>
+            <PopoverTitle>Custom focus details</PopoverTitle>
+            <Field>
+              <FieldLabel htmlFor={id}>Project name</FieldLabel>
+              <Input id={id} ref={inputRef} defaultValue="Alex"/>
+            </Field>
+            <PopoverPrimitive.Close render={<Button variant="outline"/>}>Done</PopoverPrimitive.Close>
+          </PopoverContent>
+        </Popover>
+      </>);
+    }
+}
+```
+
+### ModalFocusTrap
+
+```tsx
+{
+    render: (args) => (<Popover {...args} modal>
+      <PopoverTrigger render={<Button />}>Open modal popup</PopoverTrigger>
+      <PopoverContent>
+        <PopoverTitle>Modal details</PopoverTitle>
+        <Button>First action</Button>
+        <PopoverPrimitive.Close render={<Button />}>Close popup</PopoverPrimitive.Close>
+      </PopoverContent>
+    </Popover>)
+}
+```