@alexgorbatchev/shadcn 0.0.19 → 0.0.20

package/llms/components/forms/Field.md

@@ -0,0 +1,511 @@
+# Field
+
+Story: @alexgorbatchev/shadcn/components/forms/Field
+Source: src/components/stories/forms/Field.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/forms/Field.stories.tsx)
+
+## Public imports
+
+```tsx
+import { Field, FieldContent, FieldLabel, FieldTitle, FieldDescription, FieldError, FieldGroup, FieldSet, FieldLegend, FieldSeparator, Input, Checkbox, Button, Textarea, RadioGroup, RadioGroupItem, Switch, Slider, Select, SelectContent, SelectGroup, SelectItem, SelectTrigger, SelectValue, DirectionProvider } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import type { ReactElement } from "react";
+import { useId, useState } from "react";
+import { Controller, useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+```
+
+## Default component
+
+```tsx
+Field
+```
+
+## Default args
+
+```tsx
+{ orientation: "vertical" }
+```
+
+## Default render
+
+```tsx
+(args) => {
+    const storyId = useId();
+    return (<Field {...args}>
+        <FieldLabel htmlFor={`${storyId}-field-name`}>Project name</FieldLabel>
+        <Input id={`${storyId}-field-name`} aria-describedby={`${storyId}-field-help`} defaultValue="my-project"/>
+        <FieldDescription id={`${storyId}-field-help`}>Choose a recognizable name.</FieldDescription>
+      </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
+{}
+```
+
+### Horizontal
+
+```tsx
+{
+    args: { orientation: "horizontal" }
+}
+```
+
+### Responsive
+
+```tsx
+{
+    render: function Render() {
+        const id = useId();
+        const [isWide, setIsWide] = useState(false);
+        return (<>
+        <Button onClick={() => setIsWide((current) => !current)}>Resize fields</Button>
+        <FieldGroup style={{ width: isWide ? 600 : 360 }}>
+          <Field orientation="responsive">
+            <FieldContent>
+              <FieldLabel htmlFor={id}>Responsive name</FieldLabel>
+              <FieldDescription id={id + "-help"}>Provide your full name for identification.</FieldDescription>
+            </FieldContent>
+            <Input id={id} aria-describedby={id + "-help"}/>
+          </Field>
+        </FieldGroup>
+      </>);
+    }
+}
+```
+
+### Invalid
+
+```tsx
+{
+    render: () => {
+        const storyId = useId();
+        return (<Field data-invalid>
+        <FieldLabel htmlFor={`${storyId}-invalid-name`}>Project name</FieldLabel>
+        <Input id={`${storyId}-invalid-name`} aria-invalid aria-describedby={`${storyId}-invalid-message`} defaultValue=""/>
+        <FieldError id={`${storyId}-invalid-message`}>A project name is required.</FieldError>
+      </Field>);
+    }
+}
+```
+
+### Disabled
+
+```tsx
+{
+    render: () => {
+        const storyId = useId();
+        return (<Field data-disabled>
+        <FieldLabel htmlFor={`${storyId}-disabled-name`}>Project name</FieldLabel>
+        <Input id={`${storyId}-disabled-name`} disabled defaultValue="my-project"/>
+      </Field>);
+    }
+}
+```
+
+### Grouped
+
+```tsx
+{
+    render: () => {
+        const storyId = useId();
+        return (<FieldSet aria-describedby={`${storyId}-notify-help`}>
+        <FieldLegend>Notifications</FieldLegend>
+        <FieldDescription id={`${storyId}-notify-help`}>Select delivery channels.</FieldDescription>
+        <FieldGroup>
+          <Field orientation="horizontal">
+            <Checkbox id={`${storyId}-notify-email`} aria-describedby={`${storyId}-email-help`} defaultChecked/>
+            <FieldContent>
+              <FieldLabel htmlFor={`${storyId}-notify-email`}>Email</FieldLabel>
+              <FieldDescription id={`${storyId}-email-help`}>Weekly updates.</FieldDescription>
+            </FieldContent>
+          </Field>
+          <FieldSeparator>Or</FieldSeparator>
+          <Field orientation="horizontal">
+            <Checkbox id={`${storyId}-notify-desktop`}/>
+            <FieldLabel htmlFor={`${storyId}-notify-desktop`}>Desktop</FieldLabel>
+          </Field>
+        </FieldGroup>
+      </FieldSet>);
+    }
+}
+```
+
+### MultipleErrors
+
+```tsx
+{
+    render: () => (<Field data-invalid>
+      <FieldTitle>Validation</FieldTitle>
+      <FieldError errors={[{ message: "Required field." }, { message: "Invalid format." }, { message: "Required field." }]}/>
+    </Field>)
+}
+```
+
+### EmptyErrors
+
+```tsx
+{
+    render: () => (<Field>
+      <FieldTitle>Validation results</FieldTitle>
+      <FieldError errors={[undefined, {}, { message: "" }]}/>
+    </Field>)
+}
+```
+
+### SingleError
+
+```tsx
+{
+    render: () => (<Field>
+      <FieldTitle>Validation results</FieldTitle>
+      <FieldError errors={[{ message: "A name is required." }, { message: "A name is required." }]}/>
+    </Field>)
+}
+```
+
+### RightToLeftErrors
+
+```tsx
+{
+    render: () => (<Field data-invalid>
+      <FieldTitle>Validation</FieldTitle>
+      <FieldError errors={[{ message: "Required field." }, { message: "Invalid format." }, { message: "Required field." }]}/>
+    </Field>),
+    decorators: [
+        (Story) => (<div dir="rtl">
+        <Story />
+      </div>),
+    ]
+}
+```
+
+### HorizontalDescription
+
+```tsx
+{
+    render: function Render() {
+        const id = useId();
+        const [isHorizontal, setIsHorizontal] = useState(true);
+        return (<FieldGroup className="w-80">
+        <Field orientation={isHorizontal ? "horizontal" : "vertical"}>
+          <Checkbox id={id}/>
+          <FieldContent>
+            <FieldLabel htmlFor={id}>Project updates</FieldLabel>
+            <FieldDescription>
+              Receive weekly project news and important release updates from your team.
+            </FieldDescription>
+          </FieldContent>
+        </Field>
+        <Button onClick={() => setIsHorizontal((current) => !current)}>Change orientation</Button>
+      </FieldGroup>);
+    }
+}
+```
+
+### WithTextarea
+
+```tsx
+{
+    render: function Render() {
+        const id = useId();
+        return (<Field className="w-80">
+        <FieldLabel htmlFor={id}>Feedback</FieldLabel>
+        <Textarea id={id} aria-describedby={id + "-help"}/>
+        <FieldDescription id={id + "-help"}>Share your thoughts.</FieldDescription>
+      </Field>);
+    }
+}
+```
+
+### WithSelect
+
+```tsx
+{
+    render: function Render() {
+        const id = useId();
+        const [runtime, setRuntime] = useState<string | null>(null);
+        return (<Field className="w-80">
+        <FieldLabel htmlFor={id}>Runtime</FieldLabel>
+        <Select<string> items={fixture_runtimes} value={runtime} onValueChange={setRuntime}>
+          <SelectTrigger id={id} aria-describedby={id + "-help"}>
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectGroup>
+              {fixture_runtimes.map((item) => (<SelectItem key={item.value ?? "placeholder"} value={item.value}>
+                  {item.label}
+                </SelectItem>))}
+            </SelectGroup>
+          </SelectContent>
+        </Select>
+        <FieldDescription id={id + "-help"}>Choose the project runtime.</FieldDescription>
+        <output aria-label="Selected runtime">{runtime}</output>
+      </Field>);
+    }
+}
+```
+
+### WithSlider
+
+```tsx
+{
+    render: function Render() {
+        const id = useId();
+        const [range, setRange] = useState([200, 800]);
+        return (<Field className="w-80">
+        <FieldTitle id={id}>Budget range</FieldTitle>
+        <FieldDescription id={id + "-help"}>
+          Choose a budget from {range[0]} to {range[1]}.
+        </FieldDescription>
+        <Slider<number[]> value={range} onValueChange={setRange} min={0} max={1000} step={10} getAriaLabel={(index) => ["Minimum budget", "Maximum budget"][index]} aria-labelledby={id} aria-describedby={id + "-help"}/>
+        <output aria-label="Current budget">{range.join("–")}</output>
+      </Field>);
+    }
+}
+```
+
+### WithSwitch
+
+```tsx
+{
+    render: function Render() {
+        const id = useId();
+        return (<Field orientation="horizontal" className="w-80">
+        <FieldLabel htmlFor={id}>Multi-factor authentication</FieldLabel>
+        <Switch id={id}/>
+      </Field>);
+    }
+}
+```
+
+### WithRadio
+
+```tsx
+{
+    render: function Render() {
+        const id = useId();
+        return (<FieldSet className="w-80">
+        <FieldLegend variant="label">Subscription plan</FieldLegend>
+        <FieldDescription id={id + "-help"}>Choose how often to renew.</FieldDescription>
+        <RadioGroup defaultValue="monthly" aria-label="Subscription plan" aria-describedby={id + "-help"}>
+          <Field orientation="horizontal">
+            <RadioGroupItem id={id + "-monthly"} value="monthly"/>
+            <FieldLabel htmlFor={id + "-monthly"}>Monthly</FieldLabel>
+          </Field>
+          <Field orientation="horizontal">
+            <RadioGroupItem id={id + "-yearly"} value="yearly"/>
+            <FieldLabel htmlFor={id + "-yearly"}>Yearly</FieldLabel>
+          </Field>
+        </RadioGroup>
+      </FieldSet>);
+    }
+}
+```
+
+### RadioChoiceCards
+
+```tsx
+{
+    render: function Render() {
+        const id = useId();
+        return (<FieldGroup className="w-80">
+        <FieldSet>
+          <FieldLegend variant="label">Compute environment</FieldLegend>
+          <RadioGroup defaultValue="cluster" aria-label="Compute environment">
+            <FieldLabel htmlFor={id + "-cluster"}>
+              <Field orientation="horizontal">
+                <FieldContent>
+                  <FieldTitle>Cluster</FieldTitle>
+                  <FieldDescription>Run workloads together.</FieldDescription>
+                </FieldContent>
+                <RadioGroupItem id={id + "-cluster"} value="cluster"/>
+              </Field>
+            </FieldLabel>
+            <FieldLabel htmlFor={id + "-vm"}>
+              <Field orientation="horizontal">
+                <FieldContent>
+                  <FieldTitle>Virtual machine</FieldTitle>
+                  <FieldDescription>Run an isolated workload.</FieldDescription>
+                </FieldContent>
+                <RadioGroupItem id={id + "-vm"} value="vm"/>
+              </Field>
+            </FieldLabel>
+          </RadioGroup>
+        </FieldSet>
+      </FieldGroup>);
+    }
+}
+```
+
+### CheckboxChoiceCard
+
+```tsx
+{
+    render: function Render() {
+        const id = useId();
+        return (<FieldGroup className="w-80">
+        <FieldLabel htmlFor={id}>
+          <Field orientation="horizontal">
+            <FieldContent>
+              <FieldTitle>Sync files</FieldTitle>
+              <FieldDescription>Keep project files available.</FieldDescription>
+            </FieldContent>
+            <Checkbox id={id}/>
+          </Field>
+        </FieldLabel>
+      </FieldGroup>);
+    }
+}
+```
+
+### SwitchChoiceCard
+
+```tsx
+{
+    render: function Render() {
+        const id = useId();
+        return (<FieldGroup className="w-80">
+        <FieldLabel htmlFor={id}>
+          <Field orientation="horizontal">
+            <FieldContent>
+              <FieldTitle>Enable backup</FieldTitle>
+              <FieldDescription>Save a daily snapshot.</FieldDescription>
+            </FieldContent>
+            <Switch id={id}/>
+          </Field>
+        </FieldLabel>
+      </FieldGroup>);
+    }
+}
+```
+
+### RightToLeftChoiceCards
+
+```tsx
+{
+    render: function Render() {
+        const id = useId();
+        return (<FieldGroup className="w-80">
+        <FieldSet>
+          <FieldLegend variant="label">Compute environment</FieldLegend>
+          <RadioGroup defaultValue="cluster" aria-label="Compute environment">
+            <FieldLabel htmlFor={id + "-cluster"}>
+              <Field orientation="horizontal">
+                <FieldContent>
+                  <FieldTitle>Cluster</FieldTitle>
+                  <FieldDescription>Run workloads together.</FieldDescription>
+                </FieldContent>
+                <RadioGroupItem id={id + "-cluster"} value="cluster"/>
+              </Field>
+            </FieldLabel>
+            <FieldLabel htmlFor={id + "-vm"}>
+              <Field orientation="horizontal">
+                <FieldContent>
+                  <FieldTitle>Virtual machine</FieldTitle>
+                  <FieldDescription>Run an isolated workload.</FieldDescription>
+                </FieldContent>
+                <RadioGroupItem id={id + "-vm"} value="vm"/>
+              </Field>
+            </FieldLabel>
+          </RadioGroup>
+        </FieldSet>
+      </FieldGroup>);
+    },
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <div dir="rtl">
+          <Story />
+        </div>
+      </DirectionProvider>),
+    ]
+}
+```
+
+### RightToLeftGrouped
+
+```tsx
+{
+    render: () => {
+        const storyId = useId();
+        return (<FieldSet aria-describedby={`${storyId}-notify-help`}>
+        <FieldLegend>Notifications</FieldLegend>
+        <FieldDescription id={`${storyId}-notify-help`}>Select delivery channels.</FieldDescription>
+        <FieldGroup>
+          <Field orientation="horizontal">
+            <Checkbox id={`${storyId}-notify-email`} aria-describedby={`${storyId}-email-help`} defaultChecked/>
+            <FieldContent>
+              <FieldLabel htmlFor={`${storyId}-notify-email`}>Email</FieldLabel>
+              <FieldDescription id={`${storyId}-email-help`}>Weekly updates.</FieldDescription>
+            </FieldContent>
+          </Field>
+          <FieldSeparator>Or</FieldSeparator>
+          <Field orientation="horizontal">
+            <Checkbox id={`${storyId}-notify-desktop`}/>
+            <FieldLabel htmlFor={`${storyId}-notify-desktop`}>Desktop</FieldLabel>
+          </Field>
+        </FieldGroup>
+      </FieldSet>);
+    },
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <div dir="rtl">
+          <Story />
+        </div>
+      </DirectionProvider>),
+    ]
+}
+```
+
+### StandardSchemaValidation
+
+```tsx
+{
+    render: function Render() {
+        const id = useId();
+        const [issues, setIssues] = useState<ProfileValidation["issues"]>();
+        const [result, setResult] = useState("");
+        return (<form aria-label="Standard validation" noValidate className="w-80" onSubmit={async (event) => {
+                event.preventDefault();
+                const validation = await profileSchema["~standard"].validate(Object.fromEntries(new FormData(event.currentTarget)));
+                setIssues(validation.issues);
+                setResult(validation.issues ? "" : JSON.stringify(validation.value));
+            }}>
+        <FieldGroup>
+          <Field data-invalid={!!issues}>
+            <FieldLabel htmlFor={id + "-name"}>Display name</FieldLabel>
+            <Input id={id + "-name"} name="displayName" aria-invalid={!!issues} aria-describedby={issues ? id + "-errors" : undefined}/>
+          </Field>
+          <Field data-invalid={!!issues}>
+            <FieldLabel htmlFor={id + "-team"}>Team</FieldLabel>
+            <Input id={id + "-team"} name="team" aria-invalid={!!issues} aria-describedby={issues ? id + "-errors" : undefined}/>
+          </Field>
+          <FieldError id={id + "-errors"} errors={issues}/>
+          <Button type="submit">Validate profile</Button>
+          <output aria-label="Validated profile">{result}</output>
+        </FieldGroup>
+      </form>);
+    }
+}
+```
+
+### FormComposition
+
+```tsx
+{
+    render: () => <ReportForm />
+}
+```

