Utility Components

/**
 * Component for screen reader-only content
 * @param props - Content and element type props
 * @returns JSX element hidden visually but accessible to screen readers
 */
function VisuallyHidden(props: VisuallyHiddenProps): JSX.Element;

interface VisuallyHiddenProps {
  /** Content to hide visually but keep accessible */
  children?: ReactNode;
  /** Element or component to render as */
  as?: ElementType;
}

/**
 * CSS styles object for creating visually hidden content
 */
const visuallyHiddenStyles: {
  readonly border: 0;
  readonly clip: 'rect(0, 0, 0, 0)';
  readonly height: 1;
  readonly overflow: 'hidden';
  readonly padding: 0;
  readonly position: 'absolute';
  readonly whiteSpace: 'nowrap';
  readonly width: 1;
};

import { VisuallyHidden } from "@keystone-ui/core";

// Screen reader instructions
<button>
  <IconEdit />
  <VisuallyHidden>Edit user profile</VisuallyHidden>
</button>

// Form labels for icon-only inputs
<div>
  <VisuallyHidden as="label" htmlFor="search">
    Search products
  </VisuallyHidden>
  <input id="search" type="search" placeholder="Search..." />
</div>

// Skip navigation link
<VisuallyHidden as="a" href="#main-content">
  Skip to main content
</VisuallyHidden>

// Custom element type
<VisuallyHidden as="h2">
  Section heading for screen readers only
</VisuallyHidden>

/**
 * Themed link component with hover states
 * @param props - Link styling and content props
 * @returns JSX element with theme-based link styling
 */
function Link(props: LinkProps): JSX.Element;

interface LinkProps {
  /** Element or component to render as */
  as?: ElementType;
  /** Child content */
  children?: ReactNode;
  /** All other HTML anchor attributes */
  [key: string]: any;
}

import { Link } from "@keystone-ui/core";

// Basic themed link
<Link href="/about">About Us</Link>

// Custom element (React Router Link)
<Link as={RouterLink} to="/dashboard">
  Dashboard
</Link>

// External link
<Link href="https://keystonejs.com" target="_blank" rel="noopener">
  KeystoneJS
</Link>

// Button-styled link
<Link 
  as="button" 
  onClick={handleClick}
  style={{ background: 'none', border: 'none' }}
>
  Click me
</Link>

/**
 * Visual separator with orientation support
 * @param props - Divider styling and layout props
 * @returns JSX element as visual separator
 */
function Divider(props: DividerProps): JSX.Element;

interface DividerProps extends MarginProps {
  /** Divider color from theme palette */
  color?: ResponsiveProp<keyof Theme['palette']>;
  /** Divider orientation */
  orientation?: 'horizontal' | 'vertical';
  /** CSS class name */
  className?: string;
  /** No children allowed */
  children?: never;
}

import { Divider, Stack, Inline, Text } from "@keystone-ui/core";

// Horizontal divider (default)
<Stack gap="medium">
  <Text>Section 1</Text>
  <Divider />
  <Text>Section 2</Text>
</Stack>

// Vertical divider  
<Inline gap="medium" align="center">
  <Text>Item 1</Text>
  <Divider orientation="vertical" />
  <Text>Item 2</Text>
</Inline>

// Custom colored divider with spacing
<Divider 
  color="blue300" 
  marginY="large"
  orientation="horizontal"
/>

// Responsive divider color
<Divider color={["neutral300", "neutral400"]} />

/**
 * Component for centering content horizontally and vertically
 * @param props - Center layout and styling props
 * @returns JSX element with centered content
 */
function Center(props: CenterProps): JSX.Element;

interface CenterProps extends BoxProps {
  /** Fill entire viewport height and width */
  fillView?: boolean;
}

import { Center, Text, Stack } from "@keystone-ui/core";

// Center content in container
<Center height="200px" background="neutral100">
  <Text>Centered content</Text>
</Center>

// Full viewport centering for loading states
<Center fillView>
  <Stack gap="medium" align="center">
    <Spinner />
    <Text>Loading...</Text>
  </Stack>
</Center>

// Center with additional styling
<Center 
  height="300px"
  background="blue50"
  rounding="large"
  padding="xlarge"
>
  <Text size="large" textAlign="center">
    Welcome Message
  </Text>
</Center>

/**
 * Creates a component with polymorphic `as` prop support
 * @param render - Render function receiving props and ref
 * @returns Component with polymorphic behavior
 */
function forwardRefWithAs<DefaultElementType extends ElementType, BaseProps>(
  render: (
    props: BaseProps & { as?: ElementType },
    ref: React.Ref<any>
  ) => ReactNode
): CompWithAsProp<BaseProps, DefaultElementType>;

type CompWithAsProp<Props, DefaultElementType extends ElementType> = <
  Comp extends ElementType = DefaultElementType
>(
  props: AsProp<Comp, Props> & Props
) => ReactElement;

import { forwardRefWithAs } from "@keystone-ui/core";

// Create custom polymorphic component
const MyButton = forwardRefWithAs<'button', { variant?: 'primary' | 'secondary' }>(
  ({ variant = 'primary', as: Tag = 'button', ...props }, ref) => {
    return (
      <Tag 
        ref={ref} 
        className={`btn btn-${variant}`}
        {...props} 
      />
    );
  }
);

// Usage with different elements
<MyButton>Default button</MyButton>
<MyButton as="a" href="/link">Link button</MyButton>
<MyButton as={CustomComponent}>Custom component</MyButton>

