@cube-dev/ui-kit 0.0.0-canary-c210a8c → 0.0.0-canary-184567a

package/docs/CreateComponent.md

@@ -0,0 +1,410 @@
+# Create Component
+
+This guide explains how to create components using the `tasty` style helper and React Aria Hooks. Components in the Cube UI Kit follow consistent patterns for styling, accessibility, and functionality.
+
+## Overview
+
+Creating a component involves several optional but recommended elements:
+
+- **Base properties** handling using `filterBaseProps`
+- **Style properties** for direct styling capabilities
+- **Modifiers (`mods`)** for state-based styling
+- **Additional style properties** for styling inner elements
+- **Sub-elements** for targeted styling within components
+- **React Aria integration** for accessibility
+
+Everything is optional - you can create simplified components without all features, but exported UI Kit components should be feature-rich and consistent.
+
+## Core Concepts
+
+### 1. Base Properties with `filterBaseProps`
+
+The `filterBaseProps` helper ensures only valid DOM properties are passed to elements, filtering out design system properties and unsupported event handlers.
+
+```tsx
+import { filterBaseProps, AllBaseProps } from '@tenphi/tasty';
+
+interface MyComponentProps extends AllBaseProps {
+  customProp?: string;
+}
+
+function MyComponent(props: MyComponentProps) {
+  return (
+    <div {...filterBaseProps(props, { eventProps: true })}>
+      {props.children}
+    </div>
+  );
+}
+```
+
+**Filter options:**
+- `eventProps: true` - Include standard DOM event handlers (onClick, onFocus, etc.)
+- `labelable: true` - Include ARIA labeling properties
+- `propNames: Set<string>` - Include specific additional properties
+
+### 2. Style Properties
+
+Style properties allow direct styling without using the `styles` prop. Use predefined style property sets from `/src/tasty/styles/list.ts`:
+
+```tsx
+import {
+  CONTAINER_STYLES,
+  ContainerStyleProps,
+  BASE_STYLES,
+  BaseStyleProps,
+  TEXT_STYLES,
+  TextStyleProps,
+  extractStyles,
+} from '@tenphi/tasty';
+
+interface MyComponentProps 
+  extends AllBaseProps,
+    ContainerStyleProps,  // All container styles
+    TextStyleProps {      // Text-specific styles
+  // Component-specific props
+}
+
+function MyComponent(props: MyComponentProps) {
+  const styles = extractStyles(props, [...CONTAINER_STYLES, ...TEXT_STYLES]);
+  
+  return <Element styles={styles} />;
+}
+```
+
+**Available style property sets:**
+
+- `BASE_STYLES` - `display`, `font`, `preset`, `hide`, `opacity`, `whiteSpace`
+- `POSITION_STYLES` - `gridArea`, `order`, `margin`, `inset`, `position`, `zIndex`, etc.
+- `BLOCK_STYLES` - `padding`, `border`, `radius`, `shadow`, `overflow`, etc.
+- `COLOR_STYLES` - `color`, `fill`, `fade`
+- `TEXT_STYLES` - `textTransform` (for other text styling, use `preset`)
+- `DIMENSION_STYLES` - `width`, `height`, `flex`, `flexBasis`, etc.
+- `FLOW_STYLES` - `flow`, `gap`, `align`, `justify`, `gridColumns`, etc.
+- `CONTAINER_STYLES` - Combination of all above styles
+- `OUTER_STYLES` - Position and dimension styles only
+
+### 3. Modifiers (`mods`) Property
+
+Modifiers enable state-based styling through the `mods` prop, which creates `data-*` attributes:
+
+```tsx
+interface MyComponentProps extends AllBaseProps {
+  isLoading?: boolean;
+}
+
+function MyComponent({ isLoading, mods, ...props }: MyComponentProps) {
+  return (
+    <Element
+      mods={{
+        loading: isLoading,
+        ...mods, // Allow external mods to override
+      }}
+      styles={{
+        color: {
+          '': '#dark',
+          loading: '#gray',
+          'loading & hovered': '#light-gray',
+        }
+      }}
+    />
+  );
+}
+```
+
+**Usage:**
+```tsx
+<MyComponent mods={{ custom: true, highlighted: isHighlighted }} />
+// Renders: <div data-custom data-highlighted class="...">
+```
+
+### 4. Sub-elements for Targeted Styling
+
+Sub-elements allow styling inner parts through the main `styles` prop. They automatically inherit the parent's state and modifiers, making them ideal for tightly coupled UI elements.
+
+```tsx
+const MyElement = tasty({
+  styles: {
+    display: 'flex',
+    gap: '1x',
+    
+    // Sub-element styles
+    Icon: {
+      preset: 'h3',
+      color: '#purple',
+    },
+    Label: {
+      preset: 'default bold',
+    },
+  },
+});
+
+function MyComponent(props) {
+  return (
+    <MyElement {...props}>
+      <span data-element="Icon">🎉</span>
+      <span data-element="Label">{props.children}</span>
+    </MyElement>
+  );
+}
+```
+
+**Usage with style overrides:**
+```tsx
+<MyComponent
+  styles={{
+    Icon: { color: '#red' },      // Override icon color
+    Label: { preset: 'h4' }, // Override label size
+  }}
+>
+  Custom styled content
+</MyComponent>
+```
+
+**When to use sub-elements:**
+- Elements that should share the parent's state (hover, focus, disabled, etc.)
+- Tightly coupled UI parts (icon + label, title + subtitle)
+- When you want a single `styles` prop to control everything
+- Simpler components with predictable inner structure
+
+### 5. Additional Style Properties
+
+Create dedicated style properties for styling inner elements independently. This approach gives more control and allows inner elements to have their own state.
+
+```tsx
+import { Styles } from '@tenphi/tasty';
+
+interface MyComponentProps extends AllBaseProps {
+  styles?: Styles;
+  iconStyles?: Styles; // Additional style property
+  labelStyles?: Styles; // Another additional style property
+}
+
+function MyComponent({ iconStyles, labelStyles, ...props }: MyComponentProps) {
+  const styles = extractStyles(props, CONTAINER_STYLES);
+  
+  return (
+    <Element styles={styles}>
+      <IconElement styles={iconStyles} />
+      <LabelElement styles={labelStyles} />
+    </Element>
+  );
+}
+```
+
+**When to use additional style properties:**
+- Inner elements need independent state management (separate hover, focus behaviors)
+- Complex components with multiple logical sections
+- Components that need fine-grained styling control
+- When different parts of the component might have different interaction patterns
+
+### 6. React Aria Integration
+
+Use React Aria hooks for accessibility and behavior:
+
+```tsx
+import { useButton } from 'react-aria';
+import { useRef } from 'react';
+
+function MyButton(props) {
+  const ref = useRef();
+  const { buttonProps } = useButton(props, ref);
+  
+  return (
+    <Element
+      {...buttonProps}
+      ref={ref}
+      styles={extractStyles(props, CONTAINER_STYLES)}
+    />
+  );
+}
+```
+
+## Examples
+
+### Example 1: Block Component (Basic)
+
+This demonstrates a basic component with:
+- Base properties support
+- All container style properties
+- Clean, minimal implementation
+
+```tsx
+import { forwardRef } from 'react';
+import {
+  AllBaseProps,
+  CONTAINER_STYLES,
+  ContainerStyleProps,
+  extractStyles,
+  filterBaseProps,
+  tasty,
+} from '@tenphi/tasty';
+
+const BlockElement = tasty({
+  styles: {
+    display: 'block',
+  },
+});
+
+export interface CubeBlockProps
+  extends Omit<AllBaseProps, keyof ContainerStyleProps | 'as'>,
+    ContainerStyleProps {}
+
+export const Block = forwardRef(function Block(props: CubeBlockProps, ref) {
+  const styles = extractStyles(props, CONTAINER_STYLES);
+
+  return (
+    <BlockElement
+      {...filterBaseProps(props, { eventProps: true })}
+      ref={ref}
+      styles={styles}
+    />
+  );
+});
+```
+
+### Example 2: Action Component (Advanced)
+
+This demonstrates advanced features:
+- React Aria integration (`useButton`)
+- Complex modifier handling
+- Multiple style property sets
+- Custom behavior logic
+
+```tsx
+import { FocusableRef } from '@react-types/shared';
+import { forwardRef } from 'react';
+import { AriaButtonProps, useButton, useHover } from 'react-aria';
+import {
+  AllBaseProps,
+  BaseStyleProps,
+  CONTAINER_STYLES,
+  ContainerStyleProps,
+  extractStyles,
+  Styles,
+  TagName,
+  tasty,
+  TEXT_STYLES,
+  TextStyleProps,
+} from '@tenphi/tasty';
+
+export interface CubeActionProps<T extends TagName = 'button'>
+  extends Omit<AllBaseProps<T>, 'htmlType'>,
+    BaseStyleProps,
+    ContainerStyleProps,
+    TextStyleProps,
+    Omit<AriaButtonProps, 'type'> {
+  to?: string;
+  label?: string;
+  htmlType?: 'button' | 'submit' | 'reset';
+}
+
+const DEFAULT_ACTION_STYLES: Styles = {
+  recipe: 'reset button',
+  position: 'relative',
+  preset: 'inherit',
+  outline: {
+    '': '#purple-03.0',
+    focused: '#purple-03',
+  },
+  transition: 'theme',
+  cursor: '$pointer',
+} as const;
+
+const ActionElement = tasty({
+  as: 'button',
+  styles: DEFAULT_ACTION_STYLES,
+});
+
+const STYLE_PROPS = [...CONTAINER_STYLES, ...TEXT_STYLES];
+
+export const Action = forwardRef(function Action(
+  {
+    to,
+    as = 'button',
+    htmlType,
+    label,
+    theme,
+    mods,
+    onPress,
+    isDisabled,
+    ...props
+  }: CubeActionProps,
+  ref: FocusableRef<HTMLElement>,
+) {
+  const domRef = useRef();
+  const { buttonProps, isPressed } = useButton(
+    {
+      'aria-label': label,
+      onPress,
+      isDisabled,
+      ...props,
+    },
+    domRef,
+  );
+  
+  const { hoverProps, isHovered } = useHover({ isDisabled });
+
+  const styles = extractStyles(props, STYLE_PROPS);
+
+  return (
+    <ActionElement
+      data-theme={theme}
+      {...buttonProps}
+      {...hoverProps}
+      mods={{
+        hovered: isHovered && !isDisabled,
+        pressed: isPressed && !isDisabled,
+        disabled: isDisabled,
+        ...mods, // Allow external mods to override
+      }}
+      ref={domRef}
+      type={htmlType || 'button'}
+      as={as}
+      styles={styles}
+    />
+  );
+});
+```
+
+## Form Integration
+
+For input components that need to integrate with forms, see the [Field documentation](./components/form/Field.md) for comprehensive guidance on:
+
+- Form state management
+- Validation integration  
+- Label and help text handling
+- Error state management
+- Accessibility requirements for form controls
+
+## Best Practices
+
+1. **Always support base properties**: Use `filterBaseProps` and extend `AllBaseProps`
+
+2. **Provide appropriate style properties**: Choose the right combination of style property sets for your component's needs
+
+3. **Design for extensibility**: Allow `mods` overrides and provide additional style properties for inner elements
+
+4. **Use React Aria**: Integrate appropriate React Aria hooks for accessibility and standard behavior
+
+5. **Follow naming conventions**: Use `Cube[ComponentName]Props` for interfaces and descriptive names for sub-elements
+
+6. **Document sub-elements**: Clearly document what sub-elements are available for styling
+
+7. **Keep it simple when appropriate**: Not every component needs all features - use what makes sense for your use case
+
+## Component Checklist
+
+When creating a new component, consider:
+
+- [ ] Base properties support (`AllBaseProps`, `filterBaseProps`)
+- [ ] Appropriate style property sets
+- [ ] Modifier (`mods`) support for state-based styling  
+- [ ] Additional style properties for inner elements
+- [ ] Sub-element definitions for targeted styling
+- [ ] React Aria integration for accessibility
+- [ ] TypeScript interfaces following naming conventions
+- [ ] forwardRef for ref passing
+- [ ] Default styles and theme support
+- [ ] Documentation following UI Kit standards
+
+Remember: Start simple and add features as needed. A basic, working component is better than an over-engineered one!

