@ceed/cds 1.28.0 → 1.29.0-next.1

package/dist/components/feedback/Skeleton.md

@@ -1,280 +0,0 @@
-# Skeleton
-
-## Introduction
-
-The Skeleton component provides placeholder previews of content before data is loaded. It is based on Joy UI's Skeleton and helps reduce perceived loading time by showing an approximation of the page layout. Skeletons improve the user experience by preventing layout shifts and giving users a visual cue that content is on its way.
-
-```tsx
-<Skeleton
-  variant="rectangular"
-  width={200}
-  height={24}
-/>
-```
-
-| Field                        | Description | Default |
-| ---------------------------- | ----------- | ------- |
-| Controls resolved at runtime | —           | —       |
-
-## Usage
-
-```tsx
-import { Skeleton } from '@ceed/cds';
-
-function MyComponent() {
-  return <Skeleton variant="rectangular" width={200} height={24} />;
-}
-```
-
-## Variants
-
-Skeleton supports three variants: `rectangular`, `circular`, and `text`.
-
-- **rectangular**: Block-shaped placeholder for images, cards, and content areas.
-- **circular**: Round placeholder for avatars and icons.
-- **text**: Matches the height and spacing of text content at a given `level`.
-
-```tsx
-<>
-  <Skeleton variant="rectangular" width={200} height={24} />
-  <Skeleton variant="circular" width={48} height={48} />
-  <Skeleton variant="text" width={200} />
-</>
-```
-
-```tsx
-<Skeleton variant="rectangular" width={200} height={24} />
-<Skeleton variant="circular" width={48} height={48} />
-<Skeleton variant="text" width={200} />
-```
-
-## Animations
-
-Skeleton supports `wave` (default) and `pulse` animations. Set `animation={false}` to disable animation entirely.
-
-```tsx
-<Stack gap={3}>
-  <Box>
-    <Typography level="body-sm" sx={{
-      mb: 1
-    }}>
-    Wave (default)
-  </Typography>
-  <Skeleton animation="wave" variant="rectangular" width={200} height={24} />
-</Box>
-<Box>
-  <Typography level="body-sm" sx={{
-    mb: 1
-  }}>
-  Pulse
-</Typography>
-<Skeleton animation="pulse" variant="rectangular" width={200} height={24} />
-</Box>
-<Box>
-  <Typography level="body-sm" sx={{
-    mb: 1
-  }}>
-  No animation (false)
-</Typography>
-<Skeleton animation={false} variant="rectangular" width={200} height={24} />
-</Box>
-</Stack>
-```
-
-```tsx
-<Skeleton animation="wave" variant="rectangular" width={200} height={24} />
-<Skeleton animation="pulse" variant="rectangular" width={200} height={24} />
-<Skeleton animation={false} variant="rectangular" width={200} height={24} />
-```
-
-## Text Skeleton
-
-Use `variant="text"` with the `level` prop to match Typography sizing. This is useful for creating text content placeholders that accurately reflect the final layout.
-
-```tsx
-<Stack gap={1} sx={{
-  width: 300
-}}>
-<Skeleton variant="text" level="h3" />
-<Skeleton variant="text" level="body-md" />
-<Skeleton variant="text" level="body-md" />
-<Skeleton variant="text" level="body-md" width="80%" />
-</Stack>
-```
-
-```tsx
-<Skeleton variant="text" level="h3" />
-<Skeleton variant="text" level="body-md" />
-<Skeleton variant="text" level="body-md" />
-<Skeleton variant="text" level="body-md" width="80%" />
-```
-
-## Card Skeleton
-
-Compose multiple Skeleton elements to create placeholder layouts for complex components like cards.
-
-```tsx
-<Box sx={{
-  width: 300,
-  p: 2,
-  border: '1px solid',
-  borderColor: 'divider',
-  borderRadius: 'sm'
-}}>
-<Skeleton variant="rectangular" width="100%" height={140} sx={{
-  borderRadius: 'sm',
-  mb: 2
-}} />
-<Skeleton variant="text" level="title-md" sx={{
-  mb: 1
-}} />
-<Skeleton variant="text" level="body-sm" />
-<Skeleton variant="text" level="body-sm" width="60%" />
-<Stack direction="row" gap={1} sx={{
-  mt: 2
-}}>
-<Skeleton variant="rectangular" width={80} height={32} sx={{
-  borderRadius: 'sm'
-}} />
-<Skeleton variant="rectangular" width={80} height={32} sx={{
-  borderRadius: 'sm'
-}} />
-</Stack>
-</Box>
-```
-
-## Data Loading List
-
-Combine circular and text skeletons to represent list items during loading.
-
-```tsx
-<Stack gap={2} sx={{
-  width: 400
-}}>
-{[1, 2, 3].map(i => <Stack key={i} direction="row" gap={2} alignItems="center">
-<Skeleton variant="circular" width={40} height={40} />
-<Box sx={{
-  flex: 1
-}}>
-<Skeleton variant="text" level="title-sm" width="60%" />
-<Skeleton variant="text" level="body-xs" width="40%" />
-</Box>
-</Stack>)}
-</Stack>
-```
-
-## Inline Wrapping
-
-Wrap existing content with Skeleton to overlay it while loading. Set the `loading` prop to control visibility.
-
-```tsx
-<Typography level="body-md">
-  <Skeleton loading>
-    This text will be hidden behind a skeleton while loading.
-  </Skeleton>
-</Typography>
-```
-
-```tsx
-<Typography level="body-md">
-  <Skeleton loading>
-    This text will be hidden behind a skeleton while loading.
-  </Skeleton>
-</Typography>
-```
-
-## Common Use Cases
-
-### Page Content Loading
-
-```tsx
-function PageSkeleton() {
-  return (
-    <Stack gap={3}>
-      <Skeleton variant="text" level="h1" width="50%" />
-      <Skeleton variant="text" level="body-md" />
-      <Skeleton variant="text" level="body-md" />
-      <Skeleton variant="text" level="body-md" width="75%" />
-
-      <Skeleton variant="rectangular" width="100%" height={200} sx={{ borderRadius: 'sm' }} />
-
-      <Skeleton variant="text" level="body-md" />
-      <Skeleton variant="text" level="body-md" />
-    </Stack>
-  );
-}
-```
-
-### User List Loading
-
-```tsx
-function UserListSkeleton({ count = 5 }: { count?: number }) {
-  return (
-    <Stack gap={2}>
-      {Array.from({ length: count }).map((_, i) => (
-        <Stack key={i} direction="row" gap={2} alignItems="center">
-          <Skeleton variant="circular" width={40} height={40} />
-          <Box sx={{ flex: 1 }}>
-            <Skeleton variant="text" level="title-sm" width="40%" />
-            <Skeleton variant="text" level="body-xs" width="25%" />
-          </Box>
-        </Stack>
-      ))}
-    </Stack>
-  );
-}
-```
-
-### Conditional Rendering
-
-```tsx
-function UserProfile({ loading, user }: { loading: boolean; user?: User }) {
-  return (
-    <Stack direction="row" gap={2} alignItems="center">
-      {loading ? (
-        <Skeleton variant="circular" width={48} height={48} />
-      ) : (
-        <Avatar src={user?.avatar} />
-      )}
-      <Box>
-        <Typography level="title-md">
-          <Skeleton loading={loading}>{user?.name || 'Placeholder Name'}</Skeleton>
-        </Typography>
-        <Typography level="body-sm">
-          <Skeleton loading={loading}>{user?.email || 'email@example.com'}</Skeleton>
-        </Typography>
-      </Box>
-    </Stack>
-  );
-}
-```
-
-## Best Practices
-
-1. **Match the final layout**: Skeleton placeholders should closely approximate the size and position of the real content to prevent layout shifts.
-
-```tsx
-// ✅ Matches the actual content structure
-<Stack gap={1}>
-  <Skeleton variant="text" level="title-md" width="60%" />
-  <Skeleton variant="text" level="body-sm" />
-</Stack>
-
-// ❌ Generic rectangle that doesn't match
-<Skeleton variant="rectangular" width={300} height={100} />
-```
-
-2. **Use `variant="text"` with `level`**: When replacing Typography, use the text variant with the matching level to get accurate line heights.
-
-3. **Avoid over-skeletonizing**: Only skeleton the main content areas. Don't add skeletons for static elements like navigation or headers that are always present.
-
-4. **Use consistent animation**: Keep the same animation type (`wave` or `pulse`) across the entire application for a cohesive loading experience.
-
-5. **Set appropriate widths**: Vary skeleton widths (e.g., 60%, 80%, 100%) to mimic natural text line lengths rather than using uniform widths.
-
-## Accessibility
-
-- Skeleton elements are purely decorative. Screen readers should focus on the loading state announcement, not individual skeleton elements.
-- Use `aria-busy="true"` on the container element while content is loading.
-- Provide an `aria-label` or visually hidden text that describes the loading state (e.g., "Loading user profile").
-- Ensure the animation respects `prefers-reduced-motion` — Joy UI handles this automatically.

