@alexgorbatchev/shadcn 0.0.19 → 0.0.21

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/FileUpload.md

@@ -0,0 +1,55 @@
+# FileUpload
+
+Story: @alexgorbatchev/shadcn/components/forms/FileUpload
+Source: src/components/stories/forms/FileUpload.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/forms/FileUpload.stories.tsx)
+
+## Public imports
+
+```tsx
+import { FileUpload } from "@alexgorbatchev/shadcn/file-upload";
+```
+
+## Default component
+
+```tsx
+FileUpload
+```
+
+## Default args
+
+```tsx
+{
+    label: "Attachments",
+    description: "Text files, up to 10 bytes each.",
+    accept: { "text/plain": [".txt"] },
+    maxSize: 10,
+    onDrop: fn(),
+    onDropRejected: 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
+{}
+```
+
+### Rejected
+
+```tsx
+{}
+```
+
+### Disabled
+
+```tsx
+{
+    args: { disabled: true }
+}
+```

package/llms/components/forms/FilterBar.md

@@ -0,0 +1,34 @@
+# FilterBar
+
+Story: @alexgorbatchev/shadcn/components/forms/FilterBar
+Source: src/components/stories/forms/FilterBar.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/forms/FilterBar.stories.tsx)
+
+## Public imports
+
+```tsx
+import { FilterBar } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import { useState } from "react";
+```
+
+## Default render
+
+```tsx
+() => <Example />
+```
+
+## 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
+{}
+```

package/llms/components/forms/ImageCrop.md

@@ -0,0 +1,88 @@
+# ImageCrop
+
+Story: @alexgorbatchev/shadcn/components/forms/ImageCrop
+Source: src/components/stories/forms/ImageCrop.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/forms/ImageCrop.stories.tsx)
+
+## Public imports
+
+```tsx
+import { ImageCrop, cropToCanvas, type Crop } from "@alexgorbatchev/shadcn/image-crop";
+import { Button } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import { useState } from "react";
+import "react-image-crop/dist/ReactCrop.css";
+```
+
+## Default component
+
+```tsx
+ImageCrop
+```
+
+## Default args
+
+```tsx
+{ onChange: fn(), onComplete: fn() }
+```
+
+## Default render
+
+```tsx
+(args) => {
+    const [crop, setCrop] = useState<Crop>({ unit: "px", x: 20, y: 20, width: 100, height: 100 });
+    return (<ImageCrop {...args} crop={crop} onChange={(pixel, percent) => {
+            setCrop(pixel);
+            args.onChange(pixel, percent);
+        }}>
+        <img src={image} alt="Image to crop" width={320} height={240}/>
+      </ImageCrop>);
+}
+```
+
+## 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
+{}
+```
+
+### Export
+
+```tsx
+{
+    render: () => {
+        const [size, setSize] = useState("");
+        return (<>
+        <img src={image} alt="Source" width={320} height={240}/>
+        <Button onClick={async (event) => {
+                const source = event.currentTarget.parentElement?.querySelector("img");
+                if (!source)
+                    return;
+                const canvas = document.createElement("canvas");
+                await cropToCanvas(source, canvas, { unit: "px", x: 20, y: 20, width: 100, height: 80 });
+                setSize(`${canvas.width} × ${canvas.height}`);
+            }}>
+          Export crop
+        </Button>
+        <output aria-label="Export dimensions">{size}</output>
+      </>);
+    }
+}
+```
+
+### Disabled
+
+```tsx
+{
+    args: { disabled: true }
+}
+```