package/llms/components/forms/ImagePicker.md

@@ -0,0 +1,63 @@
+# ImagePicker
+
+Story: @alexgorbatchev/shadcn/components/forms/ImagePicker
+Source: src/components/stories/forms/ImagePicker.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/forms/ImagePicker.stories.tsx)
+
+## Public imports
+
+```tsx
+import { ImagePicker } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import { useState, type ReactElement } from "react";
+```
+
+## Default component
+
+```tsx
+ImagePicker
+```
+
+## Default args
+
+```tsx
+{ src: fixture_avatarImage, label: "Cover artwork", onFileChange: fn(), onClear: fn() }
+```
+
+## Default render
+
+```tsx
+function Example(args): ReactElement {
+    const [file, setFile] = useState<File | null>();
+    return (<ImagePicker {...args} file={file} onFileChange={(file) => {
+            setFile(file);
+            args.onFileChange(file);
+        }} onClear={() => {
+            setFile(null);
+            args.onClear();
+        }}/>);
+}
+```
+
+## 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
+{}
+```
+
+### Disabled
+
+```tsx
+{
+    args: { disabled: true }
+}
+```

package/llms/components/forms/InlineEdit.md

@@ -0,0 +1,67 @@
+# InlineEdit
+
+Story: @alexgorbatchev/shadcn/components/forms/InlineEdit
+Source: src/components/stories/forms/InlineEdit.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/forms/InlineEdit.stories.tsx)
+
+## Public imports
+
+```tsx
+import { InlineEdit } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import { useState, type ReactElement } from "react";
+```
+
+## Default component
+
+```tsx
+InlineEdit
+```
+
+## Default args
+
+```tsx
+{ label: "Playlist title", value: "New playlist", onValueChange: fn(), onCommit: fn(), onCancel: fn() }
+```
+
+## Default render
+
+```tsx
+function Example(args, { id }): ReactElement {
+    const [value, setValue] = useState(args.value);
+    return <InlineEdit key={id} {...args} value={value} onValueChange={setValue}/>;
+}
+```
+
+## 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
+{}
+```
+
+### Cancel
+
+```tsx
+{}
+```
+
+### FailedSave
+
+```tsx
+{
+    args: {
+        onCommit: async () => {
+            throw new Error("Could not save");
+        },
+    }
+}
+```