package/dist/components/inputs/FormControl.md

@@ -1,361 +0,0 @@
-# FormControl
-
-## Introduction
-
-FormControl is a wrapper component that provides context to form elements such as Input, Textarea, Select, and more. It manages shared states like `error`, `disabled`, `required`, and `size`, passing them down to its children automatically. Use it with FormLabel and FormHelperText to build accessible, consistent form fields.
-
-```tsx
-<FormControl {...args}>
-  <FormLabel>Label</FormLabel>
-  <Input placeholder="Enter text…" />
-  <FormHelperText>This is helper text.</FormHelperText>
-</FormControl>
-```
-
-| Field       | Description | Default |
-| ----------- | ----------- | ------- |
-| size        | —           | —       |
-| error       | —           | —       |
-| disabled    | —           | —       |
-| required    | —           | —       |
-| orientation | —           | —       |
-
-## Usage
-
-```tsx
-import { FormControl, FormLabel, FormHelperText, Input } from '@ceed/cds';
-
-function MyForm() {
-  return (
-    <FormControl>
-      <FormLabel>Username</FormLabel>
-      <Input placeholder="Enter username" />
-      <FormHelperText>Choose a unique username.</FormHelperText>
-    </FormControl>
-  );
-}
-```
-
-## With Input
-
-The most common pattern — wrapping an Input with a label and helper text.
-
-```tsx
-<FormControl>
-  <FormLabel>Username</FormLabel>
-  <Input placeholder="Enter username" />
-  <FormHelperText>Choose a unique username.</FormHelperText>
-</FormControl>
-```
-
-## With Textarea
-
-FormControl works equally well with Textarea components.
-
-```tsx
-<FormControl>
-  <FormLabel>Description</FormLabel>
-  <Textarea placeholder="Enter description…" minRows={3} />
-  <FormHelperText>Provide a detailed description.</FormHelperText>
-</FormControl>
-```
-
-## With Select
-
-Use FormControl with Select for dropdown fields.
-
-```tsx
-<FormControl>
-  <FormLabel>Role</FormLabel>
-  <Select placeholder="Select a role" options={roleOptions} />
-  <FormHelperText>Select the user role.</FormHelperText>
-</FormControl>
-```
-
-## Error State
-
-Set `error` on FormControl to propagate the error state to all child components. FormHelperText automatically changes color to indicate the error.
-
-```tsx
-<FormControl error>
-  <FormLabel>Email</FormLabel>
-  <Input placeholder="email@example.com" defaultValue="invalid-email" />
-  <FormHelperText>Please enter a valid email address.</FormHelperText>
-</FormControl>
-```
-
-```tsx
-<FormControl error>
-  <FormLabel>Email</FormLabel>
-  <Input placeholder="email@example.com" value="invalid-email" />
-  <FormHelperText>Please enter a valid email address.</FormHelperText>
-</FormControl>
-```
-
-## Disabled State
-
-Set `disabled` to disable all child form elements at once.
-
-```tsx
-<FormControl disabled>
-  <FormLabel>Name</FormLabel>
-  <Input placeholder="Enter name" defaultValue="John Doe" />
-  <FormHelperText>This field is disabled.</FormHelperText>
-</FormControl>
-```
-
-```tsx
-<FormControl disabled>
-  <FormLabel>Name</FormLabel>
-  <Input placeholder="Enter name" value="John Doe" />
-  <FormHelperText>This field is disabled.</FormHelperText>
-</FormControl>
-```
-
-## Required Field
-
-Set `required` to add an asterisk (\*) to the label and mark the field as required.
-
-```tsx
-<FormControl required>
-  <FormLabel>Full Name</FormLabel>
-  <Input placeholder="Enter your full name" />
-  <FormHelperText>This field is required.</FormHelperText>
-</FormControl>
-```
-
-```tsx
-<FormControl required>
-  <FormLabel>Full Name</FormLabel>
-  <Input placeholder="Enter your full name" />
-</FormControl>
-```
-
-## Sizes
-
-FormControl supports `sm`, `md`, and `lg` sizes. The size is inherited by child components.
-
-```tsx
-<Stack gap={3}>
-  <FormControl size="sm">
-    <FormLabel>Small</FormLabel>
-    <Input placeholder="Small input" />
-  </FormControl>
-  <FormControl size="md">
-    <FormLabel>Medium</FormLabel>
-    <Input placeholder="Medium input" />
-  </FormControl>
-  <FormControl size="lg">
-    <FormLabel>Large</FormLabel>
-    <Input placeholder="Large input" />
-  </FormControl>
-</Stack>
-```
-
-## Horizontal Layout
-
-Use `orientation="horizontal"` for inline form controls, such as Switch or Checkbox toggles.
-
-```tsx
-<FormControl orientation="horizontal" sx={{
-  gap: 2
-}}>
-<FormLabel>Subscribe</FormLabel>
-<Switch />
-</FormControl>
-```
-
-```tsx
-<FormControl orientation="horizontal" sx={{ gap: 2 }}>
-  <FormLabel>Subscribe</FormLabel>
-  <Switch />
-</FormControl>
-```
-
-## Form Example
-
-A complete form demonstrating FormControl with multiple input types.
-
-```tsx
-<Stack gap={2} sx={{
-  maxWidth: 400
-}}>
-<FormControl required>
-  <FormLabel>Name</FormLabel>
-  <Input placeholder="Enter your name" />
-</FormControl>
-<FormControl required>
-  <FormLabel>Email</FormLabel>
-  <Input type="email" placeholder="email@example.com" />
-  <FormHelperText>We will never share your email.</FormHelperText>
-</FormControl>
-<FormControl>
-  <FormLabel>Role</FormLabel>
-  <Select placeholder="Select a role" options={roleOptions} />
-</FormControl>
-<FormControl>
-  <FormLabel>Bio</FormLabel>
-  <Textarea placeholder="Tell us about yourself…" minRows={3} />
-  <FormHelperText>Maximum 500 characters.</FormHelperText>
-</FormControl>
-</Stack>
-```
-
-## FormLabel
-
-FormLabel renders a `<label>` element associated with its sibling input. It automatically displays an asterisk when the parent FormControl has `required` set.
-
-```tsx
-<FormControl required>
-  <FormLabel>Email</FormLabel>
-  <Input />
-</FormControl>
-```
-
-## FormHelperText
-
-FormHelperText provides supplementary guidance below the input. It automatically switches to the error color when the parent FormControl has `error` set.
-
-```tsx
-<FormControl error>
-  <FormLabel>Password</FormLabel>
-  <Input type="password" />
-  <FormHelperText>Password must be at least 8 characters.</FormHelperText>
-</FormControl>
-```
-
-## Common Use Cases
-
-### Registration Form
-
-```tsx
-function RegistrationForm() {
-  const [errors, setErrors] = React.useState({});
-
-  return (
-    <Stack gap={2} component="form">
-      <FormControl required error={!!errors.name}>
-        <FormLabel>Name</FormLabel>
-        <Input placeholder="Enter your name" />
-        {errors.name && <FormHelperText>{errors.name}</FormHelperText>}
-      </FormControl>
-
-      <FormControl required error={!!errors.email}>
-        <FormLabel>Email</FormLabel>
-        <Input type="email" placeholder="email@example.com" />
-        {errors.email && <FormHelperText>{errors.email}</FormHelperText>}
-      </FormControl>
-
-      <FormControl required error={!!errors.password}>
-        <FormLabel>Password</FormLabel>
-        <Input type="password" placeholder="Enter password" />
-        <FormHelperText>{errors.password || 'Must be at least 8 characters.'}</FormHelperText>
-      </FormControl>
-
-      <FormControl orientation="horizontal">
-        <Checkbox label="I agree to the terms and conditions" />
-      </FormControl>
-    </Stack>
-  );
-}
-```
-
-### Settings Form with Mixed Controls
-
-```tsx
-function SettingsForm() {
-  return (
-    <Stack gap={2}>
-      <FormControl orientation="horizontal" sx={{ justifyContent: 'space-between' }}>
-        <FormLabel>Email notifications</FormLabel>
-        <Switch />
-      </FormControl>
-
-      <FormControl>
-        <FormLabel>Language</FormLabel>
-        <Select
-          defaultValue="en"
-          options={[
-            { value: 'en', label: 'English' },
-            { value: 'ko', label: 'Korean' },
-          ]}
-        />
-      </FormControl>
-
-      <FormControl>
-        <FormLabel>Notes</FormLabel>
-        <Textarea minRows={3} placeholder="Additional notes…" />
-        <FormHelperText>Optional</FormHelperText>
-      </FormControl>
-    </Stack>
-  );
-}
-```
-
-> **Tip: Use built-in form props instead**
->
-> Input, Select, Textarea, DatePicker 등 Input 계열 컴포넌트는 `label`, `helperText` prop을 자체적으로 지원합니다.
-> 간단한 form 필드에는 각 컴포넌트의 내장 prop을 사용하는 것이 더 간결합니다.
->
-> ```tsx
-> // ✅ Simpler: built-in props
-> <Input label="Username" helperText="Choose a unique username." />
->
-> // ⬆️ Equivalent to:
-> <FormControl>
->   <FormLabel>Username</FormLabel>
->   <Input placeholder="Enter username" />
->   <FormHelperText>Choose a unique username.</FormHelperText>
-> </FormControl>
-> ```
->
-> FormControl is most useful when you need to compose multiple elements, share state across siblings, or use horizontal orientation.
-
-## Best Practices
-
-1. **Always pair with FormLabel**: Every form field should have a label for accessibility. Use FormLabel inside FormControl.
-
-```tsx
-// ✅ Accessible — label is associated with input
-<FormControl>
-  <FormLabel>Email</FormLabel>
-  <Input />
-</FormControl>
-
-// ❌ No label — screen readers cannot identify the input
-<FormControl>
-  <Input placeholder="Email" />
-</FormControl>
-```
-
-2. **Use `error` prop on FormControl, not children**: Set error state on FormControl so all children react consistently.
-
-```tsx
-// ✅ Error propagated from FormControl
-<FormControl error>
-  <FormLabel>Email</FormLabel>
-  <Input />
-  <FormHelperText>Invalid email</FormHelperText>
-</FormControl>
-
-// ❌ Inconsistent — only Input shows error
-<FormControl>
-  <FormLabel>Email</FormLabel>
-  <Input error />
-  <FormHelperText>Invalid email</FormHelperText>
-</FormControl>
-```
-
-3. **Use consistent sizing**: Set `size` on FormControl to ensure all children (label, input, helper text) are proportionally sized.
-
-4. **Mark required fields**: Use the `required` prop to automatically add visual indicators and `aria-required` attributes.
-
-5. **Provide helpful error messages**: When using the error state, always include a FormHelperText explaining what went wrong and how to fix it.
-
-## Accessibility
-
-- FormControl automatically associates FormLabel with the input using `htmlFor` and `id`.
-- The `required` prop adds `aria-required="true"` to the input and an asterisk to the label.
-- The `error` prop adds `aria-invalid="true"` to the input.
-- FormHelperText is linked to the input via `aria-describedby` so screen readers announce it.
-- Use the `disabled` prop on FormControl to set `aria-disabled` on child elements.