feat: form components

apps/www/package.json

@@ -29,6 +29,7 @@
     "prettier": "^2.8.8",
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
+    "react-hook-form": "^7.72.1",
     "react-live": "^4.1.8",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.1",

apps/www/src/app/examples/page.tsx

@@ -186,8 +186,6 @@ const Page = () => {
                 placeholder='Default large search'
                 showClearButton
                 value={search1}
-                label='Search'
-                helperText='This is a helper text'
                 onChange={(e: React.ChangeEvent<HTMLInputElement>) =>
                   setSearch1(e.target.value)
                 }
@@ -1335,7 +1333,6 @@ const Page = () => {
                 variant='borderless'
                 showClearButton
                 value={search3}
-                label='Search'
                 onChange={(e: React.ChangeEvent<HTMLInputElement>) =>
                   setSearch3(e.target.value)
                 }
@@ -1582,7 +1579,6 @@ const Page = () => {
                           </Popover.Content>
                         </Popover>
                         <InputField
-                          label='Filter Team Members'
                           placeholder='Type to filter...'
                           leadingIcon={<FilterIcon />}
                           width='100%'
@@ -1639,7 +1635,6 @@ const Page = () => {
                     </Flex>
 
                     <TextArea
-                      label='Example Text Area'
                       value={inputValue}
                       onChange={e => setInputValue(e.target.value)}
                     />
@@ -1753,7 +1748,6 @@ const Page = () => {
                           </Popover.Content>
                         </Popover>
                         <InputField
-                          label='Filter Team Members'
                           placeholder='Type to filter...'
                           leadingIcon={<FilterIcon />}
                           width='100%'

apps/www/src/components/playground/field-examples.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { Field, Flex, InputField, TextArea } from '@raystack/apsara';
+import PlaygroundLayout from './playground-layout';
+
+export function FieldExamples() {
+  return (
+    <PlaygroundLayout title='Field'>
+      <Flex gap='large' wrap='wrap'>
+        <Flex gap='large' direction='column' style={{ width: 300 }}>
+          <Field label='Name' required description='Enter your full name'>
+            <InputField placeholder='John Doe' />
+          </Field>
+          <Field label='Email' error='Please enter a valid email'>
+            <InputField type='email' placeholder='Enter email' />
+          </Field>
+          <Field label='Phone' required={false}>
+            <InputField placeholder='Enter phone' />
+          </Field>
+        </Flex>
+        <Flex gap='large' direction='column' style={{ width: 300 }}>
+          <Field
+            label='Bio'
+            required={false}
+            description='Tell us about yourself'
+          >
+            <TextArea placeholder='Write something...' />
+          </Field>
+          <Field label='Disabled' disabled>
+            <InputField placeholder='Cannot edit' />
+          </Field>
+        </Flex>
+      </Flex>
+    </PlaygroundLayout>
+  );
+}

apps/www/src/components/playground/fieldset-examples.tsx

@@ -0,0 +1,26 @@
+'use client';
+
+import { Field, Fieldset, Flex, InputField } from '@raystack/apsara';
+import PlaygroundLayout from './playground-layout';
+
+export function FieldsetExamples() {
+  return (
+    <PlaygroundLayout title='Fieldset'>
+      <Flex gap='large' direction='column' style={{ maxWidth: 400 }}>
+        <Fieldset legend='Contact Details'>
+          <Field label='Phone' required>
+            <InputField type='tel' placeholder='+1 (555) 000-0000' />
+          </Field>
+          <Field label='Address' required={false}>
+            <InputField placeholder='123 Main St' />
+          </Field>
+        </Fieldset>
+        <Fieldset legend='Disabled Section' disabled>
+          <Field label='Read Only'>
+            <InputField placeholder='Cannot edit' />
+          </Field>
+        </Fieldset>
+      </Flex>
+    </PlaygroundLayout>
+  );
+}

apps/www/src/components/playground/form-examples.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+import {
+  Button,
+  Field,
+  Fieldset,
+  Form,
+  InputField,
+  TextArea
+} from '@raystack/apsara';
+import PlaygroundLayout from './playground-layout';
+
+export function FormExamples() {
+  return (
+    <PlaygroundLayout title='Form'>
+      <Form
+        onSubmit={e => {
+          e.preventDefault();
+          alert('Form submitted!');
+        }}
+        style={{ maxWidth: 400 }}
+      >
+        <Fieldset legend='Personal Information'>
+          <Field label='First Name' required>
+            <InputField placeholder='John' />
+          </Field>
+          <Field label='Last Name' required>
+            <InputField placeholder='Doe' />
+          </Field>
+        </Fieldset>
+        <Field label='Email' required description="We'll send a confirmation">
+          <InputField type='email' placeholder='john@example.com' />
+        </Field>
+        <Field label='Message' required={false}>
+          <TextArea placeholder='Tell us more...' />
+        </Field>
+        <Button type='submit'>Submit</Button>
+      </Form>
+    </PlaygroundLayout>
+  );
+}

apps/www/src/components/playground/index.ts

@@ -19,8 +19,11 @@ export * from './data-table-examples';
 export * from './dialog-examples';
 export * from './drawer-examples';
 export * from './empty-state-examples';
+export * from './field-examples';
+export * from './fieldset-examples';
 export * from './filter-chip-examples';
 export * from './flex-examples';
+export * from './form-examples';
 export * from './headline-examples';
 export * from './icon-button-examples';
 export * from './image-examples';

apps/www/src/components/playground/input-field-examples.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { Flex, InputField } from '@raystack/apsara';
+import { Field, Flex, InputField } from '@raystack/apsara';
 import { Home, Info } from 'lucide-react';
 import PlaygroundLayout from './playground-layout';
 
@@ -9,32 +9,24 @@ export function InputFieldExamples() {
     <PlaygroundLayout title='InputField'>
       <Flex gap='large' wrap='wrap'>
         <Flex gap='large' direction='column' style={{ width: 300 }}>
-          <InputField label='Default' placeholder='Enter text' />
-          <InputField
-            label='With label'
-            placeholder='Enter text'
-            helperText='This is a helper text'
-          />
-          <InputField
-            label='With Error'
-            placeholder='Enter text'
-            error='This field is required'
-          />
+          <Field label='Default'>
+            <InputField placeholder='Enter text' />
+          </Field>
+          <Field label='With Description' description='This is a description'>
+            <InputField placeholder='Enter text' />
+          </Field>
+          <Field label='With Error' error='This field is required'>
+            <InputField placeholder='Enter text' />
+          </Field>
         </Flex>
         <Flex gap='large' direction='column' style={{ width: 300 }}>
+          <InputField placeholder='0.00' prefix='$' suffix='USD' />
           <InputField
-            label='With Prefix/Suffix'
-            placeholder='0.00'
-            prefix='$'
-            suffix='USD'
-          />
-          <InputField
-            label='With Icons'
             placeholder='Enter text'
             leadingIcon={<Home size={16} />}
             trailingIcon={<Info size={16} />}
           />
-          <InputField label='Disabled' placeholder='Enter text' disabled />
+          <InputField placeholder='Enter text' disabled />
         </Flex>
       </Flex>
     </PlaygroundLayout>

apps/www/src/components/playground/text-area-examples.tsx

@@ -1,24 +1,19 @@
 'use client';
 
-import { Flex, TextArea } from '@raystack/apsara';
+import { Field, Flex, TextArea } from '@raystack/apsara';
 import PlaygroundLayout from './playground-layout';
 
 export function TextAreaExamples() {
   return (
     <PlaygroundLayout title='TextArea'>
       <Flex gap='large' wrap='wrap'>
-        <TextArea label='Basic TextArea' placeholder='Enter your text here' />
-        <TextArea
-          label='Basic TextArea'
-          placeholder='Enter your text here'
-          helperText='This is a helper text'
-        />
-        <TextArea
-          label='Error TextArea'
-          error={true}
-          helperText='This field has an error'
-          placeholder='Enter your text here'
-        />
+        <Field label='Basic TextArea' description='This is a description'>
+          <TextArea placeholder='Enter your text here' />
+        </Field>
+        <Field label='Error TextArea' error='This field has an error'>
+          <TextArea placeholder='Enter your text here' />
+        </Field>
+        <TextArea placeholder='Without Field wrapper' width='300px' />
       </Flex>
     </PlaygroundLayout>
   );

apps/www/src/content/docs/components/combobox/demo.ts

@@ -105,23 +105,20 @@ export const iconDemo = {
   </Combobox>`
 };
 
-export const withLabelDemo = {
+export const withFieldDemo = {
   type: 'code',
   code: `
-  <Combobox>
-    <Combobox.Input
-      placeholder="Select a fruit"
-      label="Favorite Fruit"
-      helperText="Choose your favorite fruit"
-      width={240}
-    />
-    <Combobox.Content>
-      <Combobox.Item value="apple">Apple</Combobox.Item>
-      <Combobox.Item value="banana">Banana</Combobox.Item>
-      <Combobox.Item value="blueberry">Blueberry</Combobox.Item>
-      <Combobox.Item value="grapes">Grapes</Combobox.Item>
-    </Combobox.Content>
-  </Combobox>`
+  <Field label="Favorite Fruit" description="Choose your favorite fruit">
+    <Combobox>
+      <Combobox.Input placeholder="Select a fruit" width={240} />
+      <Combobox.Content>
+        <Combobox.Item value="apple">Apple</Combobox.Item>
+        <Combobox.Item value="banana">Banana</Combobox.Item>
+        <Combobox.Item value="blueberry">Blueberry</Combobox.Item>
+        <Combobox.Item value="grapes">Grapes</Combobox.Item>
+      </Combobox.Content>
+    </Combobox>
+  </Field>`
 };
 
 export const controlledDemo = {

apps/www/src/content/docs/components/combobox/index.mdx

@@ -10,7 +10,7 @@ import {
   multipleDemo,
   groupDemo,
   iconDemo,
-  withLabelDemo,
+  withFieldDemo,
   controlledDemo,
 } from "./demo.ts";
 
@@ -91,11 +91,11 @@ You can pass the `leadingIcon` prop to `Combobox.Item` to display icons before i
 
 <Demo data={iconDemo} />
 
-### With Label and Helper Text
+### With Field
 
-The input supports `label`, `helperText`, and other `InputField` props.
+Wrap the Combobox with [Field](/docs/components/field) to add a label, description, and error handling.
 
-<Demo data={withLabelDemo} />
+<Demo data={withFieldDemo} />
 
 ### Groups and Separators
 

apps/www/src/content/docs/components/combobox/props.ts

@@ -53,35 +53,26 @@ export interface ComboboxRootProps {
 
 export interface ComboboxInputProps {
   /**
-   * Size variant of the input field
+   * Size variant of the input field.
    * @default "large"
    */
   size?: 'small' | 'large';
 
-  /** Text label above the input */
-  label?: string;
-
-  /** Helper text below the input */
-  helperText?: string;
-
-  /** Error message to display below the input */
-  error?: string;
-
-  /** Whether the input is disabled */
+  /** Whether the input is disabled. */
   disabled?: boolean;
 
-  /** Icon element to display at the start of input */
+  /** Icon element to display at the start of input. */
   leadingIcon?: React.ReactNode;
 
-  /** Shows "(Optional)" text next to label */
-  optional?: boolean;
-
-  /** Text or symbol to show before input value */
+  /** Text or symbol to show before input value. */
   prefix?: string;
 
   /** Placeholder text for the input field. */
   placeholder?: string;
 
+  /** Custom width for the input field. */
+  width?: string | number;
+
   /** Additional CSS class names. */
   className?: string;
 }