/**
 * Returns appropriate child tag for a parent element
 * @param parentTag - Parent element type
 * @returns Appropriate child element tag
 */
function getChildTag(parentTag?: ElementType): ElementType;

import { getChildTag } from "@keystone-ui/core";

// Used internally by Stack and Inline components
function MyListComponent({ as = 'div', children }) {
  const ChildTag = getChildTag(as);
  
  return (
    <as>
      {children.map(child => (
        <ChildTag key={child.id}>
          {child.content}
        </ChildTag>
      ))}
    </as>
  );
}

// Returns 'li' for 'ul' or 'ol', 'div' for others
getChildTag('ul');  // 'li'
getChildTag('ol');  // 'li'  
getChildTag('div'); // 'div'

/**
 * Generates unique ID for components, with SSR support
 * @param idFromProps - Optional ID provided via props
 * @returns Unique string ID or undefined
 */
function useId(idFromProps?: string | null): string | undefined;

/**
 * Creates compound ID from multiple inputs
 * @param args - String, number, or null/undefined values to combine
 * @returns Compound ID string with null/undefined values filtered out
 */
function makeId(...args: (string | number | null | undefined)[]): string;

import { useId, makeId } from "@keystone-ui/core";

function FormField({ id: providedId, label, ...props }) {
  // Generate ID if not provided
  const id = useId(providedId);
  const labelId = makeId(id, 'label');
  const helpId = makeId(id, 'help');
  
  return (
    <div>
      <label id={labelId} htmlFor={id}>
        {label}
      </label>
      <input 
        id={id} 
        aria-labelledby={labelId}
        aria-describedby={helpId}
        {...props} 
      />
      <div id={helpId}>
        Help text
      </div>
    </div>
  );
}

// makeId filters out null/undefined values
makeId('field', null, 'label', undefined); // 'field--label'
makeId('modal', 123, 'content'); // 'modal--123--content'

/**
 * Logs warning to console in development mode only
 * @param condition - When true, warning will be logged
 * @param message - Warning message to display
 */
function devWarning(condition: boolean, message: string): void;

import { devWarning } from "@keystone-ui/core";

function MyComponent({ value, onChange }) {
  // Warn about missing onChange handler
  devWarning(
    value !== undefined && !onChange,
    'MyComponent: controlled component is missing onChange handler'
  );
  
  // Warn about invalid prop combinations
  devWarning(
    variant === 'custom' && !customStyle,
    'MyComponent: customStyle prop is required when variant="custom"'
  );
  
  return <div>{/* component content */}</div>;
}

/**
 * Maps responsive prop values to theme scale values
 * @param value - Single value or array of responsive values
 * @param valueMap - Theme scale object to map values against
 * @returns Mapped value(s) for CSS properties
 */
function mapResponsiveProp<
  Map extends Record<string, string | number>,
  Keys extends keyof Map
>(
  value: Keys | readonly (Keys | null)[],
  valueMap: Map
): string | number | (string | number | null)[];

import { mapResponsiveProp, useTheme } from "@keystone-ui/core";

function CustomComponent({ padding, margin }) {
  const theme = useTheme();
  
  // Map single values
  const paddingValue = mapResponsiveProp(padding, theme.spacing);
  // padding = "medium" -> theme.spacing.medium (12)
  
  // Map responsive arrays  
  const marginValue = mapResponsiveProp(
    ["small", "medium", "large"], 
    theme.spacing
  );
  // Returns [8, 12, 16]
  
  // Handle null values in arrays
  const responsiveValue = mapResponsiveProp(
    ["small", null, "large"],
    theme.spacing  
  );
  // Returns [8, null, 16]
  
  return (
    <div style={{ 
      padding: paddingValue,
      margin: marginValue 
    }}>
      Content
    </div>
  );
}

// Used internally by Box component
const boxStyles = {
  padding: mapResponsiveProp(paddingProp, theme.spacing),
  backgroundColor: mapResponsiveProp(backgroundProp, theme.palette)
};

/**
 * Renders children in a portal to document.body
 * @param props - Portal props with children
 * @returns React portal or null for SSR compatibility
 */
function Portal(props: PortalProps): React.ReactPortal | null;

interface PortalProps {
  children: ReactElement;
}

import { Portal } from "@keystone-ui/core";

function Modal({ isOpen, children }) {
  if (!isOpen) return null;
  
  return (
    <Portal>
      <div className="modal-overlay">
        <div className="modal-content">
          {children}
        </div>
      </div>
    </Portal>
  );
}

function Tooltip({ content, children }) {
  return (
    <div>
      {children}
      <Portal>
        <div className="tooltip">
          {content}
        </div>
      </Portal>
    </div>
  );
}

/**
 * TypeScript utility for preserving generic types with inference
 * @returns Function that preserves and validates generic type
 */
function identityType<T>(): <U extends T>(u: U) => U;

import { identityType } from "@keystone-ui/core";

// Define strongly-typed configuration objects
const createConfig = identityType<{ name: string; value: number }>()({
  name: 'example',
  value: 42
  // TypeScript will enforce this shape
});

// Used internally for theme type safety
const toneConfig = identityType<Record<string, ToneColor>>()({
  primary: { fill: '#blue', tint: '#lightblue' },
  secondary: { fill: '#gray', tint: '#lightgray' }
});