package/docs/Introduction.md

@@ -0,0 +1,122 @@
+# Welcome to Cube Cloud UI Kit
+
+A comprehensive React component library built for modern web applications with accessibility, theming, and developer experience at its core.
+
+## What is Cube UI Kit?
+
+Cube UI Kit is a complete design system that provides:
+- **Accessible Components** - Built with React Aria hooks for WCAG compliance
+- **Powerful Styling System** - The `tasty` style system for maintainable, theme-able components
+- **Form Management** - Integrated form handling with validation and state management
+- **Consistent Design** - Unified visual language across all components
+
+Browse example stories by navigating to them in the sidebar to see components in action.
+
+## Key Features
+
+### 🎨 Tasty Style System
+A declarative styling approach that makes it easy to create consistent, maintainable styles:
+- **State-based styling** - Bind styles to hover, focus, and custom modifiers
+- **Responsive design** - Use arrays for breakpoint-specific styles
+- **Token-based theming** - Built-in color tokens and semantic units
+- **Component variants** - Pre-defined style variations for different use cases
+
+### ♿ Accessibility First
+Every component is built with accessibility as a priority:
+- React Aria hooks provide keyboard navigation and screen reader support
+- ARIA attributes are automatically managed
+- Focus management follows best practices
+- High contrast and reduced motion support
+
+### 📝 Modern Form Handling
+Streamlined form development with built-in field support:
+- All input components have integrated field properties
+- Automatic validation and error handling
+- Form-level configuration inheritance
+- No wrapper components needed for most use cases
+
+## Getting Started
+
+### Basic Usage
+
+```jsx
+import { Button, TextInput, Form } from '@cube-dev/ui-kit';
+
+function MyApp() {
+  return (
+    <Form onSubmit={handleSubmit}>
+      <TextInput
+        name="email"
+        label="Email"
+        type="email"
+        isRequired
+      />
+      <Button type="primary">Submit</Button>
+    </Form>
+  );
+}
+```
+
+### Styling Components
+
+Use the `tasty` system for consistent styling:
+
+```jsx
+import { tasty, Button } from '@cube-dev/ui-kit';
+
+const CustomButton = tasty(Button, {
+  styles: {
+    padding: '2x 4x',
+    fill: {
+      '': '#purple',
+      hovered: '#purple.8',
+    },
+    color: '#white',
+  },
+});
+```
+
+## Core Concepts
+
+### Styling with Tasty
+
+The `tasty` style system provides a powerful, declarative way to style components:
+
+- **Custom Units** - Use semantic units like `2x` (gap), `1r` (radius), `#purple` (color tokens)
+- **State Bindings** - Style different states using modifiers like `hovered`, `focused`, `disabled`
+- **Responsive Arrays** - Define breakpoint-specific styles with arrays: `padding: ['4x', '2x', '1x']`
+- **Sub-element Styling** - Style internal component parts using element names
+
+### Form Integration
+
+All input components work seamlessly with the Form component:
+
+- **Built-in Field Support** - No wrapper components needed
+- **Automatic Validation** - Validation rules and error display
+- **Form-level Configuration** - Inherit settings like `labelPosition` and `validationState`
+- **Programmatic Control** - Use `Form.useForm()` for advanced form management
+
+### Component Architecture
+
+Components are designed with composition and reusability in mind:
+
+- **Base Properties** - Common props like `qa`, styling, and accessibility
+- **Style Properties** - Direct style application without the `styles` prop
+- **Modifiers** - Control component states through the `mods` prop
+- **Variants** - Pre-defined style themes and sizes
+
+## Documentation Structure
+
+Each component includes comprehensive documentation:
+
+- **Usage Examples** - Real-world implementation patterns
+- **Accessibility Guidelines** - Keyboard navigation and screen reader support
+- **Styling Reference** - Available sub-elements and modifiers
+- **Best Practices** - Recommended usage patterns and common pitfalls
+
+## Next Steps
+
+1. **Explore Components** - Browse the sidebar to see all available components
+2. **Learn Tasty** - Visit the [Tasty documentation](./tasty/usage.md) to master the styling system
+3. **Build Forms** - Check out [Form documentation](./components/form/Form.md) for form development patterns
+4. **Accessibility** - Review accessibility guidelines for inclusive design

