@alexgorbatchev/shadcn 0.0.18 → 0.0.20

package/llms/components/forms/Input.md

@@ -0,0 +1,380 @@
+# Input
+
+Story: @alexgorbatchev/shadcn/components/forms/Input
+Source: src/components/stories/forms/Input.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/forms/Input.stories.tsx)
+
+## Public imports
+
+```tsx
+import { Input, Field, FieldGroup, FieldLabel, FieldDescription, FieldError, Button, Badge, ButtonGroup, InputGroup, InputGroupInput, InputGroupAddon, InputGroupText, DirectionProvider, Select, SelectTrigger, SelectValue, SelectContent, SelectGroup, SelectItem } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import { useId, useState } from "react";
+import type { InputState } from "@base-ui/react/input";
+```
+
+## Default component
+
+```tsx
+Input
+```
+
+## Default args
+
+```tsx
+{ placeholder: "alex@example.com", onChange: fn() }
+```
+
+## Default render
+
+```tsx
+(args) => {
+    const storyId = useId();
+    return (<Field data-invalid={args["aria-invalid"]} data-disabled={args.disabled}>
+        <FieldLabel htmlFor={`${storyId}-input-demo`}>
+          {args.type === "file" ? "Project file" : args.type === "password" ? "Password" : "Email"}
+        </FieldLabel>
+        <Input id={`${storyId}-input-demo`} aria-describedby={`${storyId}-input-help`} aria-errormessage={args["aria-invalid"] ? `${storyId}-input-error` : undefined} {...args}/>
+        <FieldDescription id={`${storyId}-input-help`}>Used for account notifications.</FieldDescription>
+        {args["aria-invalid"] && <FieldError id={`${storyId}-input-error`}>Check this value.</FieldError>}
+      </Field>);
+}
+```
+
+## 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
+{}
+```
+
+### Filled
+
+```tsx
+{
+    args: { defaultValue: "alex@example.com" }
+}
+```
+
+### Disabled
+
+```tsx
+{
+    args: { disabled: true }
+}
+```
+
+### Invalid
+
+```tsx
+{
+    args: { "aria-invalid": true }
+}
+```
+
+### ReadOnly
+
+```tsx
+{
+    args: { readOnly: true, defaultValue: "Read only value" }
+}
+```
+
+### Password
+
+```tsx
+{
+    args: { type: "password", placeholder: "Password" }
+}
+```
+
+### FileUpload
+
+```tsx
+{
+    args: { type: "file", placeholder: undefined, accept: ".txt" }
+}
+```
+
+### NativeCallbacks
+
+```tsx
+{
+    args: { className: (state: InputState) => (state.disabled ? "h-12" : "h-8") },
+    render: function Render(args) {
+        const [isDisabled, setIsDisabled] = useState(false);
+        const id = useId();
+        return (<Field>
+        <FieldLabel htmlFor={id}>Callback input</FieldLabel>
+        <Input {...args} id={id} disabled={isDisabled}/>
+        <Button onClick={() => setIsDisabled(true)}>Disable input</Button>
+      </Field>);
+    }
+}
+```
+
+### NativeValueChange
+
+```tsx
+{
+    args: { onValueChange: fn() }
+}
+```
+
+### Controlled
+
+```tsx
+{
+    render: function Render(args) {
+        const [value, setValue] = useState("");
+        return (<Field>
+        <Input {...args} aria-label="Uppercase name" value={value} onValueChange={(nextValue) => setValue(nextValue.toUpperCase())}/>
+        <output aria-label="Current name">{value}</output>
+      </Field>);
+    }
+}
+```
+
+### NativeRenderAndRef
+
+```tsx
+{
+    args: { render: <input data-testid="Input--custom"/>, ref: fn() }
+}
+```
+
+### NativeEmailValidation
+
+```tsx
+{
+    args: { type: "email", required: true }
+}
+```
+
+### FormSubmissionAndReset
+
+```tsx
+{
+    render: function Render(args) {
+        const [result, setResult] = useState("");
+        return (<form aria-label="Profile form" onSubmit={(event) => {
+                event.preventDefault();
+                setResult(JSON.stringify(Object.fromEntries(new FormData(event.currentTarget))));
+            }}>
+        <Field>
+          <Input {...args} name="email" aria-label="Profile email" defaultValue="alex@example.com"/>
+          <Input name="omitted" aria-label="Disabled profile field" disabled defaultValue="hidden"/>
+          <Button type="submit">Save profile</Button>
+          <Button type="reset">Reset profile</Button>
+        </Field>
+        <output aria-label="Saved profile">{result}</output>
+      </form>);
+    }
+}
+```
+
+### InlineSearch
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        const [query, setQuery] = useState("");
+        return (<form aria-label="Project search" onSubmit={(event) => {
+                event.preventDefault();
+                setQuery(String(new FormData(event.currentTarget).get("query")));
+            }}>
+        <Field orientation="horizontal">
+          <FieldLabel htmlFor={id} className="sr-only">
+            Search projects
+          </FieldLabel>
+          <Input {...args} id={id} name="query" required placeholder="Project name"/>
+          <Button type="submit">Search</Button>
+        </Field>
+        <output aria-label="Search query">{query}</output>
+      </form>);
+    }
+}
+```
+
+### GridFields
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        return (<FieldGroup className="grid grid-cols-2 gap-4">
+        <Field>
+          <FieldLabel htmlFor={id + "-first"}>First name</FieldLabel>
+          <Input {...args} id={id + "-first"}/>
+        </Field>
+        <Field>
+          <FieldLabel htmlFor={id + "-last"}>Last name</FieldLabel>
+          <Input {...args} id={id + "-last"}/>
+        </Field>
+      </FieldGroup>);
+    }
+}
+```
+
+### Required
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        return (<Field>
+        <FieldLabel htmlFor={id}>
+          Project name <span aria-hidden>*</span>
+        </FieldLabel>
+        <Input {...args} id={id} required aria-describedby={id + "-help"}/>
+        <FieldDescription id={id + "-help"}>A project name is required.</FieldDescription>
+      </Field>);
+    }
+}
+```
+
+### WithBadge
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        return (<Field>
+        <FieldLabel htmlFor={id}>
+          Webhook URL <Badge variant="secondary">Beta</Badge>
+        </FieldLabel>
+        <Input {...args} id={id} type="url" placeholder="https://example.com/webhook"/>
+      </Field>);
+    }
+}
+```
+
+### WithInputGroup
+
+```tsx
+{
+    render: function Render() {
+        const id = useId();
+        return (<Field>
+        <FieldLabel htmlFor={id}>Website domain</FieldLabel>
+        <InputGroup>
+          <InputGroupInput id={id} aria-describedby={id + "-help"}/>
+          <InputGroupAddon>
+            <InputGroupText>https://</InputGroupText>
+          </InputGroupAddon>
+        </InputGroup>
+        <FieldDescription id={id + "-help"}>Enter the domain without its protocol.</FieldDescription>
+      </Field>);
+    }
+}
+```
+
+### WithButtonGroup
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        const [query, setQuery] = useState("");
+        return (<form aria-label="Joined project search" onSubmit={(event) => {
+                event.preventDefault();
+                setQuery(String(new FormData(event.currentTarget).get("query")));
+            }}>
+        <Field>
+          <FieldLabel htmlFor={id}>Joined search</FieldLabel>
+          <ButtonGroup>
+            <Input {...args} id={id} name="query" required/>
+            <Button type="submit" variant="outline">
+              Find
+            </Button>
+          </ButtonGroup>
+        </Field>
+        <output aria-label="Joined search query">{query}</output>
+      </form>);
+    }
+}
+```
+
+### ProfileForm
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        const [result, setResult] = useState("");
+        const [runtime, setRuntime] = useState<string | null>("bun");
+        return (<form aria-label="Project profile" className="w-80" onReset={() => setRuntime("bun")} onSubmit={(event) => {
+                event.preventDefault();
+                setResult(JSON.stringify(Object.fromEntries(new FormData(event.currentTarget))));
+            }}>
+        <FieldGroup>
+          <Field>
+            <FieldLabel htmlFor={id + "-name"}>Name</FieldLabel>
+            <Input {...args} id={id + "-name"} name="name" required/>
+          </Field>
+          <Field>
+            <FieldLabel htmlFor={id + "-email"}>Contact email</FieldLabel>
+            <Input id={id + "-email"} type="email" name="email" aria-describedby={id + "-help"}/>
+            <FieldDescription id={id + "-help"}>Used for project updates.</FieldDescription>
+          </Field>
+          <FieldGroup className="grid grid-cols-2 gap-4">
+            <Field>
+              <FieldLabel htmlFor={id + "-phone"}>Phone</FieldLabel>
+              <Input id={id + "-phone"} type="tel" name="phone"/>
+            </Field>
+            <Field>
+              <FieldLabel htmlFor={id + "-runtime"}>Runtime</FieldLabel>
+              <Select items={fixture_runtimes} name="runtime" value={runtime} onValueChange={setRuntime}>
+                <SelectTrigger id={id + "-runtime"}>
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectGroup>
+                    {fixture_runtimes.map((item) => (<SelectItem key={item.value ?? "placeholder"} value={item.value}>
+                        {item.label}
+                      </SelectItem>))}
+                  </SelectGroup>
+                </SelectContent>
+              </Select>
+            </Field>
+          </FieldGroup>
+          <Field>
+            <FieldLabel htmlFor={id + "-address"}>Address</FieldLabel>
+            <Input id={id + "-address"} name="address"/>
+          </Field>
+          <Field orientation="horizontal">
+            <Button type="reset" variant="outline">
+              Reset
+            </Button>
+            <Button type="submit">Submit profile</Button>
+          </Field>
+        </FieldGroup>
+        <output aria-label="Submitted project profile">{result}</output>
+      </form>);
+    }
+}
+```
+
+### RightToLeft
+
+```tsx
+{
+    args: { dir: "rtl" },
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <div dir="rtl" className="w-80">
+          <Story />
+        </div>
+      </DirectionProvider>),
+    ]
+}
+```