section.tsx

import { cn } from '@/lib/utils';

/**
 * Container for grouping section content with title. Use with FieldGroup for
 * form fields or ItemGroup for list items.
 *
 * @example
 *   // Section with form fields
 *   <Section>
 *     <SectionTitle>Account Settings</SectionTitle>
 *     <FieldGroup>
 *       <Field>
 *         <FieldLabel>Username</FieldLabel>
 *         <FieldControl>
 *           <Input />
 *         </FieldControl>
 *       </Field>
 *     </FieldGroup>
 *   </Section>;
 *
 * @example
 *   // Section with items
 *   <Section>
 *     <SectionTitle>Notifications</SectionTitle>
 *     <ItemGroup separator>
 *       <Item>
 *         <ItemContent>
 *           <ItemTitle>Email notifications</ItemTitle>
 *         </ItemContent>
 *         <ItemActions>
 *           <Switch />
 *         </ItemActions>
 *       </Item>
 *       <Item>
 *         <ItemContent>
 *           <ItemTitle>Push notifications</ItemTitle>
 *         </ItemContent>
 *         <ItemActions>
 *           <Switch />
 *         </ItemActions>
 *       </Item>
 *     </ItemGroup>
 *   </Section>;
 */
export function Section({
  className,
  ...props
}: React.ComponentProps<'section'>) {
  return (
    <section
      className={cn(
        'relative mb-4 not-has-[>div,>section,>h1,>h2,>h3,>h4,>h5,>h6]:hidden',
        className
      )}
      data-slot="section"
      {...props}
    />
  );
}

/**
 * Title for a section with optional description.
 *
 * @example
 *   // Simple title
 *   <SectionTitle>Security Settings</SectionTitle>;
 *
 * @example
 *   // With description and actions
 *   <SectionTitle>
 *     <div className="flex w-full items-center justify-between">
 *       <div>
 *         Plan Summary
 *         <SectionDescription>
 *           Manage your subscription and billing.
 *         </SectionDescription>
 *       </div>
 *       <Button size="sm">Upgrade</Button>
 *     </div>
 *   </SectionTitle>;
 */
export function SectionTitle({
  children,
  className,
  ...props
}: React.ComponentProps<'div'>) {
  return (
    <div
      className={cn(
        'flex items-center justify-between border-b border-border py-3',
        className
      )}
      data-slot="section-title"
      {...props}
    >
      <h3 className="w-full text-lg font-normal">{children}</h3>
    </div>
  );
}

/**
 * Optional description text for a section title. Supports inline links.
 *
 * @example
 *   <SectionTitle>
 *     Security Settings
 *     <SectionDescription>
 *       Enable two-factor authentication to secure your account.
 *       <a href="/help">Learn more</a>
 *     </SectionDescription>
 *   </SectionTitle>;
 */
export function SectionDescription({
  className,
  ...props
}: React.ComponentProps<'div'>) {
  return (
    <div
      className={cn(
        'mt-0.5 text-xs text-muted-foreground [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary',
        className
      )}
      data-slot="section-description"
      {...props}
    />
  );
}