package/docs/RenderCache.md

@@ -0,0 +1,172 @@
+# RenderCache
+
+RenderCache is a performance optimization component that caches rendered React elements and only re-renders specific items when needed. It's useful for lists where most items remain unchanged but you need fine-grained control over which items to re-render.
+
+## When to Use
+
+- When rendering lists where only specific items need to re-render based on state changes
+- When child components are expensive to render and don't need to update on every parent re-render
+- When you want more control than React.memo provides, with explicit per-item cache invalidation
+- When building complex UI where selective re-rendering improves performance significantly
+
+## Component
+
+---
+
+### Properties
+
+### Property Details
+
+- **items**: Array of items to render
+- **renderKeys**: Array of keys that should trigger re-render. Only items with keys in this array will be re-rendered
+- **getKey**: Function that extracts a unique key from each item
+- **children**: Render function that takes an item and returns a React element
+
+### Base Properties
+
+This is a headless component and does not support base properties.
+
+## How It Works
+
+The component maintains an internal cache of rendered elements. When rendering:
+
+1. For each item, it checks if the item's key is in renderKeys
+2. If the key is in renderKeys or the item hasn't been rendered before, it calls the children function to render/re-render
+3. Otherwise, it returns the cached element from the previous render
+4. It automatically cleans up cache entries for items that are no longer in the list
+
+## Examples
+
+### Basic Usage
+
+```jsx
+import { RenderCache } from '@cube-dev/ui-kit';
+
+const items = [
+  { id: 1, name: 'Item 1' },
+  { id: 2, name: 'Item 2' },
+  { id: 3, name: 'Item 3' },
+];
+
+const [selectedId, setSelectedId] = useState(1);
+
+<RenderCache
+  items={items}
+  renderKeys={[selectedId]}
+  getKey={(item) => item.id}
+>
+  {(item) => <ExpensiveItem item={item} isSelected={item.id === selectedId} />}
+</RenderCache>
+```
+
+### With List of Expensive Components
+
+```jsx
+import { RenderCache } from '@cube-dev/ui-kit';
+
+function ExpensiveListItem({ item, isActive }) {
+  // Complex rendering logic
+  return <div className={isActive ? 'active' : ''}>{item.name}</div>;
+}
+
+const [activeId, setActiveId] = useState(1);
+
+<RenderCache
+  items={data}
+  renderKeys={[activeId]}
+  getKey={(item) => item.id}
+>
+  {(item) => (
+    <ExpensiveListItem 
+      item={item} 
+      isActive={item.id === activeId}
+    />
+  )}
+</RenderCache>
+```
+
+## Performance Considerations
+
+- **Cache management**: The component uses useRef to maintain the cache across renders, avoiding unnecessary re-allocations
+- **Automatic cleanup**: Removes cached entries for items no longer in the list to prevent memory leaks
+- **Selective invalidation**: Only items with keys in renderKeys are re-rendered, others use cached elements
+- **Best for expensive renders**: Most effective when child components have significant render cost
+
+## Best Practices
+
+1. **Use stable keys**: Ensure getKey returns consistent keys for the same items across renders
+   ```jsx
+   // Good: Using stable IDs
+   <RenderCache
+     items={items}
+     getKey={(item) => item.id}
+     renderKeys={[selectedId]}
+   >
+     {(item) => <Item {...item} />}
+   </RenderCache>
+   
+   // Bad: Using indices (unstable when list changes)
+   <RenderCache
+     items={items}
+     getKey={(item, index) => index}
+     renderKeys={[selectedIndex]}
+   >
+     {(item) => <Item {...item} />}
+   </RenderCache>
+   ```
+
+2. **Minimize renderKeys**: Only include keys that truly need re-rendering to maximize cache benefits
+   ```jsx
+   // Good: Only re-render the active item
+   <RenderCache
+     items={items}
+     renderKeys={[activeItemId]}
+     getKey={(item) => item.id}
+   >
+     {(item) => <Item {...item} />}
+   </RenderCache>
+   
+   // Bad: Re-rendering all items defeats the purpose
+   <RenderCache
+     items={items}
+     renderKeys={items.map(item => item.id)}
+     getKey={(item) => item.id}
+   >
+     {(item) => <Item {...item} />}
+   </RenderCache>
+   ```
+
+3. **Consider alternatives**: For simple cases, React.memo might be sufficient and simpler
+
+4. **Profile first**: Use React DevTools Profiler to confirm you have a performance issue before adding this optimization
+
+5. **Avoid inline functions**: Use stable render functions to prevent unnecessary cache invalidation
+   ```jsx
+   // Good: Stable render function
+   const renderItem = useCallback((item) => (
+     <ExpensiveItem item={item} />
+   ), []);
+   
+   <RenderCache
+     items={items}
+     renderKeys={[selectedId]}
+     getKey={(item) => item.id}
+   >
+     {renderItem}
+   </RenderCache>
+   ```
+
+## When NOT to Use
+
+- **Simple lists**: For simple lists without performance issues, regular rendering is simpler
+- **All items update frequently**: If all items need to re-render on every change, the cache overhead isn't worth it
+- **Small lists**: Lists with < 10 items typically don't benefit from caching
+- **Simple components**: If child components render quickly, the optimization overhead may outweigh benefits
+
+## Related Components
+
+- **React.memo** - For simple component memoization
+- **useMemo** - For memoizing computed values
+- **useCallback** - For memoizing callback functions
+- **DisplayTransition** - For animating component mount/unmount
+