@alexgorbatchev/shadcn 0.0.19 → 0.0.21

package/llms/components/forms/Select.md

@@ -0,0 +1,575 @@
+# Select
+
+Story: @alexgorbatchev/shadcn/components/forms/Select
+Source: src/components/stories/forms/Select.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/forms/Select.stories.tsx)
+
+## Public imports
+
+```tsx
+import { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectTrigger, SelectValue, SelectSeparator, SelectScrollUpButton, SelectScrollDownButton, DirectionProvider, DensityProvider, Button, Field, FieldGroup, FieldLabel, FieldError } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import { useId, useRef, useState } from "react";
+import type { ComponentProps } from "react";
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import type { SelectRootChangeEventDetails } from "@base-ui/react/select";
+```
+
+## Default component
+
+```tsx
+Select
+```
+
+## Default args
+
+```tsx
+{ items: fixture_runtimes, onValueChange: fn(), onOpenChange: fn() }
+```
+
+## Default render
+
+```tsx
+({ triggerClassName, valueClassName, contentClassName, groupClassName, labelClassName, itemClassName, separatorClassName, ...args }) => (<Select {...args}>
+      <SelectTrigger aria-label="Runtime" className={triggerClassName}>
+        <SelectValue className={valueClassName}/>
+      </SelectTrigger>
+      <SelectContent className={contentClassName}>
+        <SelectGroup className={groupClassName}>
+          <SelectLabel className={labelClassName}>Runtime</SelectLabel>
+          {fixture_runtimes
+        .filter((item) => !args.multiple || item.value !== null)
+        .map((item) => (<SelectItem key={item.value ?? "placeholder"} value={item.value} className={itemClassName}>
+                {item.label}
+              </SelectItem>))}
+          <SelectSeparator className={separatorClassName} data-testid="Select--separator"/>
+        </SelectGroup>
+      </SelectContent>
+    </Select>)
+```
+
+## 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
+{}
+```
+
+### Selected
+
+```tsx
+{
+    args: { defaultValue: "bun" }
+}
+```
+
+### Disabled
+
+```tsx
+{
+    args: { disabled: true }
+}
+```
+
+### Multiple
+
+```tsx
+{
+    args: { multiple: true, defaultValue: ["bun", "node"] }
+}
+```
+
+### Small
+
+```tsx
+{
+    render: (args) => (<Select {...args}>
+      <SelectTrigger size="sm" aria-label="Runtime">
+        <SelectValue />
+      </SelectTrigger>
+      <SelectContent alignItemWithTrigger={false}>
+        <SelectGroup>
+          {fixture_runtimes.map((item) => (<SelectItem key={item.value ?? "placeholder"} value={item.value}>
+              {item.label}
+            </SelectItem>))}
+        </SelectGroup>
+      </SelectContent>
+    </Select>)
+}
+```
+
+### Keyboard
+
+```tsx
+{}
+```
+
+### Typeahead
+
+```tsx
+{}
+```
+
+### ReadOnly
+
+```tsx
+{
+    args: { readOnly: true, defaultValue: "bun" }
+}
+```
+
+### CancelledSelection
+
+```tsx
+{
+    args: {
+        defaultValue: "bun",
+        onValueChange: fn((_value: unknown, details: SelectRootChangeEventDetails) => details.cancel()),
+    }
+}
+```
+
+### Controlled
+
+```tsx
+{
+    render: function Render() {
+        const [value, setValue] = useState<string | null>("bun");
+        return (<Field>
+        <Select<string> items={fixture_runtimes} value={value} onValueChange={setValue}>
+          <SelectTrigger aria-label="Controlled runtime">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectGroup>
+              {fixture_runtimes.map((item) => (<SelectItem key={item.value ?? "placeholder"} value={item.value}>
+                  {item.label}
+                </SelectItem>))}
+            </SelectGroup>
+          </SelectContent>
+        </Select>
+        <output aria-label="Current runtime">{value}</output>
+      </Field>);
+    }
+}
+```
+
+### NativeCallbacks
+
+```tsx
+{
+    args: {
+        triggerClassName: (state) => (state.open ? "w-64" : "w-48"),
+        valueClassName: (state) => (state.placeholder ? "flex-none w-20" : "flex-none w-32"),
+        contentClassName: () => "p-4",
+        groupClassName: () => "p-3",
+        labelClassName: () => "h-8",
+        itemClassName: (state) => (state.selected ? "h-12" : "h-8"),
+        separatorClassName: (state) => (state.orientation === "horizontal" ? "h-2" : "w-2 h-8"),
+    }
+}
+```
+
+### DisabledItem
+
+```tsx
+{
+    render: (args) => (<Select {...args}>
+      <SelectTrigger aria-label="Runtime">
+        <SelectValue />
+      </SelectTrigger>
+      <SelectContent>
+        <SelectGroup>
+          {fixture_runtimes.map((item) => (<SelectItem key={item.value ?? "placeholder"} value={item.value} disabled={item.value === "node"}>
+              {item.label}
+            </SelectItem>))}
+        </SelectGroup>
+      </SelectContent>
+    </Select>)
+}
+```
+
+### Invalid
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        return (<Field data-invalid>
+        <FieldLabel htmlFor={id}>Runtime</FieldLabel>
+        <Select {...args}>
+          <SelectTrigger id={id} aria-invalid aria-describedby={`${id}-error`} aria-errormessage={`${id}-error`}>
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectGroup>
+              {fixture_runtimes
+                .filter((item) => !args.multiple || item.value !== null)
+                .map((item) => (<SelectItem key={item.value ?? "placeholder"} value={item.value}>
+                    {item.label}
+                  </SelectItem>))}
+            </SelectGroup>
+          </SelectContent>
+        </Select>
+        <FieldError id={`${id}-error`}>Choose a runtime.</FieldError>
+      </Field>);
+    }
+}
+```
+
+### NativeRenderAndRef
+
+```tsx
+{
+    render: function Render() {
+        const ref = useRef<HTMLButtonElement>(null);
+        return (<Field>
+        <Select items={fixture_runtimes}>
+          <SelectTrigger aria-label="Runtime" render={<button data-testid="Select--native-trigger"/>} ref={ref}>
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent render={<section data-testid="Select--native-popup"/>}>
+            <SelectGroup>
+              {fixture_runtimes.map((item) => (<SelectItem key={item.value ?? "placeholder"} value={item.value}>
+                  {item.label}
+                </SelectItem>))}
+            </SelectGroup>
+          </SelectContent>
+        </Select>
+        <Button onClick={() => ref.current?.focus()}>Focus runtime ref</Button>
+      </Field>);
+    }
+}
+```
+
+### ObjectValues
+
+```tsx
+{
+    render: function Render() {
+        const [value, setValue] = useState<RuntimeEngine | null>({ id: "bun", name: "Bun" });
+        return (<form aria-label="Object engine form">
+        <Field>
+          <Select<RuntimeEngine> name="engine" value={value} onValueChange={setValue} itemToStringLabel={(engine) => engine.name} itemToStringValue={(engine) => engine.id} isItemEqualToValue={(item, current) => item.id === current.id}>
+            <SelectTrigger aria-label="Object runtime">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectGroup>
+                {fixture_runtimeEngines.map((engine) => (<SelectItem key={engine.id} value={engine}>
+                    {engine.name}
+                  </SelectItem>))}
+              </SelectGroup>
+            </SelectContent>
+          </Select>
+          <output aria-label="Selected engine">{value?.id}</output>
+        </Field>
+      </form>);
+    }
+}
+```
+
+### CompactPortal
+
+```tsx
+{
+    render: (args) => (<DensityProvider density="compact">
+      <Select {...args}>
+        <SelectTrigger aria-label="Runtime">
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent alignItemWithTrigger={false}>
+          <SelectGroup>
+            {fixture_runtimes.map((item) => (<SelectItem key={item.value ?? "placeholder"} value={item.value}>
+                {item.label}
+              </SelectItem>))}
+          </SelectGroup>
+        </SelectContent>
+      </Select>
+    </DensityProvider>)
+}
+```
+
+### RTL
+
+```tsx
+{
+    render: (args) => (<DirectionProvider direction="rtl">
+      <div dir="rtl">
+        <Select {...args} defaultValue="bun">
+          <SelectTrigger aria-label="Runtime">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent alignItemWithTrigger={false}>
+            <SelectGroup>
+              {fixture_runtimes.map((item) => (<SelectItem key={item.value ?? "placeholder"} value={item.value}>
+                  {item.label}
+                </SelectItem>))}
+            </SelectGroup>
+          </SelectContent>
+        </Select>
+      </div>
+    </DirectionProvider>)
+}
+```
+
+### Scrollable
+
+```tsx
+{
+    render: (args) => (<Select {...args} items={fixture_projectNumbers} defaultValue={10}>
+      <SelectTrigger aria-label="Project number">
+        <SelectValue />
+      </SelectTrigger>
+      <SelectContent className="max-h-48" alignItemWithTrigger={false}>
+        <SelectGroup>
+          {fixture_projectNumbers.map((item) => (<SelectItem key={item.value} value={item.value}>
+              {item.label}
+            </SelectItem>))}
+        </SelectGroup>
+      </SelectContent>
+    </Select>)
+}
+```
+
+### ScrollCallbacks
+
+```tsx
+{
+    render: (args) => (<Select {...args}>
+      <SelectTrigger aria-label="Runtime">
+        <SelectValue />
+      </SelectTrigger>
+      <SelectPrimitive.Portal>
+        <SelectPrimitive.Positioner alignItemWithTrigger={false}>
+          <SelectPrimitive.Popup>
+            <SelectScrollUpButton keepMounted className={() => "h-10"} data-testid="Select--scroll-up"/>
+            <SelectPrimitive.List>
+              <SelectGroup>
+                {fixture_runtimes.map((item) => (<SelectItem key={item.value ?? "placeholder"} value={item.value}>
+                    {item.label}
+                  </SelectItem>))}
+              </SelectGroup>
+            </SelectPrimitive.List>
+            <SelectScrollDownButton keepMounted className={() => "h-10"} data-testid="Select--scroll-down"/>
+          </SelectPrimitive.Popup>
+        </SelectPrimitive.Positioner>
+      </SelectPrimitive.Portal>
+    </Select>)
+}
+```
+
+### FormSubmissionAndReset
+
+```tsx
+{
+    render: function Render() {
+        const [runtime, setRuntime] = useState<string | null>(null);
+        const [runtimes, setRuntimes] = useState<string[]>(["bun"]);
+        const [result, setResult] = useState("");
+        const id = useId();
+        return (<form aria-label="Runtime form" onReset={() => {
+                setRuntime(null);
+                setRuntimes(["bun"]);
+            }} onSubmit={(event) => {
+                event.preventDefault();
+                const data = new FormData(event.currentTarget);
+                setResult(JSON.stringify({
+                    runtime: data.get("runtime"),
+                    runtimes: data.getAll("runtimes"),
+                    omitted: data.get("omitted"),
+                }));
+            }}>
+        <FieldGroup>
+          <Field>
+            <FieldLabel htmlFor={id}>Required runtime</FieldLabel>
+            <Select<string> id={id} name="runtime" required value={runtime} onValueChange={setRuntime} items={fixture_runtimes}>
+              <SelectTrigger>
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectGroup>
+                  {fixture_runtimes.map((item) => (<SelectItem key={item.value ?? "placeholder"} value={item.value}>
+                      {item.label}
+                    </SelectItem>))}
+                </SelectGroup>
+              </SelectContent>
+            </Select>
+          </Field>
+          <Select<string, true> name="runtimes" multiple value={runtimes} onValueChange={setRuntimes} items={fixture_runtimes}>
+            <SelectTrigger aria-label="Supported runtimes">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectGroup>
+                {fixture_runtimes
+                .filter((item) => item.value !== null)
+                .map((item) => (<SelectItem key={item.value} value={item.value}>
+                      {item.label}
+                    </SelectItem>))}
+              </SelectGroup>
+            </SelectContent>
+          </Select>
+          <Select name="omitted" disabled defaultValue="deno" items={fixture_runtimes}>
+            <SelectTrigger aria-label="Disabled runtime">
+              <SelectValue />
+            </SelectTrigger>
+          </Select>
+          <Button type="submit">Save runtimes</Button>
+          <Button type="reset">Reset runtimes</Button>
+          <output aria-label="Saved runtimes">{result}</output>
+        </FieldGroup>
+      </form>);
+    }
+}
+```
+
+### CancelledOpening
+
+```tsx
+{
+    args: { onOpenChange: fn((_open: boolean, details: SelectRootChangeEventDetails) => details.cancel()) }
+}
+```
+
+### ControlledOpening
+
+```tsx
+{
+    render: function Render() {
+        const [isOpen, setIsOpen] = useState(false);
+        return (<Field>
+        <Button onClick={() => setIsOpen(true)}>Open runtime choices</Button>
+        <Select open={isOpen} onOpenChange={setIsOpen} items={fixture_runtimes}>
+          <SelectTrigger aria-label="Controlled popup">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent alignItemWithTrigger={false}>
+            <SelectGroup>
+              {fixture_runtimes.map((item) => (<SelectItem key={item.value ?? "placeholder"} value={item.value}>
+                  {item.label}
+                </SelectItem>))}
+            </SelectGroup>
+          </SelectContent>
+        </Select>
+        <output aria-label="Popup state">{String(isOpen)}</output>
+      </Field>);
+    }
+}
+```
+
+### Grouped
+
+```tsx
+{
+    render: (args) => (<Select {...args}>
+      <SelectTrigger aria-label="Runtime">
+        <SelectValue />
+      </SelectTrigger>
+      <SelectContent alignItemWithTrigger={false}>
+        <SelectGroup>
+          <SelectLabel>Primary runtimes</SelectLabel>
+          <SelectItem value="bun">Bun</SelectItem>
+          <SelectItem value="node">Node.js</SelectItem>
+        </SelectGroup>
+        <SelectSeparator />
+        <SelectGroup>
+          <SelectLabel>Alternative runtimes</SelectLabel>
+          <SelectItem value="deno">Deno</SelectItem>
+        </SelectGroup>
+      </SelectContent>
+    </Select>)
+}
+```
+
+### AlignedItem
+
+```tsx
+{
+    args: { defaultValue: "node", triggerClassName: "w-64" },
+    decorators: [
+        (Story) => (<div className="py-40">
+        <Story />
+      </div>),
+    ]
+}
+```
+
+### RightToLeftAlignedItem
+
+```tsx
+{
+    args: { defaultValue: "node", triggerClassName: "w-64" },
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <div dir="rtl" className="py-40">
+          <Story />
+        </div>
+      </DirectionProvider>),
+    ]
+}
+```
+
+### EdgeAligned
+
+```tsx
+{
+    args: { defaultValue: "node" },
+    decorators: AlignedItem.decorators,
+    render: (args) => (<Select {...args}>
+      <SelectTrigger aria-label="Runtime">
+        <SelectValue />
+      </SelectTrigger>
+      <SelectContent alignItemWithTrigger={false}>
+        <SelectGroup>
+          {fixture_runtimes.map((item) => (<SelectItem key={item.value ?? "placeholder"} value={item.value}>
+              {item.label}
+            </SelectItem>))}
+        </SelectGroup>
+      </SelectContent>
+    </Select>)
+}
+```
+
+### RightToLeftInvalid
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        return (<Field data-invalid>
+        <FieldLabel htmlFor={id}>Runtime</FieldLabel>
+        <Select {...args}>
+          <SelectTrigger id={id} aria-invalid aria-describedby={`${id}-error`} aria-errormessage={`${id}-error`}>
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectGroup>
+              {fixture_runtimes
+                .filter((item) => !args.multiple || item.value !== null)
+                .map((item) => (<SelectItem key={item.value ?? "placeholder"} value={item.value}>
+                    {item.label}
+                  </SelectItem>))}
+            </SelectGroup>
+          </SelectContent>
+        </Select>
+        <FieldError id={`${id}-error`}>Choose a runtime.</FieldError>
+      </Field>);
+    },
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <div dir="rtl">
+          <Story />
+        </div>
+      </DirectionProvider>),
+    ]
+}
+```

package/llms/components/forms/SettingsSection.md

@@ -0,0 +1,65 @@
+# SettingsSection
+
+Story: @alexgorbatchev/shadcn/components/forms/SettingsSection
+Source: src/components/stories/forms/SettingsSection.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/forms/SettingsSection.stories.tsx)
+
+## Public imports
+
+```tsx
+import { SettingsSection, Field, FieldLabel, Input } from "@alexgorbatchev/shadcn";
+```
+
+## Default component
+
+```tsx
+SettingsSection
+```
+
+## Default args
+
+```tsx
+{
+    title: "Profile settings",
+    description: "Keep your details up to date.",
+    onSubmit: fn((event) => event.preventDefault()),
+    footer: "Changes apply to this workspace.",
+    children: (<Field>
+        <FieldLabel htmlFor="profile-name">Display name</FieldLabel>
+        <Input id="profile-name" name="displayName" required defaultValue="Alex"/>
+      </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
+{}
+```
+
+### Saving
+
+```tsx
+{
+    args: { pending: true }
+}
+```
+
+### Destructive
+
+```tsx
+{
+    args: {
+        title: "Delete workspace",
+        description: undefined,
+        destructive: true,
+        saveLabel: "Delete workspace",
+        children: "This action permanently removes the workspace.",
+    }
+}
+```