@alexgorbatchev/shadcn 0.0.19 → 0.0.20

package/llms/components/forms/Questionnaire.md

@@ -0,0 +1,267 @@
+# Questionnaire
+
+Story: @alexgorbatchev/shadcn/components/forms/Questionnaire
+Source: src/components/stories/forms/Questionnaire.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/forms/Questionnaire.stories.tsx)
+
+## Public imports
+
+```tsx
+import { Questionnaire, QuestionnaireActions, QuestionnaireChoice, QuestionnaireChoiceDescription, QuestionnaireChoices, QuestionnaireDescription, QuestionnaireError, QuestionnaireInput, QuestionnaireItem, QuestionnaireNext, QuestionnairePrevious, QuestionnaireProgress, QuestionnaireSkip, QuestionnaireSubmit, QuestionnaireTitle } from "@alexgorbatchev/shadcn/questionnaire";
+import { Button, DensityProvider, Dialog, DialogClose, DialogContent, DialogDescription, DialogTitle, DialogTrigger, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, cn } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import type { ComponentProps, ReactElement } from "react";
+import { useId, useMemo, useState } from "react";
+import { z } from "zod";
+```
+
+## Default component
+
+```tsx
+Questionnaire
+```
+
+## Default args
+
+```tsx
+{ onItemChange: fn(), onSubmit: fn((event) => event.preventDefault()) }
+```
+
+## Default render
+
+```tsx
+(args) => <Survey {...args}/>
+```
+
+## 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.
+
+### MultiStep
+
+```tsx
+{}
+```
+
+### RequiredValidation
+
+```tsx
+{}
+```
+
+### FreeformAnswer
+
+```tsx
+{}
+```
+
+### LetterShortcuts
+
+```tsx
+{
+    args: { shortcuts: "letters" }
+}
+```
+
+### NumberShortcuts
+
+```tsx
+{
+    args: { shortcuts: "numbers" }
+}
+```
+
+### SkippedStatus
+
+```tsx
+{
+    args: { defaultItem: "optional" },
+    render: (args) => (<Questionnaire {...args}>
+      <QuestionnaireItem name="optional" onStatusChange={fn()}>
+        <QuestionnaireTitle>Optional preference</QuestionnaireTitle>
+        <QuestionnaireChoice value="saved" defaultChecked>
+          Saved preference
+        </QuestionnaireChoice>
+        <QuestionnaireError />
+      </QuestionnaireItem>
+      <QuestionnaireItem name="last">
+        <QuestionnaireTitle>Last question</QuestionnaireTitle>
+        <QuestionnaireInput aria-label="Final answer"/>
+      </QuestionnaireItem>
+      <QuestionnaireActions>
+        <QuestionnairePrevious />
+        <QuestionnaireSkip />
+        <QuestionnaireNext />
+        <QuestionnaireSubmit />
+      </QuestionnaireActions>
+    </Questionnaire>)
+}
+```
+
+### ValidateAllItems
+
+```tsx
+{
+    args: { defaultItem: "schedule" }
+}
+```
+
+### ResumeAndReset
+
+```tsx
+{
+    render: (args) => <ResumedSurvey {...args}/>
+}
+```
+
+### ControlledAndDisabledItems
+
+```tsx
+{
+    render: (args) => <ControlledSurvey {...args}/>
+}
+```
+
+### ComfortableDensity
+
+```tsx
+{
+    render: (args) => (<DensityProvider density="comfortable">
+      <Survey {...args}/>
+    </DensityProvider>)
+}
+```
+
+### CompactDensity
+
+```tsx
+{
+    render: (args) => (<DensityProvider density="compact">
+      <Survey {...args}/>
+    </DensityProvider>)
+}
+```
+
+### ChoiceIndicators
+
+```tsx
+{}
+```
+
+### ExternalValidation
+
+```tsx
+{
+    render: (args) => <ExternalValidationSurvey {...args}/>
+}
+```
+
+### NativeRenderAndRefs
+
+```tsx
+{
+    args: { ref: fn() },
+    render: (args) => (<Questionnaire {...args} shortcuts="letters" items={[{ name: "tool", required: true, choices: [{ value: "disabled", disabled: true }, { value: "native" }] }]}>
+      <QuestionnaireProgress render={(props, state) => (<div {...props}>
+            {state.current} enabled step of {state.total}
+          </div>)}/>
+      <QuestionnaireItem name="tool" required aria-labelledby="custom-question-title">
+        <QuestionnaireTitle id="custom-question-title" render={<h2 />}>
+          Choose a tool
+        </QuestionnaireTitle>
+        <QuestionnaireDescription render={<span />}>
+          Disabled tools are omitted from shortcuts.
+        </QuestionnaireDescription>
+        <QuestionnaireChoices>
+          <QuestionnaireChoice value="disabled" disabled>
+            Unavailable tool
+          </QuestionnaireChoice>
+          <QuestionnaireChoice value="native" render={(props, state) => <label {...props} title={String(state.checked)}/>}>
+            Native tool
+          </QuestionnaireChoice>
+        </QuestionnaireChoices>
+        <QuestionnaireActions>
+          <QuestionnaireSubmit render={(props, state) => <button {...props} disabled={state.status !== "answered"}/>}>
+            Confirm tool
+          </QuestionnaireSubmit>
+        </QuestionnaireActions>
+      </QuestionnaireItem>
+    </Questionnaire>)
+}
+```
+
+### DialogComposition
+
+```tsx
+{
+    render: (args) => (<Dialog>
+      <DialogTrigger>Configure project</DialogTrigger>
+      <DialogContent>
+        <DialogTitle>Project configuration</DialogTitle>
+        <DialogDescription>Complete the survey or cancel.</DialogDescription>
+        <Survey {...args}/>
+        <DialogClose>Cancel configuration</DialogClose>
+      </DialogContent>
+    </Dialog>)
+}
+```
+
+### ConditionalItems
+
+```tsx
+{
+    render: (args) => <ConditionalSurvey {...args}/>
+}
+```
+
+### NavigationState
+
+```tsx
+{
+    render: (args) => (<Survey {...args} nextAction={<QuestionnaireNext render={(props, state) => <button {...props} disabled={state.status !== "answered"}/>}/>}/>)
+}
+```
+
+### CustomProgress
+
+```tsx
+{
+    render: (args) => (<Survey {...args} progress={<QuestionnaireProgress className="w-full" render={(props, state) => (<div {...props}>
+              <div aria-hidden="true" className="flex gap-2">
+                {Array.from({ length: state.total }, (_, index) => (<span key={index} className={cn("h-1 flex-1", index < state.current ? "bg-primary" : "bg-muted")}/>))}
+              </div>
+              <span>
+                Checkpoint {state.current} of {state.total}
+              </span>
+            </div>)}/>}/>)
+}
+```
+
+### AnimatedItems
+
+```tsx
+{
+    render: (args) => (<Survey {...args} itemClassName="min-h-64 data-active:animate-in data-active:fade-in-0 data-active:duration-300 data-active:motion-reduce:animate-none"/>)
+}
+```
+
+### CardComposition
+
+```tsx
+{
+    render: (args) => <CardSurvey {...args}/>
+}
+```
+
+### SchemaValidation
+
+```tsx
+{
+    render: (args) => <SchemaSurvey {...args}/>
+}
+```

