@alexgorbatchev/shadcn 0.0.19 → 0.0.21

package/llms/components/forms/InputGroup.md

@@ -0,0 +1,628 @@
+# InputGroup
+
+Story: @alexgorbatchev/shadcn/components/forms/InputGroup
+Source: src/components/stories/forms/InputGroup.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/forms/InputGroup.stories.tsx)
+
+## Public imports
+
+```tsx
+import { InputGroup, InputGroupInput, InputGroupTextarea, InputGroupAddon, InputGroupButton, InputGroupText, Field, FieldGroup, FieldLabel, FieldError, FieldDescription, Button, DirectionProvider, DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import { useId, useRef, useState } from "react";
+import type { InputState } from "@base-ui/react/input";
+import type { ButtonState } from "@base-ui/react/button";
+import { SearchIcon, CopyIcon } from "lucide-react";
+```
+
+## Default component
+
+```tsx
+InputGroup
+```
+
+## Default args
+
+```tsx
+{ onClick: fn() }
+```
+
+## Default render
+
+```tsx
+(args) => (<InputGroup {...args} aria-label="Project search">
+      <InputGroupInput aria-label="Search" placeholder="Search projects"/>
+      <InputGroupAddon aria-label="Search adornment">
+        <SearchIcon aria-hidden/>
+      </InputGroupAddon>
+      <InputGroupAddon align="inline-end">
+        <InputGroupText>⌘K</InputGroupText>
+      </InputGroupAddon>
+    </InputGroup>)
+```
+
+## 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.
+
+### Search
+
+```tsx
+{}
+```
+
+### WithAction
+
+```tsx
+{
+    render: function Render(args) {
+        const [value, setValue] = useState("https://example.com");
+        const [result, setResult] = useState("");
+        return (<Field>
+        <InputGroup {...args}>
+          <InputGroupInput aria-label="Project URL" value={value} onValueChange={setValue}/>
+          <InputGroupAddon align="inline-end">
+            <InputGroupButton aria-label="Copy URL" onClick={async () => {
+                try {
+                    await navigator.clipboard.writeText(value);
+                    setResult("URL copied");
+                }
+                catch {
+                    setResult("Clipboard access denied.");
+                }
+            }}>
+              <CopyIcon aria-hidden/>
+            </InputGroupButton>
+          </InputGroupAddon>
+        </InputGroup>
+        <output aria-label="Copy result">{result}</output>
+      </Field>);
+    }
+}
+```
+
+### Disabled
+
+```tsx
+{
+    render: (args) => (<InputGroup {...args}>
+      <InputGroupInput aria-label="Disabled search" disabled placeholder="Search"/>
+      <InputGroupAddon aria-label="Disabled adornment">
+        <SearchIcon aria-hidden/>
+      </InputGroupAddon>
+    </InputGroup>)
+}
+```
+
+### DisabledInputWithAction
+
+```tsx
+{
+    render: function Render(args) {
+        const [details, setDetails] = useState("Choose Details to inspect the project.");
+        return (<Field>
+        <InputGroup {...args}>
+          <InputGroupInput aria-label="Project code" defaultValue="AG-42" disabled/>
+          <InputGroupAddon>
+            <InputGroupText>Project</InputGroupText>
+          </InputGroupAddon>
+          <InputGroupAddon align="inline-end">
+            <InputGroupButton onClick={() => setDetails("Project AG-42")}>Details</InputGroupButton>
+          </InputGroupAddon>
+        </InputGroup>
+        <output aria-label="Project details">{details}</output>
+      </Field>);
+    }
+}
+```
+
+### Invalid
+
+```tsx
+{
+    render: (args) => (<Field data-invalid>
+      <InputGroup {...args}>
+        <InputGroupInput aria-label="Invalid search" aria-invalid defaultValue="?" aria-describedby="input-group-error"/>
+        <InputGroupAddon>
+          <SearchIcon aria-hidden/>
+        </InputGroupAddon>
+      </InputGroup>
+      <FieldError id="input-group-error">Enter a project name.</FieldError>
+    </Field>)
+}
+```
+
+### Textarea
+
+```tsx
+{
+    render: function Render(args) {
+        const [result, setResult] = useState("");
+        return (<form aria-label="Comment form" onSubmit={(event) => {
+                event.preventDefault();
+                setResult(String(new FormData(event.currentTarget).get("comment")));
+            }}>
+        <Field>
+          <InputGroup {...args}>
+            <InputGroupTextarea name="comment" aria-label="Comment" placeholder="Write a comment"/>
+            <InputGroupAddon align="block-end">
+              <InputGroupText>Markdown supported</InputGroupText>
+              <InputGroupButton type="submit" variant="default" size="sm">
+                Post
+              </InputGroupButton>
+            </InputGroupAddon>
+          </InputGroup>
+          <output aria-label="Posted comment">{result}</output>
+        </Field>
+      </form>);
+    }
+}
+```
+
+### AddonCallback
+
+```tsx
+{
+    render: (args) => (<InputGroup>
+      <InputGroupInput aria-label="Callback search"/>
+      <InputGroupAddon onClick={args.onClick}>
+        <InputGroupText>Search projects</InputGroupText>
+      </InputGroupAddon>
+    </InputGroup>)
+}
+```
+
+### CancelledAddonFocus
+
+```tsx
+{
+    render: (args) => (<FieldGroup>
+      <Button>Keep focus</Button>
+      <InputGroup {...args}>
+        <InputGroupInput aria-label="Cancelled search"/>
+        <InputGroupAddon onClick={(event) => event.preventDefault()}>
+          <InputGroupText>Cancelled addon</InputGroupText>
+        </InputGroupAddon>
+      </InputGroup>
+    </FieldGroup>)
+}
+```
+
+### LinkAddon
+
+```tsx
+{
+    render: (args) => (<InputGroup {...args}>
+      <InputGroupInput aria-label="Help search"/>
+      <InputGroupAddon align="inline-end">
+        <a href="#input-group-help" onClick={(event) => event.preventDefault()}>
+          Search help
+        </a>
+      </InputGroupAddon>
+    </InputGroup>)
+}
+```
+
+### NativeInputCallbacks
+
+```tsx
+{
+    render: function Render(args) {
+        const [isDisabled, setIsDisabled] = useState(false);
+        return (<Field>
+        <InputGroup {...args}>
+          <InputGroupInput aria-label="Native callback input" disabled={isDisabled} className={(state: InputState) => (state.disabled ? "h-12" : "h-8")}/>
+          <InputGroupAddon>
+            <InputGroupText>Native state</InputGroupText>
+          </InputGroupAddon>
+        </InputGroup>
+        <Button onClick={() => setIsDisabled(true)}>Disable callback input</Button>
+      </Field>);
+    }
+}
+```
+
+### NativeButtonCallbacks
+
+```tsx
+{
+    render: function Render(args) {
+        const [isDisabled, setIsDisabled] = useState(false);
+        return (<InputGroup {...args}>
+        <InputGroupInput aria-label="Native button input"/>
+        <InputGroupAddon align="inline-end">
+          <InputGroupButton disabled={isDisabled} className={(state: ButtonState) => (state.disabled ? "h-12" : "h-8")} onClick={() => setIsDisabled(true)}>
+            Disable action
+          </InputGroupButton>
+        </InputGroupAddon>
+      </InputGroup>);
+    }
+}
+```
+
+### NativeRenderAndRefs
+
+```tsx
+{
+    render: function Render(args) {
+        const inputRef = useRef<HTMLInputElement>(null);
+        const textareaRef = useRef<HTMLTextAreaElement>(null);
+        const buttonRef = useRef<HTMLButtonElement>(null);
+        return (<FieldGroup>
+        <InputGroup {...args}>
+          <InputGroupInput aria-label="Rendered input" render={<input data-testid="InputGroup--custom-input"/>} ref={inputRef}/>
+          <InputGroupAddon align="inline-end">
+            <InputGroupButton render={<button data-testid="InputGroup--custom-button"/>} ref={buttonRef}>
+              Native button
+            </InputGroupButton>
+          </InputGroupAddon>
+        </InputGroup>
+        <InputGroup>
+          <InputGroupTextarea aria-label="Native textarea" ref={textareaRef}/>
+        </InputGroup>
+        <Button onClick={() => inputRef.current?.focus()}>Focus input ref</Button>
+        <Button onClick={() => textareaRef.current?.focus()}>Focus textarea ref</Button>
+        <Button onClick={() => buttonRef.current?.focus()}>Focus button ref</Button>
+      </FieldGroup>);
+    }
+}
+```
+
+### FormSubmissionAndReset
+
+```tsx
+{
+    render: function Render(args) {
+        const [result, setResult] = useState("");
+        const id = useId();
+        return (<form aria-label="Group form" onSubmit={(event) => {
+                event.preventDefault();
+                setResult(JSON.stringify(Object.fromEntries(new FormData(event.currentTarget))));
+            }}>
+        <FieldGroup>
+          <Field>
+            <FieldLabel htmlFor={id}>Profile name</FieldLabel>
+            <InputGroup {...args}>
+              <InputGroupInput id={id} name="name" defaultValue="alex" required/>
+              <InputGroupAddon align="inline-end">
+                <InputGroupButton>Preview</InputGroupButton>
+              </InputGroupAddon>
+            </InputGroup>
+          </Field>
+          <InputGroup>
+            <InputGroupInput aria-label="Omitted name" name="omitted" defaultValue="hidden" disabled/>
+          </InputGroup>
+          <InputGroup>
+            <InputGroupTextarea aria-label="Profile notes" name="notes" defaultValue="Initial notes"/>
+            <InputGroupAddon align="block-end">
+              <InputGroupButton type="submit">Save group</InputGroupButton>
+              <InputGroupButton type="reset">Reset group</InputGroupButton>
+            </InputGroupAddon>
+          </InputGroup>
+          <output aria-label="Saved group">{result}</output>
+        </FieldGroup>
+      </form>);
+    }
+}
+```
+
+### BlockStart
+
+```tsx
+{
+    render: (args) => (<InputGroup {...args} aria-label="Block group">
+      <InputGroupInput aria-label="Block name"/>
+      <InputGroupAddon align="block-start">
+        <InputGroupText>Project name</InputGroupText>
+      </InputGroupAddon>
+    </InputGroup>)
+}
+```
+
+### ReadOnly
+
+```tsx
+{
+    render: (args) => (<InputGroup {...args}>
+      <InputGroupInput aria-label="Reference" readOnly defaultValue="REF-001"/>
+      <InputGroupAddon>
+        <InputGroupText>Reference code</InputGroupText>
+      </InputGroupAddon>
+    </InputGroup>)
+}
+```
+
+### RTL
+
+```tsx
+{
+    args: { dir: "rtl" }
+}
+```
+
+### Compact
+
+```tsx
+{
+    args: { density: "compact" }
+}
+```
+
+### Comfortable
+
+```tsx
+{
+    args: { density: "comfortable" }
+}
+```
+
+### ButtonSizes
+
+```tsx
+{
+    args: { density: "comfortable" },
+    render: (args) => (<FieldGroup>
+      <InputGroup {...args} aria-label="Small action group">
+        <InputGroupInput aria-label="Small action input"/>
+        <InputGroupAddon align="inline-end">
+          <InputGroupButton size="sm">Small action</InputGroupButton>
+        </InputGroupAddon>
+      </InputGroup>
+      <InputGroup {...args} aria-label="Small icon group">
+        <InputGroupInput aria-label="Small icon input"/>
+        <InputGroupAddon align="inline-end">
+          <InputGroupButton size="icon-sm" aria-label="Small icon action">
+            <SearchIcon aria-hidden/>
+          </InputGroupButton>
+        </InputGroupAddon>
+      </InputGroup>
+      <InputGroup {...args} aria-label="Extra small action group">
+        <InputGroupInput aria-label="Extra small action input"/>
+        <InputGroupAddon align="inline-end">
+          <InputGroupButton size="xs">Extra small action</InputGroupButton>
+        </InputGroupAddon>
+      </InputGroup>
+      <InputGroup {...args} aria-label="Extra small icon group">
+        <InputGroupInput aria-label="Extra small icon input"/>
+        <InputGroupAddon align="inline-end">
+          <InputGroupButton size="icon-xs" aria-label="Extra small icon action">
+            <SearchIcon aria-hidden/>
+          </InputGroupButton>
+        </InputGroupAddon>
+      </InputGroup>
+    </FieldGroup>)
+}
+```
+
+### CompactButtonSizes
+
+```tsx
+{
+    args: { density: "compact" },
+    render: (args) => (<FieldGroup>
+      <InputGroup {...args} aria-label="Small action group">
+        <InputGroupInput aria-label="Small action input"/>
+        <InputGroupAddon align="inline-end">
+          <InputGroupButton size="sm">Small action</InputGroupButton>
+        </InputGroupAddon>
+      </InputGroup>
+      <InputGroup {...args} aria-label="Small icon group">
+        <InputGroupInput aria-label="Small icon input"/>
+        <InputGroupAddon align="inline-end">
+          <InputGroupButton size="icon-sm" aria-label="Small icon action">
+            <SearchIcon aria-hidden/>
+          </InputGroupButton>
+        </InputGroupAddon>
+      </InputGroup>
+      <InputGroup {...args} aria-label="Extra small action group">
+        <InputGroupInput aria-label="Extra small action input"/>
+        <InputGroupAddon align="inline-end">
+          <InputGroupButton size="xs">Extra small action</InputGroupButton>
+        </InputGroupAddon>
+      </InputGroup>
+      <InputGroup {...args} aria-label="Extra small icon group">
+        <InputGroupInput aria-label="Extra small icon input"/>
+        <InputGroupAddon align="inline-end">
+          <InputGroupButton size="icon-xs" aria-label="Extra small icon action">
+            <SearchIcon aria-hidden/>
+          </InputGroupButton>
+        </InputGroupAddon>
+      </InputGroup>
+    </FieldGroup>)
+}
+```
+
+### InlineEnd
+
+```tsx
+{
+    render: (args) => (<InputGroup {...args}>
+      <InputGroupInput aria-label="Filter projects"/>
+      <InputGroupAddon align="inline-end" aria-label="Filter icon">
+        <SearchIcon aria-hidden/>
+      </InputGroupAddon>
+    </InputGroup>)
+}
+```
+
+### TextAffixes
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        return (<Field>
+        <FieldLabel htmlFor={id}>Budget (USD)</FieldLabel>
+        <InputGroup {...args}>
+          <InputGroupInput id={id} type="number" min={0} aria-describedby={id + "-help"}/>
+          <InputGroupAddon>
+            <InputGroupText>$</InputGroupText>
+          </InputGroupAddon>
+          <InputGroupAddon align="inline-end">
+            <InputGroupText>USD</InputGroupText>
+          </InputGroupAddon>
+        </InputGroup>
+        <FieldDescription id={id + "-help"}>Enter a nonnegative budget in US dollars.</FieldDescription>
+      </Field>);
+    }
+}
+```
+
+### RightToLeftAffixes
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        return (<Field>
+        <FieldLabel htmlFor={id}>Budget (USD)</FieldLabel>
+        <InputGroup {...args}>
+          <InputGroupInput id={id} type="number" min={0} aria-describedby={id + "-help"}/>
+          <InputGroupAddon>
+            <InputGroupText>$</InputGroupText>
+          </InputGroupAddon>
+          <InputGroupAddon align="inline-end">
+            <InputGroupText>USD</InputGroupText>
+          </InputGroupAddon>
+        </InputGroup>
+        <FieldDescription id={id + "-help"}>Enter a nonnegative budget in US dollars.</FieldDescription>
+      </Field>);
+    },
+    args: { dir: "rtl" },
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <div dir="rtl" className="w-80">
+          <Story />
+        </div>
+      </DirectionProvider>),
+    ]
+}
+```
+
+### DropdownAction
+
+```tsx
+{
+    render: function Render(args) {
+        const [format, setFormat] = useState("Markdown");
+        return (<Field>
+        <InputGroup {...args}>
+          <InputGroupInput aria-label="File name"/>
+          <InputGroupAddon align="inline-end">
+            <DropdownMenu>
+              <DropdownMenuTrigger render={<InputGroupButton aria-label="File actions"/>}>Format</DropdownMenuTrigger>
+              <DropdownMenuContent align="end">
+                <DropdownMenuGroup>
+                  <DropdownMenuItem onClick={() => setFormat("Markdown")}>Markdown</DropdownMenuItem>
+                  <DropdownMenuItem onClick={() => setFormat("Plain text")}>Plain text</DropdownMenuItem>
+                </DropdownMenuGroup>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </InputGroupAddon>
+        </InputGroup>
+        <output aria-label="File format">{format}</output>
+      </Field>);
+    }
+}
+```
+
+### RightToLeftDropdown
+
+```tsx
+{
+    render: function Render(args) {
+        const [format, setFormat] = useState("Markdown");
+        return (<Field>
+        <InputGroup {...args}>
+          <InputGroupInput aria-label="File name"/>
+          <InputGroupAddon align="inline-end">
+            <DropdownMenu>
+              <DropdownMenuTrigger render={<InputGroupButton aria-label="File actions"/>}>Format</DropdownMenuTrigger>
+              <DropdownMenuContent align="end">
+                <DropdownMenuGroup>
+                  <DropdownMenuItem onClick={() => setFormat("Markdown")}>Markdown</DropdownMenuItem>
+                  <DropdownMenuItem onClick={() => setFormat("Plain text")}>Plain text</DropdownMenuItem>
+                </DropdownMenuGroup>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </InputGroupAddon>
+        </InputGroup>
+        <output aria-label="File format">{format}</output>
+      </Field>);
+    },
+    args: { dir: "rtl" },
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <div dir="rtl" className="w-80">
+          <Story />
+        </div>
+      </DirectionProvider>),
+    ]
+}
+```
+
+### BlockStartTextarea
+
+```tsx
+{
+    render: (args) => (<InputGroup {...args}>
+      <InputGroupTextarea aria-label="Markdown notes"/>
+      <InputGroupAddon align="block-start">
+        <InputGroupText>Markdown editor</InputGroupText>
+      </InputGroupAddon>
+    </InputGroup>)
+}
+```
+
+### CustomControl
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        return (<Field>
+        <FieldLabel htmlFor={id}>Custom notes</FieldLabel>
+        <InputGroup {...args} aria-label="Custom notes group">
+          <textarea id={id} data-slot="input-group-control" aria-describedby={id + "-help"} className="field-sizing-content min-h-16 w-full resize-none bg-transparent px-control-x py-2 text-base outline-none"/>
+          <InputGroupAddon align="block-end">
+            <InputGroupText>Notes editor</InputGroupText>
+          </InputGroupAddon>
+        </InputGroup>
+        <FieldDescription id={id + "-help"}>The native custom control grows with its content.</FieldDescription>
+      </Field>);
+    }
+}
+```
+
+### RightToLeftCustomControl
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        return (<Field>
+        <FieldLabel htmlFor={id}>Custom notes</FieldLabel>
+        <InputGroup {...args} aria-label="Custom notes group">
+          <textarea id={id} data-slot="input-group-control" aria-describedby={id + "-help"} className="field-sizing-content min-h-16 w-full resize-none bg-transparent px-control-x py-2 text-base outline-none"/>
+          <InputGroupAddon align="block-end">
+            <InputGroupText>Notes editor</InputGroupText>
+          </InputGroupAddon>
+        </InputGroup>
+        <FieldDescription id={id + "-help"}>The native custom control grows with its content.</FieldDescription>
+      </Field>);
+    },
+    args: { dir: "rtl" },
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <div dir="rtl" className="w-80">
+          <Story />
+        </div>
+      </DirectionProvider>),
+    ]
+}
+```