@neynar/ui 1.0.1 → 1.0.3

package/llm/components/progress.llm.md

@@ -0,0 +1,259 @@
+# Progress
+
+Progress bar for displaying task completion, loading states, and quota usage.
+
+## Import
+
+```tsx
+import {
+  Progress,
+  ProgressTrack,
+  ProgressIndicator,
+  ProgressLabel,
+  ProgressValue,
+} from "@neynar/ui/progress"
+```
+
+## Anatomy
+
+```tsx
+<Progress value={65}>
+  <ProgressLabel>Loading</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack>
+    <ProgressIndicator />
+  </ProgressTrack>
+</Progress>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| Progress | Root container managing progress state and rendering |
+| ProgressLabel | Text label describing the task |
+| ProgressValue | Formatted percentage display (auto-positioned right) |
+| ProgressTrack | Container for the progress bar track |
+| ProgressIndicator | Visual bar showing completion (auto-width based on value) |
+
+## Props
+
+### Progress
+
+Root component providing progress state context to all children.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | number \| null | - | Progress value 0-100, or null for indeterminate |
+| min | number | 0 | Minimum value |
+| max | number | 100 | Maximum value |
+| aria-valuetext | string | - | Custom accessible label for current value |
+| getAriaValueText | (formatted: string \| null, value: number \| null) => string | - | Function to generate accessible label |
+| locale | Intl.LocalesArgument | - | Locale for number formatting |
+| format | Intl.NumberFormatOptions | - | Options for value formatting |
+| className | string | - | Additional CSS classes |
+
+### ProgressTrack
+
+Container for the progress indicator. Customize height via className.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Override default styles (default: `h-1.5`) |
+
+**Default styles**: `bg-muted h-1.5 rounded-full relative flex w-full items-center overflow-x-hidden`
+
+### ProgressIndicator
+
+Visual bar showing task completion. Width automatically adjusts based on parent Progress value.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Override colors/animation (default: `bg-primary`) |
+
+**Default styles**: `bg-primary h-full transition-all`
+
+Color customization examples:
+- Success: `bg-green-500 dark:bg-green-400`
+- Warning: `bg-yellow-500 dark:bg-yellow-400`
+- Danger: `bg-red-500 dark:bg-red-400`
+
+### ProgressLabel
+
+Text label for the progress task.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional CSS classes |
+| children | ReactNode | - | Label text |
+
+**Default styles**: `text-sm font-medium`
+
+### ProgressValue
+
+Displays formatted progress value (e.g., "65%").
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional CSS classes |
+| children | (formatted: string \| null, value: number \| null) => ReactNode | - | Custom formatter function |
+
+**Default styles**: `text-muted-foreground ml-auto text-sm tabular-nums`
+
+## Data Attributes
+
+All components share these data attributes for styling:
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-progressing | Value is between min and max |
+| data-complete | Value equals max (100 by default) |
+| data-indeterminate | Value is null (unknown duration) |
+
+## Examples
+
+### Basic Progress
+
+```tsx
+<Progress value={65}>
+  <ProgressLabel>Loading</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack>
+    <ProgressIndicator />
+  </ProgressTrack>
+</Progress>
+```
+
+### Minimal (No Label/Value)
+
+```tsx
+<Progress value={45}>
+  <ProgressTrack>
+    <ProgressIndicator />
+  </ProgressTrack>
+</Progress>
+```
+
+### Semantic Colors for States
+
+```tsx
+// Success state (healthy usage)
+<Progress value={45}>
+  <ProgressLabel>API Usage</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack>
+    <ProgressIndicator className="bg-green-500 dark:bg-green-400" />
+  </ProgressTrack>
+</Progress>
+
+// Warning state (approaching limit)
+<Progress value={78}>
+  <ProgressLabel>Rate Limit</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack>
+    <ProgressIndicator className="bg-yellow-500 dark:bg-yellow-400" />
+  </ProgressTrack>
+</Progress>
+
+// Critical state
+<Progress value={94}>
+  <ProgressLabel>Storage</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack>
+    <ProgressIndicator className="bg-red-500 dark:bg-red-400" />
+  </ProgressTrack>
+</Progress>
+```
+
+### Size Variants
+
+```tsx
+// Small
+<Progress value={65}>
+  <ProgressLabel>Small</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack className="h-1">
+    <ProgressIndicator />
+  </ProgressTrack>
+</Progress>
+
+// Default
+<Progress value={65}>
+  <ProgressLabel>Default</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack className="h-1.5">
+    <ProgressIndicator />
+  </ProgressTrack>
+</Progress>
+
+// Large
+<Progress value={65}>
+  <ProgressLabel>Large</ProgressLabel>
+  <ProgressValue />
+  <ProgressTrack className="h-3">
+    <ProgressIndicator />
+  </ProgressTrack>
+</Progress>
+```
+
+### Indeterminate State
+
+For tasks with unknown duration:
+
+```tsx
+<Progress value={null}>
+  <ProgressLabel>Processing...</ProgressLabel>
+  <ProgressTrack>
+    <ProgressIndicator className="w-1/3 animate-pulse" />
+  </ProgressTrack>
+</Progress>
+```
+
+### API Usage Dashboard Context
+
+```tsx
+<div className="border-border bg-card rounded-lg border p-5">
+  <div className="mb-4 flex items-start justify-between">
+    <div className="flex items-center gap-3">
+      <div className="bg-primary/10 text-primary rounded-md p-2">
+        <ActivityIcon className="size-5" />
+      </div>
+      <div>
+        <p className="font-medium">Monthly API Calls</p>
+        <p className="text-muted-foreground text-sm">
+          Standard Plan: 1M requests/month
+        </p>
+      </div>
+    </div>
+    <span className="rounded-full bg-green-500/10 px-2.5 py-1 text-xs font-medium text-green-600">
+      Healthy
+    </span>
+  </div>
+
+  <Progress value={45}>
+    <ProgressLabel>API Requests</ProgressLabel>
+    <ProgressValue />
+    <ProgressTrack>
+      <ProgressIndicator className="bg-green-500 dark:bg-green-400" />
+    </ProgressTrack>
+  </Progress>
+
+  <p className="text-muted-foreground mt-2 text-sm">
+    450,000 of 1,000,000 requests used
+  </p>
+</div>
+```
+
+## Accessibility
+
+- Uses `role="progressbar"` with proper ARIA attributes
+- Announces progress value and label to screen readers
+- Supports `aria-valuetext` for custom accessible labels
+- `getAriaValueText` prop allows dynamic accessible descriptions
+- Indeterminate state properly announced when `value={null}`
+
+## Related
+
+- **Skeleton** - Loading placeholders for content
+- **Spinner** - Circular loading indicator
+- **Badge** - Status indicators with semantic colors

package/llm/components/radio-group.llm.md

@@ -0,0 +1,269 @@
+# RadioGroup
+
+Mutually exclusive selection from a group of options.
+
+## Import
+
+```tsx
+import { RadioGroup, RadioGroupItem } from "@neynar/ui/radio-group"
+```
+
+## Anatomy
+
+```tsx
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroupItem value="option-1" id="option-1" />
+  <RadioGroupItem value="option-2" id="option-2" />
+</RadioGroup>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| RadioGroup | Container that manages state for radio items |
+| RadioGroupItem | Individual radio button with automatic indicator |
+
+## Props
+
+### RadioGroup
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | unknown | - | Controlled selected value |
+| onValueChange | (value: unknown) => void | - | Called when selection changes |
+| defaultValue | unknown | - | Uncontrolled initial value |
+| name | string | - | Form field name for submission |
+| disabled | boolean | false | Disable all radio items |
+| readOnly | boolean | false | Prevent selection changes |
+| required | boolean | false | Mark as required for forms |
+| inputRef | Ref\<HTMLInputElement\> | - | Ref to hidden input element |
+| className | string | - | Additional CSS classes |
+
+### RadioGroupItem
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | string | - | Value for this radio option |
+| id | string | - | HTML id for label association |
+| disabled | boolean | false | Disable this specific item |
+| aria-invalid | boolean | - | Mark as invalid (error state) |
+| className | string | - | Additional CSS classes |
+
+The RadioGroupItem automatically renders a checked indicator (filled circle) when selected.
+
+## Data Attributes
+
+### RadioGroup
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-disabled | Group is disabled |
+
+### RadioGroupItem
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-checked | Item is selected |
+| data-unchecked | Item is not selected |
+| data-disabled | Item is disabled |
+
+## Examples
+
+### Basic Usage
+
+```tsx
+function NotificationPreferences() {
+  const [method, setMethod] = useState("email")
+
+  return (
+    <RadioGroup value={method} onValueChange={(v) => setMethod(v as string)}>
+      <div className="flex items-center space-x-2">
+        <RadioGroupItem value="email" id="email" />
+        <Label htmlFor="email">Email</Label>
+      </div>
+      <div className="flex items-center space-x-2">
+        <RadioGroupItem value="sms" id="sms" />
+        <Label htmlFor="sms">SMS</Label>
+      </div>
+      <div className="flex items-center space-x-2">
+        <RadioGroupItem value="push" id="push" />
+        <Label htmlFor="push">Push Notifications</Label>
+      </div>
+    </RadioGroup>
+  )
+}
+```
+
+### Uncontrolled with Default Value
+
+```tsx
+<RadioGroup defaultValue="standard" name="shipping">
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="standard" id="standard" />
+    <Label htmlFor="standard">Standard Shipping</Label>
+  </div>
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="express" id="express" />
+    <Label htmlFor="express">Express Shipping</Label>
+  </div>
+</RadioGroup>
+```
+
+### With Descriptions
+
+```tsx
+<RadioGroup defaultValue="mainnet">
+  <div className="flex items-start space-x-3">
+    <RadioGroupItem value="mainnet" id="mainnet" className="mt-0.5" />
+    <div className="flex-1">
+      <Label htmlFor="mainnet" className="font-medium">Mainnet</Label>
+      <p className="text-muted-foreground text-sm">
+        Production-ready network with real users and data.
+      </p>
+    </div>
+  </div>
+  <div className="flex items-start space-x-3">
+    <RadioGroupItem value="testnet" id="testnet" className="mt-0.5" />
+    <div className="flex-1">
+      <Label htmlFor="testnet" className="font-medium">Testnet</Label>
+      <p className="text-muted-foreground text-sm">
+        Testing environment for development.
+      </p>
+    </div>
+  </div>
+</RadioGroup>
+```
+
+### Error State
+
+```tsx
+function FormField() {
+  const [value, setValue] = useState("")
+  const [showError, setShowError] = useState(false)
+
+  return (
+    <div className="space-y-2">
+      <RadioGroup
+        value={value}
+        onValueChange={(v) => {
+          setValue(v as string)
+          setShowError(false)
+        }}
+        aria-invalid={showError}
+      >
+        <div className="flex items-center space-x-2">
+          <RadioGroupItem value="yes" id="yes" aria-invalid={showError} />
+          <Label htmlFor="yes">Yes</Label>
+        </div>
+        <div className="flex items-center space-x-2">
+          <RadioGroupItem value="no" id="no" aria-invalid={showError} />
+          <Label htmlFor="no">No</Label>
+        </div>
+      </RadioGroup>
+      {showError && (
+        <p className="text-destructive text-sm">Please make a selection.</p>
+      )}
+    </div>
+  )
+}
+```
+
+### Disabled Group
+
+```tsx
+<RadioGroup disabled defaultValue="option-1">
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="option-1" id="option-1" />
+    <Label htmlFor="option-1">Option 1</Label>
+  </div>
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="option-2" id="option-2" />
+    <Label htmlFor="option-2">Option 2</Label>
+  </div>
+</RadioGroup>
+```
+
+### Individual Disabled Items
+
+```tsx
+<RadioGroup defaultValue="available-1">
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="available-1" id="available-1" />
+    <Label htmlFor="available-1">Available Option</Label>
+  </div>
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="sold-out" id="sold-out" disabled />
+    <Label htmlFor="sold-out">Sold Out</Label>
+  </div>
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="available-2" id="available-2" />
+    <Label htmlFor="available-2">Another Available</Label>
+  </div>
+</RadioGroup>
+```
+
+### Card-Based Layout
+
+```tsx
+<RadioGroup defaultValue="pro">
+  <div className="grid gap-4 sm:grid-cols-3">
+    <label
+      htmlFor="free"
+      className="hover:border-primary/50 border-border flex cursor-pointer flex-col gap-3 rounded-lg border p-4"
+    >
+      <RadioGroupItem value="free" id="free" />
+      <div>
+        <p className="font-semibold">Free Plan</p>
+        <p className="text-muted-foreground text-sm">Perfect for testing</p>
+      </div>
+    </label>
+
+    <label
+      htmlFor="pro"
+      className="hover:border-primary/50 border-primary border-2 flex cursor-pointer flex-col gap-3 rounded-lg p-4"
+    >
+      <RadioGroupItem value="pro" id="pro" />
+      <div>
+        <p className="font-semibold">Pro Plan</p>
+        <p className="text-muted-foreground text-sm">For production apps</p>
+      </div>
+    </label>
+
+    <label
+      htmlFor="enterprise"
+      className="hover:border-primary/50 border-border flex cursor-pointer flex-col gap-3 rounded-lg border p-4"
+    >
+      <RadioGroupItem value="enterprise" id="enterprise" />
+      <div>
+        <p className="font-semibold">Enterprise</p>
+        <p className="text-muted-foreground text-sm">Custom solutions</p>
+      </div>
+    </label>
+  </div>
+</RadioGroup>
+```
+
+## Keyboard
+
+| Key | Action |
+|-----|--------|
+| Tab | Focus next radio item |
+| Shift+Tab | Focus previous radio item |
+| Space | Select focused item |
+| Arrow Down/Right | Select next item |
+| Arrow Up/Left | Select previous item |
+
+## Accessibility
+
+- Each RadioGroupItem should have a unique `id` and paired `<Label htmlFor={id}>`
+- Uses `role="radiogroup"` and `role="radio"` with proper ARIA attributes
+- Manages focus with roving tabindex for keyboard navigation
+- Error states use `aria-invalid` for screen reader announcements
+- Disabled state prevents interaction and is announced to assistive technologies
+
+## Related
+
+- [Label](./label.llm.md) - For labeling radio items
+- [Checkbox](./checkbox.llm.md) - For multi-select options
+- [Select](./select.llm.md) - For dropdown selections