@neynar/ui 0.3.0 → 0.3.1

package/.llm/text-field.llm.md

@@ -0,0 +1,327 @@
+# TextField
+
+**Type**: component
+
+TextField - Complete form field with label, input, and descriptive text A comprehensive form field component that combines Input and Label components with additional helper text and error handling capabilities. Automatically manages accessibility attributes, ID generation, and ARIA relationships to ensure forms are usable by all users including those using assistive technologies. Built on top of the Input and Label primitives, TextField provides a complete form field solution with consistent styling, proper semantic markup, and enhanced UX features. Supports all HTML input types while adding form validation states, descriptive text, and automatic accessibility compliance.
+
+## JSX Usage
+
+```jsx
+import { TextField } from '@neynar/ui';
+
+<TextField
+  label="value"
+  helperText="value"
+  error="value"
+  required={true}
+  id="value"
+  type={value}
+  placeholder="value"
+  value={value}
+  defaultValue={value}
+  disabled={true}
+  readOnly={true}
+  name="value"
+  autoComplete="value"
+  autoFocus={true}
+  maxLength={0}
+  minLength={0}
+  pattern="value"
+  min={value}
+  max={value}
+  step={value}
+  onChange={handleChange}
+  onFocus={handleFocus}
+  onBlur={handleBlur}
+  onKeyDown={handleKeyDown}
+  onKeyUp={handleKeyUp}
+  className="value"
+/>
+```
+
+## Component Props
+
+### label
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### helperText
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### error
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### required
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### id
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### type
+- **Type**: `React.HTMLInputTypeAttribute`
+- **Required**: No
+- **Description**: No description available
+
+### placeholder
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### value
+- **Type**: `string | ReadonlyArray<string> | number`
+- **Required**: No
+- **Description**: No description available
+
+### defaultValue
+- **Type**: `string | ReadonlyArray<string> | number`
+- **Required**: No
+- **Description**: No description available
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### readOnly
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### name
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### autoComplete
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### autoFocus
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### maxLength
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### minLength
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### pattern
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### min
+- **Type**: `string | number`
+- **Required**: No
+- **Description**: No description available
+
+### max
+- **Type**: `string | number`
+- **Required**: No
+- **Description**: No description available
+
+### step
+- **Type**: `string | number`
+- **Required**: No
+- **Description**: No description available
+
+### onChange
+- **Type**: `(event: React.ChangeEvent<HTMLInputElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### onFocus
+- **Type**: `(event: React.FocusEvent<HTMLInputElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### onBlur
+- **Type**: `(event: React.FocusEvent<HTMLInputElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### onKeyDown
+- **Type**: `(event: React.KeyboardEvent<HTMLInputElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### onKeyUp
+- **Type**: `(event: React.KeyboardEvent<HTMLInputElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic text input with label
+<TextField
+  label="Email Address"
+  type="email"
+  placeholder="Enter your email"
+  name="email"
+/>
+```
+### Example 2
+```tsx
+// Required field with helper text
+<TextField
+  label="Username"
+  placeholder="
+### Example 3
+```tsx
+// Password field with validation error
+<TextField
+  label="Password"
+  type="password"
+  required
+  error="Password must be at least 8 characters long"
+  value={password}
+  onChange={(e) => setPassword(e.target.value)}
+  minLength={8}
+  autoComplete="new-password"
+/>
+```
+### Example 4
+```tsx
+// Controlled component with real-time validation
+const [email, setEmail] = useState("");
+const [error, setError] = useState("");
+const validateEmail = (value: string) => {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  if (!emailRegex.test(value)) {
+    setError("Please enter a valid email address");
+  } else {
+    setError("");
+  }
+};
+<TextField
+  label="Email"
+  type="email"
+  value={email}
+  onChange={(e) => {
+    setEmail(e.target.value);
+    validateEmail(e.target.value);
+  }}
+  onBlur={(e) => validateEmail(e.target.value)}
+  error={error}
+  required
+  autoComplete="email"
+/>
+```
+### Example 5
+```tsx
+// Number input with constraints
+<TextField
+  label="Age"
+  type="number"
+  min={0}
+  max={120}
+  step={1}
+  helperText="Enter your age in years"
+  placeholder="25"
+/>
+```
+### Example 6
+```tsx
+// Search input with custom styling
+<TextField
+  label="Search"
+  type="search"
+  placeholder="Search products..."
+  className="max-w-md"
+  onKeyDown={(e) => {
+    if (e.key === 'Enter') {
+      handleSearch(e.currentTarget.value);
+    }
+  }}
+/>
+```
+### Example 7
+```tsx
+// Form integration with React Hook Form
+const { register, formState: { errors } } = useForm();
+<form onSubmit={handleSubmit(onSubmit)}>
+  <TextField
+    label="Full Name"
+    {...register("fullName", { required: "Full name is required" })}
+    error={errors.fullName?.message}
+    helperText="Enter your first and last name"
+  />
+  <TextField
+    label="Phone Number"
+    type="tel"
+    {...register("phone", {
+      pattern: {
+        value: /^[\+]?[1-9][\d]{0,15}$/,
+        message: "Please enter a valid phone number"
+      }
+    })}
+    error={errors.phone?.message}
+    autoComplete="tel"
+  />
+</form>
+```
+### Example 8
+```tsx
+// File input with custom validation
+<TextField
+  label="Profile Picture"
+  type="file"
+  accept="image/*"
+  helperText="Upload a PNG, JPG or GIF (max 5MB)"
+  onChange={(e) => {
+    const file = e.target.files?.[0];
+    if (file && file.size > 5 * 1024 * 1024) {
+      setError("File size must be less than 5MB");
+    } else {
+      setError("");
+      handleFileUpload(file);
+    }
+  }}
+  error={fileError}
+/>
+```
+### Example 9
+```tsx
+// Date input with range constraints
+<TextField
+  label="Birth Date"
+  type="date"
+  min="1900-01-01"
+  max={new Date().toISOString().split('T')[0]}
+  helperText="You must be 18 or older to register"
+  required
+/>
+```
+### Example 10
+```tsx
+// Disabled field with explanation
+<TextField
+  label="Account ID"
+  value="ACC-12345"
+  disabled
+  helperText="This value is automatically generated and cannot be changed"
+/>
+```

package/.llm/textarea.llm.md

@@ -0,0 +1,311 @@
+# Textarea
+
+**Type**: component
+
+Textarea - Multi-line text input control for extended content entry A styled textarea component built on the native HTML textarea element for entering longer pieces of text that span multiple lines, such as comments, descriptions, messages, or any content that requires multiple lines of input. Features automatic content-based resizing using CSS field-sizing when supported by the browser. Built following shadcn/ui design patterns with consistent styling and behavior across form elements. Inherits all native HTML textarea functionality while providing enhanced visual design and better accessibility patterns.
+
+## JSX Usage
+
+```jsx
+import { Textarea } from '@neynar/ui';
+
+<Textarea
+  className="value"
+  placeholder="value"
+  disabled={true}
+  readOnly={true}
+  rows={0}
+  cols={0}
+  maxLength={0}
+  minLength={0}
+  required={true}
+  form="value"
+  name="value"
+  id="value"
+  value="value"
+  defaultValue="value"
+  wrap={value}
+  autoFocus={true}
+  autoComplete="value"
+  autoCapitalize={value}
+  spellCheck={true}
+  onChange={handleChange}
+  onFocus={handleFocus}
+  onBlur={handleBlur}
+  onKeyDown={handleKeyDown}
+  onKeyUp={handleKeyUp}
+  onKeyPress={handleKeyPress}
+  "aria-invalid"={value}
+  "aria-describedby"="value"
+  "aria-labelledby"="value"
+  "aria-label"="value"
+  tabIndex={0}
+  style={value}
+/>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### placeholder
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### readOnly
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### rows
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### cols
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### maxLength
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### minLength
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### required
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### form
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### name
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### id
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### value
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### defaultValue
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### wrap
+- **Type**: `"soft" | "hard" | "off"`
+- **Required**: No
+- **Description**: No description available
+
+### autoFocus
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### autoComplete
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### autoCapitalize
+- **Type**: `"none" | "sentences" | "words" | "characters"`
+- **Required**: No
+- **Description**: No description available
+
+### spellCheck
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### onChange
+- **Type**: `(event: React.ChangeEvent<HTMLTextAreaElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### onFocus
+- **Type**: `(event: React.FocusEvent<HTMLTextAreaElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### onBlur
+- **Type**: `(event: React.FocusEvent<HTMLTextAreaElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### onKeyDown
+- **Type**: `(event: React.KeyboardEvent<HTMLTextAreaElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### onKeyUp
+- **Type**: `(event: React.KeyboardEvent<HTMLTextAreaElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### onKeyPress
+- **Type**: `(event: React.KeyboardEvent<HTMLTextAreaElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-invalid"
+- **Type**: `boolean | "false" | "true" | "grammar" | "spelling"`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-describedby"
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-labelledby"
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-label"
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### tabIndex
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### style
+- **Type**: `React.CSSProperties & {
+    resize?: "none" | "both" | "horizontal" | "vertical";
+  }`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic usage
+<Textarea placeholder="Type your message here..." />
+```
+### Example 2
+```tsx
+// With label and validation
+<div className="space-y-2">
+  <Label htmlFor="description">Description</Label>
+  <Textarea
+    id="description"
+    placeholder="Enter a description..."
+    rows={4}
+    required
+  />
+</div>
+```
+### Example 3
+```tsx
+// Controlled with character limit and validation
+const [bio, setBio] = useState("");
+const [error, setError] = useState("");
+const maxLength = 160;
+<div className="space-y-2">
+  <Label htmlFor="bio">Bio</Label>
+  <Textarea
+    id="bio"
+    value={bio}
+    onChange={(e) => {
+      setBio(e.target.value);
+      if (e.target.value.length > maxLength) {
+        setError("Bio is too long");
+      } else {
+        setError("");
+      }
+    }}
+    placeholder="Tell us about yourself..."
+    maxLength={maxLength}
+    aria-invalid={!!error}
+    aria-describedby={error ? "bio-error" : "bio-count"}
+  />
+  <div className="flex justify-between items-center">
+    <p id="bio-count" className="text-sm text-muted-foreground">
+      {bio.length}/{maxLength} characters
+    </p>
+    {error && (
+      <p id="bio-error" className="text-sm text-destructive">
+        {error}
+      </p>
+    )}
+  </div>
+</div>
+```
+### Example 4
+```tsx
+// Auto-resizing with minimum height
+<Textarea
+  placeholder="This textarea grows with content"
+  className="min-h-[100px] max-h-[300px]"
+  style={{ resize: "vertical" }}
+/>
+```
+### Example 5
+```tsx
+// Form integration with validation
+<form onSubmit={handleSubmit}>
+  <div className="space-y-2">
+    <Label htmlFor="feedback">Feedback</Label>
+    <Textarea
+      id="feedback"
+      name="feedback"
+      placeholder="Share your thoughts..."
+      required
+      minLength={10}
+      maxLength={500}
+      rows={3}
+    />
+  </div>
+  <Button type="submit">Submit Feedback</Button>
+</form>
+```
+### Example 6
+```tsx
+// Different wrap behaviors for code/text
+<div className="space-y-4">
+  <div>
+    <Label>Code (no wrapping)</Label>
+    <Textarea
+      wrap="off"
+      placeholder="Enter code here..."
+      className="font-mono text-sm"
+      style={{ resize: "both" }}
+    />
+  </div>
+  <div>
+    <Label>Text (soft wrapping)</Label>
+    <Textarea
+      wrap="soft"
+      placeholder="Enter text content..."
+    />
+  </div>
+</div>
+```

package/.llm/theme-preference.llm.md

@@ -0,0 +1,25 @@
+# ThemePreference
+
+**Type**: type
+
+Theme preference options for the theme system Controls how the application determines the active theme: - `"system"` - Automatically follows the user's OS preference - `"light"` - Forces light theme regardless of system preference - `"dark"` - Forces dark theme regardless of system preference
+
+## Type Definition
+
+```typescript
+import { ThemePreference } from '@neynar/ui';
+
+type ThemePreference = "system" | "light" | "dark"
+```
+
+## Examples
+
+```tsx
+const { preference, setPreference } = useTheme();
+
+// Switch to dark mode
+setPreference("dark");
+
+// Follow system preference
+setPreference("system");
+```

package/.llm/theme-toggle.llm.md

@@ -0,0 +1,57 @@
+# ThemeToggle
+
+**Type**: component
+
+ThemeToggle - A zero-configuration theme switcher with system, light, and dark modes A completely self-contained theme toggle component that provides an intuitive dropdown interface for switching between system preference, light mode, and dark mode. Works immediately without any provider setup, context configuration, or additional dependencies. Built on top of shadcn/ui components (Button + DropdownMenu) with the Neynar useTheme hook for state management. Handles theme persistence via cookies, system preference detection, real-time system changes, and synchronization across multiple instances. **Zero Configuration Design:** Just import and use - no providers, no setup, no configuration required. The component handles all theme management internally and provides a complete solution out of the box. **Perfect for:** - Application headers and navigation bars - Settings panels and preference screens - Toolbars and floating action areas - Any location where users need quick theme access
+
+## JSX Usage
+
+```jsx
+import { ThemeToggle } from '@neynar/ui';
+
+<ThemeToggle
+  variant={value}
+  size={value}
+  className="value"
+  showLabel={true}
+  align={value}
+  asChild={true}
+/>
+```
+
+## Component Props
+
+### variant
+- **Type**: `| "default"
+    | "destructive"
+    | "outline"
+    | "secondary"
+    | "ghost"
+    | "link"`
+- **Required**: No
+- **Description**: Visual style variant inherited from Button component (default: "outline")
+
+### size
+- **Type**: `"default" | "sm" | "lg" | "icon"`
+- **Required**: No
+- **Description**: Size variant inherited from Button component (default: "icon")
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for custom styling
+
+### showLabel
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Whether to show theme name text (auto-enabled for non-icon sizes)
+
+### align
+- **Type**: `"start" | "center" | "end"`
+- **Required**: No
+- **Description**: Dropdown menu alignment relative to trigger button (default: "end")
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available