package/llms/components/forms/RadioGroup.md

@@ -0,0 +1,401 @@
+# RadioGroup
+
+Story: @alexgorbatchev/shadcn/components/forms/RadioGroup
+Source: src/components/stories/forms/RadioGroup.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/forms/RadioGroup.stories.tsx)
+
+## Public imports
+
+```tsx
+import { RadioGroup, RadioGroupItem, Field, FieldContent, FieldLabel, FieldSet, FieldLegend, FieldDescription, FieldError, Button, DirectionProvider } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import { useId, useState } from "react";
+import type { ComponentProps, ReactElement } from "react";
+```
+
+## Default component
+
+```tsx
+RadioGroup
+```
+
+## Default args
+
+```tsx
+{ defaultValue: "daily", onValueChange: fn() }
+```
+
+## Default render
+
+```tsx
+(args) => {
+    return (<FieldSet>
+        <FieldLegend>Update frequency</FieldLegend>
+        <RadioGroup aria-label="Update frequency" {...args}>
+          <FrequencyOptions disabled={args.disabled}/>
+        </RadioGroup>
+      </FieldSet>);
+}
+```
+
+## 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
+{}
+```
+
+### Weekly
+
+```tsx
+{
+    args: { defaultValue: "weekly" }
+}
+```
+
+### Unselected
+
+```tsx
+{
+    args: { defaultValue: undefined }
+}
+```
+
+### Disabled
+
+```tsx
+{
+    args: { disabled: true }
+}
+```
+
+### ReadOnly
+
+```tsx
+{
+    args: { readOnly: true }
+}
+```
+
+### DisabledItem
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        return (<FieldSet>
+        <FieldLegend>Update frequency</FieldLegend>
+        <RadioGroup {...args} aria-label="Update frequency">
+          <Field orientation="horizontal">
+            <RadioGroupItem value="daily" id={id + "-daily"}/>
+            <FieldLabel htmlFor={id + "-daily"}>Daily</FieldLabel>
+          </Field>
+          <Field data-disabled orientation="horizontal">
+            <RadioGroupItem value="weekly" id={id + "-weekly"} disabled/>
+            <FieldLabel htmlFor={id + "-weekly"}>Weekly</FieldLabel>
+          </Field>
+          <Field orientation="horizontal">
+            <RadioGroupItem value="monthly" id={id + "-monthly"}/>
+            <FieldLabel htmlFor={id + "-monthly"}>Monthly</FieldLabel>
+          </Field>
+        </RadioGroup>
+      </FieldSet>);
+    }
+}
+```
+
+### Controlled
+
+```tsx
+{
+    render: function Render(args) {
+        const [value, setValue] = useState("daily");
+        return (<FieldSet>
+        <FieldLegend>Controlled frequency</FieldLegend>
+        <RadioGroup {...args} aria-label="Controlled frequency" value={value} onValueChange={setValue}>
+          <FrequencyOptions />
+        </RadioGroup>
+        <output aria-label="Frequency preference">{value}</output>
+      </FieldSet>);
+    }
+}
+```
+
+### NativeGroupCallback
+
+```tsx
+{
+    args: { disabled: true, className: (state) => (state.disabled ? "gap-6" : "gap-2") }
+}
+```
+
+### NativeItemCallback
+
+```tsx
+{
+    render: (args) => (<FieldSet>
+      <FieldLegend>Update frequency</FieldLegend>
+      <RadioGroup {...args} aria-label="Update frequency">
+        <FrequencyOptions className={(state) => (state.checked ? "size-8" : "size-6")}/>
+      </RadioGroup>
+    </FieldSet>)
+}
+```
+
+### NativeStyleCallback
+
+```tsx
+{
+    render: (args) => (<FieldSet>
+      <FieldLegend>Update frequency</FieldLegend>
+      <RadioGroup {...args} aria-label="Update frequency">
+        <FrequencyOptions style={(state) => ({ height: state.checked ? 32 : 24 })}/>
+      </RadioGroup>
+    </FieldSet>)
+}
+```
+
+### CancelledChange
+
+```tsx
+{
+    args: { onValueChange: (_value, details) => details.cancel() }
+}
+```
+
+### NativeButton
+
+```tsx
+{
+    render: (args) => (<FieldSet>
+      <FieldLegend>Update frequency</FieldLegend>
+      <RadioGroup {...args} aria-label="Update frequency">
+        <FrequencyOptions nativeButton render={<button type="button"/>}/>
+      </RadioGroup>
+    </FieldSet>)
+}
+```
+
+### RightToLeft
+
+```tsx
+{
+    render: (args) => (<DirectionProvider direction="rtl">
+      <FieldSet dir="rtl">
+        <FieldLegend>Update frequency</FieldLegend>
+        <RadioGroup {...args} aria-label="Update frequency">
+          <FrequencyOptions />
+        </RadioGroup>
+      </FieldSet>
+    </DirectionProvider>)
+}
+```
+
+### RequiredForm
+
+```tsx
+{
+    args: { defaultValue: undefined, required: true, name: "frequency" },
+    render: function Render(args) {
+        const [result, setResult] = useState("");
+        const [value, setValue] = useState<string | null>(null);
+        return (<form aria-label="Frequency form" onReset={() => setValue(null)} onSubmit={(event) => {
+                event.preventDefault();
+                setResult(JSON.stringify(Object.fromEntries(new FormData(event.currentTarget))));
+            }}>
+        <FieldSet>
+          <FieldLegend>Update frequency</FieldLegend>
+          <RadioGroup {...args} aria-label="Update frequency" value={value} onValueChange={setValue}>
+            <FrequencyOptions />
+          </RadioGroup>
+          <Field orientation="horizontal">
+            <Button type="submit">Save frequency</Button>
+            <Button type="reset">Reset frequency</Button>
+          </Field>
+        </FieldSet>
+        <output aria-label="Saved frequency">{result}</output>
+      </form>);
+    }
+}
+```
+
+### ExternalFormAndRefs
+
+```tsx
+{
+    args: { inputRef: fn(), ref: fn() },
+    render: function Render(args) {
+        const formId = useId();
+        const [result, setResult] = useState("");
+        return (<FieldSet>
+        <FieldLegend>Update frequency</FieldLegend>
+        <form id={formId} aria-label="External frequency form" onSubmit={(event) => {
+                event.preventDefault();
+                setResult(JSON.stringify(Object.fromEntries(new FormData(event.currentTarget))));
+            }}>
+          <Button type="submit">Save external frequency</Button>
+          <output aria-label="Saved external frequency">{result}</output>
+        </form>
+        <RadioGroup {...args} name="frequency" form={formId} aria-label="Update frequency">
+          <FrequencyOptions />
+        </RadioGroup>
+      </FieldSet>);
+    }
+}
+```
+
+### WithDescription
+
+```tsx
+{
+    args: { defaultValue: "email" },
+    render: function Render(args) {
+        const id = useId();
+        const isInvalid = Boolean(args["aria-invalid"]);
+        return (<FieldSet className="w-80" aria-describedby={id + "-help"}>
+        <FieldLegend id={id + "-legend"} variant="label">
+          Notification delivery
+        </FieldLegend>
+        <FieldDescription id={id + "-help"}>Choose how to receive project updates.</FieldDescription>
+        <RadioGroup {...args} aria-labelledby={id + "-legend"} aria-describedby={id + "-help"}>
+          <Field orientation="horizontal" data-invalid={isInvalid}>
+            <RadioGroupItem id={id + "-email"} value="email" aria-invalid={isInvalid} aria-describedby={id + "-email-help"} aria-errormessage={isInvalid ? id + "-error" : undefined}/>
+            <FieldContent>
+              <FieldLabel htmlFor={id + "-email"}>Email</FieldLabel>
+              <FieldDescription id={id + "-email-help"}>Receive email updates.</FieldDescription>
+            </FieldContent>
+          </Field>
+          <Field orientation="horizontal" data-invalid={isInvalid}>
+            <RadioGroupItem id={id + "-sms"} value="sms" aria-invalid={isInvalid} aria-describedby={id + "-sms-help"} aria-errormessage={isInvalid ? id + "-error" : undefined}/>
+            <FieldContent>
+              <FieldLabel htmlFor={id + "-sms"}>Text message</FieldLabel>
+              <FieldDescription id={id + "-sms-help"}>Receive mobile updates.</FieldDescription>
+            </FieldContent>
+          </Field>
+        </RadioGroup>
+        {isInvalid && <FieldError id={id + "-error"}>Choose an available delivery method.</FieldError>}
+      </FieldSet>);
+    }
+}
+```
+
+### RightToLeftDescription
+
+```tsx
+{
+    args: { defaultValue: "email" },
+    render: function Render(args) {
+        const id = useId();
+        const isInvalid = Boolean(args["aria-invalid"]);
+        return (<FieldSet className="w-80" aria-describedby={id + "-help"}>
+        <FieldLegend id={id + "-legend"} variant="label">
+          Notification delivery
+        </FieldLegend>
+        <FieldDescription id={id + "-help"}>Choose how to receive project updates.</FieldDescription>
+        <RadioGroup {...args} aria-labelledby={id + "-legend"} aria-describedby={id + "-help"}>
+          <Field orientation="horizontal" data-invalid={isInvalid}>
+            <RadioGroupItem id={id + "-email"} value="email" aria-invalid={isInvalid} aria-describedby={id + "-email-help"} aria-errormessage={isInvalid ? id + "-error" : undefined}/>
+            <FieldContent>
+              <FieldLabel htmlFor={id + "-email"}>Email</FieldLabel>
+              <FieldDescription id={id + "-email-help"}>Receive email updates.</FieldDescription>
+            </FieldContent>
+          </Field>
+          <Field orientation="horizontal" data-invalid={isInvalid}>
+            <RadioGroupItem id={id + "-sms"} value="sms" aria-invalid={isInvalid} aria-describedby={id + "-sms-help"} aria-errormessage={isInvalid ? id + "-error" : undefined}/>
+            <FieldContent>
+              <FieldLabel htmlFor={id + "-sms"}>Text message</FieldLabel>
+              <FieldDescription id={id + "-sms-help"}>Receive mobile updates.</FieldDescription>
+            </FieldContent>
+          </Field>
+        </RadioGroup>
+        {isInvalid && <FieldError id={id + "-error"}>Choose an available delivery method.</FieldError>}
+      </FieldSet>);
+    },
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <div dir="rtl">
+          <Story />
+        </div>
+      </DirectionProvider>),
+    ]
+}
+```
+
+### Invalid
+
+```tsx
+{
+    args: { defaultValue: "email", "aria-invalid": true },
+    render: function Render(args) {
+        const id = useId();
+        const isInvalid = Boolean(args["aria-invalid"]);
+        return (<FieldSet className="w-80" aria-describedby={id + "-help"}>
+        <FieldLegend id={id + "-legend"} variant="label">
+          Notification delivery
+        </FieldLegend>
+        <FieldDescription id={id + "-help"}>Choose how to receive project updates.</FieldDescription>
+        <RadioGroup {...args} aria-labelledby={id + "-legend"} aria-describedby={id + "-help"}>
+          <Field orientation="horizontal" data-invalid={isInvalid}>
+            <RadioGroupItem id={id + "-email"} value="email" aria-invalid={isInvalid} aria-describedby={id + "-email-help"} aria-errormessage={isInvalid ? id + "-error" : undefined}/>
+            <FieldContent>
+              <FieldLabel htmlFor={id + "-email"}>Email</FieldLabel>
+              <FieldDescription id={id + "-email-help"}>Receive email updates.</FieldDescription>
+            </FieldContent>
+          </Field>
+          <Field orientation="horizontal" data-invalid={isInvalid}>
+            <RadioGroupItem id={id + "-sms"} value="sms" aria-invalid={isInvalid} aria-describedby={id + "-sms-help"} aria-errormessage={isInvalid ? id + "-error" : undefined}/>
+            <FieldContent>
+              <FieldLabel htmlFor={id + "-sms"}>Text message</FieldLabel>
+              <FieldDescription id={id + "-sms-help"}>Receive mobile updates.</FieldDescription>
+            </FieldContent>
+          </Field>
+        </RadioGroup>
+        {isInvalid && <FieldError id={id + "-error"}>Choose an available delivery method.</FieldError>}
+      </FieldSet>);
+    }
+}
+```
+
+### RightToLeftInvalid
+
+```tsx
+{
+    args: { defaultValue: "email", "aria-invalid": true },
+    render: function Render(args) {
+        const id = useId();
+        const isInvalid = Boolean(args["aria-invalid"]);
+        return (<FieldSet className="w-80" aria-describedby={id + "-help"}>
+        <FieldLegend id={id + "-legend"} variant="label">
+          Notification delivery
+        </FieldLegend>
+        <FieldDescription id={id + "-help"}>Choose how to receive project updates.</FieldDescription>
+        <RadioGroup {...args} aria-labelledby={id + "-legend"} aria-describedby={id + "-help"}>
+          <Field orientation="horizontal" data-invalid={isInvalid}>
+            <RadioGroupItem id={id + "-email"} value="email" aria-invalid={isInvalid} aria-describedby={id + "-email-help"} aria-errormessage={isInvalid ? id + "-error" : undefined}/>
+            <FieldContent>
+              <FieldLabel htmlFor={id + "-email"}>Email</FieldLabel>
+              <FieldDescription id={id + "-email-help"}>Receive email updates.</FieldDescription>
+            </FieldContent>
+          </Field>
+          <Field orientation="horizontal" data-invalid={isInvalid}>
+            <RadioGroupItem id={id + "-sms"} value="sms" aria-invalid={isInvalid} aria-describedby={id + "-sms-help"} aria-errormessage={isInvalid ? id + "-error" : undefined}/>
+            <FieldContent>
+              <FieldLabel htmlFor={id + "-sms"}>Text message</FieldLabel>
+              <FieldDescription id={id + "-sms-help"}>Receive mobile updates.</FieldDescription>
+            </FieldContent>
+          </Field>
+        </RadioGroup>
+        {isInvalid && <FieldError id={id + "-error"}>Choose an available delivery method.</FieldError>}
+      </FieldSet>);
+    },
+    decorators: RightToLeftDescription.decorators
+}
+```