@cube-dev/ui-kit 0.121.2 → 0.121.3

package/docs/CreateComponent.md

@@ -44,30 +44,73 @@ function MyComponent(props: MyComponentProps) {
 
 ### 2. Style Properties
 
-Style properties allow direct styling without using the `styles` prop. Use predefined style property sets from `/src/tasty/styles/list.ts`:
+Style properties allow consumers to apply layout and styling directly as component props. There are two approaches:
+
+**Approach A — `styleProps` on `tasty()`** (simpler, when rest props go directly to the tasty element):
+
+`styleProps` tells tasty which CSS properties the component accepts as typed React props. The component still needs to declare the matching TypeScript interfaces so consumers get autocomplete. This works when rest props are spread directly onto the tasty element.
+
+```tsx
+import { tasty, BaseProps, OUTER_STYLES, CONTAINER_STYLES } from '@tenphi/tasty';
+import type { OuterStyleProps, ContainerStyleProps } from '@tenphi/tasty';
+
+interface CubeMyComponentProps extends BaseProps, OuterStyleProps, ContainerStyleProps {
+  label?: string;
+  isDisabled?: boolean;
+}
+
+const MyElement = tasty({
+  qa: 'MyComponent',
+  styles: {
+    display: 'flex',
+    flow: 'column',
+    padding: '2x',
+    fill: '#surface',
+    radius: '1r',
+    border: {
+      '': '#border',
+      disabled: '#border.5',
+    },
+  },
+  styleProps: [...OUTER_STYLES, ...CONTAINER_STYLES],
+});
+
+function MyComponent({ label, isDisabled, ...props }: CubeMyComponentProps) {
+  return (
+    <MyElement {...props} mods={{ disabled: isDisabled }}>
+      {label}
+    </MyElement>
+  );
+}
+```
+
+**Approach B — `extractStyles` + `filterBaseProps`** (when you need to split props between multiple elements or add custom logic):
 
 ```tsx
 import {
   CONTAINER_STYLES,
   ContainerStyleProps,
-  BASE_STYLES,
-  BaseStyleProps,
   TEXT_STYLES,
   TextStyleProps,
   extractStyles,
+  filterBaseProps,
 } from '@tenphi/tasty';
 
 interface MyComponentProps 
   extends AllBaseProps,
-    ContainerStyleProps,  // All container styles
-    TextStyleProps {      // Text-specific styles
-  // Component-specific props
+    ContainerStyleProps,
+    TextStyleProps {
 }
 
 function MyComponent(props: MyComponentProps) {
   const styles = extractStyles(props, [...CONTAINER_STYLES, ...TEXT_STYLES]);
   
-  return <Element styles={styles} />;
+  return (
+    <Element
+      {...filterBaseProps(props, { eventProps: true })}
+      styles={styles}
+    />
+  );
 }
 ```
 
@@ -378,7 +421,7 @@ For input components that need to integrate with forms, see the [Field documenta
 
 ## Best Practices
 
-1. **Always support base properties**: Use `filterBaseProps` and extend `AllBaseProps`
+1. **Always support base properties**: Use `styleProps` (recommended) or `filterBaseProps`, and extend `AllBaseProps`
 
 2. **Provide appropriate style properties**: Choose the right combination of style property sets for your component's needs
 
@@ -392,6 +435,20 @@ For input components that need to integrate with forms, see the [Field documenta
 
 7. **Keep it simple when appropriate**: Not every component needs all features - use what makes sense for your use case
 
+8. **Use named React imports**: Import `useCallback`, `useState`, `forwardRef` etc. directly from `'react'` instead of using `React.useCallback(...)`.
+
+9. **Use `useEvent` for stable callbacks**: When a callback doesn't need to trigger re-renders, prefer `useEvent` from `src/_internal/hooks/use-event` for a stable identity that always calls the latest implementation:
+
+```tsx
+import { useEvent } from '../_internal/hooks/use-event';
+
+const handleClick = useEvent((e) => {
+  // always has latest closure, but stable identity
+});
+```
+
+10. **Use `variants` for theming, not sizing**: The `variants` option in `tasty()` defines mutually exclusive visual variations (e.g. `default`, `danger`, `outline`). CSS is only generated for variants actually rendered at runtime. Use modifiers for dimensions like `size`.
+
 ## Component Checklist
 
 When creating a new component, consider:

package/docs/Usage.md

@@ -0,0 +1,304 @@
+# Usage Guide
+
+This guide covers the design system foundations — tokens, presets, colors, units, and patterns — needed to build and maintain components in Cube UI Kit.
+
+For styling engine internals see the [Tasty documentation](./tasty/usage.md). Tasty docs are also bundled with this package in `docs/tasty/`:
+
+- **usage.md** — `tasty()` component creation, state mappings, sub-elements, variants, extending components, hooks.
+- **configuration.md** — `configure()` options: tokens, recipes, custom units, style handlers, TypeScript module augmentation.
+- **styles.md** — Complete reference for all enhanced style properties (`fill`, `flow`, `preset`, `border`, `radius`, `transition`, etc.).
+- **debug.md** — `tastyDebug` runtime API for inspecting injected CSS and troubleshooting.
+- **injector.md** — Low-level style injector: `inject()`, `injectGlobal()`, deduplication, SSR.
+- **tasty-static.md** — Zero-runtime `tastyStatic()`, Babel plugin, Next.js/Vite integration.
+
+## Units
+
+Tasty provides custom units that map to CSS custom properties defined on the Root component. Use these instead of raw pixel values to keep styling consistent.
+
+| Unit | CSS Variable | Example | Computed (defaults) |
+|------|-------------|---------|---------------------|
+| `x` | `var(--gap)` | `2x` → `calc(var(--gap) * 2)` | 16px |
+| `r` | `var(--radius)` | `1r` → `var(--radius)` | 6px |
+| `cr` | `var(--card-radius)` | `1cr` → `var(--card-radius)` | 10px |
+| `bw` | `var(--border-width)` | `1bw` → `var(--border-width)` | 1px |
+| `ow` | `var(--outline-width)` | `1ow` → `var(--outline-width)` | 3px |
+
+## Base Tokens
+
+These CSS custom properties are defined in `src/tokens/base.ts` and applied globally.
+
+| Token | Default | Description |
+|-------|---------|-------------|
+| `$gap` | `8px` | Base spacing unit (used with `x` multiplier) |
+| `$radius` | `6px` | Base border radius (used with `r` multiplier) |
+| `$border-width` | `1px` | Base border width (used with `bw` multiplier) |
+| `$outline-width` | `3px` | Focus outline width (used with `ow` multiplier) |
+| `$stroke-width` | `1.5` | Icon stroke width |
+| `$disabled-opacity` | `0.4` | Opacity for disabled elements |
+| `$transition` | `80ms` | Default transition duration |
+| `$disclosure-transition` | `120ms` | Disclosure animation duration |
+| `$tab-transition` | `120ms` | Tab animation duration |
+| `$fade-transition` | `200ms` | Fade animation duration |
+| `$large-radius` | `(1r + .5x)` | Larger radius for cards/dialogs |
+| `$card-radius` | `(1r + .5x)` | Card border radius |
+| `$min-dialog-size` | `min(288px, calc(100vw - 2*var(--gap)))` | Minimum dialog width |
+
+## Spacing Tokens
+
+Defined in `src/tokens/spacing.ts`. Values use the `x` unit.
+
+| Token | Value | Computed (gap=8px) |
+|-------|-------|-------------------|
+| `$space-xs` | `0.5x` | 4px |
+| `$space-sm` | `0.75x` | 6px |
+| `$space-md` | `1x` | 8px |
+| `$space-lg` | `1.5x` | 12px |
+| `$space-xl` | `2x` | 16px |
+
+## Size Tokens
+
+Defined in `src/tokens/sizes.ts`. Used for component heights and icon sizes.
+
+| Token | Value |
+|-------|-------|
+| `$size-xs` | `24px` |
+| `$size-sm` | `28px` |
+| `$size-md` | `32px` |
+| `$size-lg` | `40px` |
+| `$size-xl` | `48px` |
+
+## Shadow Tokens
+
+Defined in `src/tokens/shadows.ts`.
+
+| Token | Value |
+|-------|-------|
+| `$item-shadow` | `0 1bw 0.375x #dark.15` |
+| `$card-shadow` | `0 0.5x 2x #shadow` |
+| `$dialog-shadow` | `0 1x 4x #dark.15` |
+
+## Layout Tokens
+
+Defined in `src/tokens/layout.ts`.
+
+| Token | Value |
+|-------|-------|
+| `$max-content-width` | `1440px` |
+| `$topbar-height` | `48px` |
+| `$sidebar-width` | `200px` |
+
+## Color Tokens
+
+All color tokens use `#name` syntax in styles. Opacity variants use `#name.NN` (e.g. `#dark.06` for 6% opacity). Defined in `src/tokens/colors.ts`.
+
+### Base Colors
+
+| Token | Description |
+|-------|-------------|
+| `#white`, `#black`, `#clear` | Absolute white, black, and transparent |
+| `#text` | Default text color |
+| `#border` | Default border color |
+| `#placeholder` | Input placeholder text |
+| `#shadow` | Shadow color |
+| `#minor` | Secondary/muted text |
+| `#focus` | Focus ring color |
+| `#pink` | Accent pink |
+| `#light` | Light background |
+
+### Semantic Color Groups
+
+Each semantic group provides a base color and variants following the pattern: `#name`, `#name-text`, `#name-bg`, `#name-icon`, `#name-desaturated`, `#name-disabled`.
+
+| Group | Hue | Purpose |
+|-------|-----|---------|
+| `#primary` / `#purple` | 280.3° | Primary actions, brand color |
+| `#danger` | 23.1° | Errors, destructive actions |
+| `#success` | 156.9° | Success states, confirmations |
+| `#warning` | 84.3° | Warning states, caution |
+| `#note` | 302.3° | Informational notes |
+
+### Neutral Scales
+
+**Dark scale:** `#dark`, `#dark-01` through `#dark-05`, `#dark-bg` — six-step neutral scale from near-black to light gray.
+
+**Purple scale:** `#purple-01` through `#purple-04` — additional purple shades for gradients and accents.
+
+### Disabled Colors
+
+`#disabled`, `#disabled-text`, `#disabled-bg` — dedicated colors for disabled UI elements.
+
+## Typography Presets
+
+Use via the `preset` style property. Modifiers can be appended with a space: `'t1 strong'`, `'h2 italic'`.
+
+Defined in `src/tokens/typography.ts`.
+
+### Headings
+
+| Preset | Size | Line Height | Weight |
+|--------|------|-------------|--------|
+| `h1` | 36px | 44px | 600 |
+| `h2` | 24px | 32px | 600 |
+| `h3` | 20px | 28px | 600 |
+| `h4` | 18px | 24px | 600 |
+| `h5` | 16px | 22px | 600 |
+| `h6` | 14px | 20px | 600 |
+
+### Text
+
+| Preset | Size | Line Height | Weight | Notes |
+|--------|------|-------------|--------|-------|
+| `t1` | 18px | 24px | 400 | |
+| `t2` | 16px | 22px | 400 | |
+| `t2m` | 16px | 22px | 500 | Medium weight variant |
+| `t3` | 14px | 20px | 400 | Base text size |
+| `t3m` | 14px | 20px | 500 | Medium weight variant |
+| `t4` | 12px | 18px | 500 | Small text |
+| `t4m` | 12px | 18px | 600 | Small text, semi-bold |
+
+### Paragraph
+
+Paragraph presets have slightly increased line heights compared to text presets at the same size, optimized for multi-line reading.
+
+| Preset | Size | Line Height | Weight |
+|--------|------|-------------|--------|
+| `p1` | 18px | 28px | 400 |
+| `p2` | 16px | 24px | 400 |
+| `p3` | 14px | 22px | 400 |
+| `p4` | 12px | 20px | 500 |
+
+### Markdown / Prose
+
+Largest line heights, designed for long-form content blocks.
+
+| Preset | Size | Line Height | Weight |
+|--------|------|-------------|--------|
+| `m1` | 18px | 32px | 400 |
+| `m2` | 16px | 28px | 400 |
+| `m3` | 14px | 24px | 400 |
+
+### Special Presets
+
+| Preset | Description |
+|--------|-------------|
+| `c1` | 14px, weight 600, uppercase — section captions |
+| `c2` | 12px, weight 600, uppercase — small captions |
+| `tag` | 12px, weight 600 — tag/badge text |
+| `strong` | Inherits everything, applies bold weight |
+| `em` | Inherits everything, applies italic style |
+| `default` | Aliases `t3` values — the base text style |
+
+## Themes
+
+Component themes are set via the `theme` prop or `theme=name` modifier:
+
+| Theme | Purpose |
+|-------|---------|
+| `default` | Standard appearance |
+| `danger` | Destructive / error actions |
+| `special` | Highlighted / promoted actions |
+| `success` | Success / positive states |
+| `warning` | Warning / caution states |
+| `note` | Informational / note states |
+
+## Recipes
+
+Reusable style presets applied via the `recipe` style property. Defined in `src/components/Root.tsx`.
+
+| Recipe | Purpose |
+|--------|---------|
+| `reset` | Zero out margin, padding, border, outline; set `box-sizing: border-box` |
+| `button` | Base button appearance: no native styling, `touch-action: manipulation` |
+| `input` | Base input appearance: no native styling, inherit color |
+| `input-autofill` | Handle `:-webkit-autofill` styling |
+| `input-placeholder` | Placeholder text styling via `-webkit-text-fill-color` |
+| `input-search-cancel-button` | Hide native search cancel button |
+
+## Common Modifiers
+
+These are data-attribute modifiers used in component style maps (via the `mods` prop):
+
+| Modifier | Description |
+|----------|-------------|
+| `disabled` | Disabled state |
+| `hovered` | Hover state |
+| `focused` | Focus state |
+| `pressed` | Active/pressed state |
+| `selected` | Selected state |
+| `checked` | Checked state (checkbox, switch) |
+| `invalid` | Invalid validation state |
+| `valid` | Valid validation state |
+| `indeterminate` | Indeterminate state |
+| `collapsed` | Collapsed state |
+| `type=primary` | Primary variant |
+| `type=outline` | Outline variant |
+| `size=small` / `size=medium` / `size=large` | Size modifiers |
+
+## State Syntax
+
+In style value maps, keys define when styles apply. States can be combined with boolean logic:
+
+```jsx
+fill: {
+  '': '#surface',              // default
+  ':hover': '#surface-hover',  // pseudo-class
+  disabled: '#disabled-bg',    // data-attribute modifier
+  'type=danger': '#danger',    // data-attribute with value
+  '@media(w < 768px)': '...',  // media query
+  '@(panel, w >= 300px)': '...', // container query
+  'disabled & :hover': '...',  // combined with AND
+  'a | b': '...',              // combined with OR
+  '!disabled': '...',          // negated
+}
+```
+
+## Icons
+
+Icons live in `src/icons/`. Use existing icons when possible; otherwise use `@tabler/icons-react`.
+
+- **`<Icon>`** — wrapper component for sizing and coloring icons. Props: `size`, `stroke`, plus style props.
+- **`wrapIcon(name, icon)`** — creates a Cube icon component from a tabler icon.
+- Always wrap tabler icons with `<Icon>` for custom size/color. Never add props directly to tabler icons.
+- To add new icons run: `pnpm add-icons`
+
+## Form System
+
+### Form Component
+
+`<Form>` wraps a native `<form>` and provides validation context:
+
+```jsx
+const [form] = useForm();
+
+<Form form={form} onSubmit={(data) => save(data)}>
+  <TextInput name="email" label="Email" rules={[{ required: true }, { type: 'email' }]} />
+  <SubmitButton>Save</SubmitButton>
+</Form>
+```
+
+### useForm Hook
+
+Returns a `CubeFormInstance` with:
+
+- **Get/Set:** `getFieldValue`, `setFieldValue`, `getFieldsValue`, `setFieldsValue`, `getFormData`
+- **Validation:** `validateField`, `validateFields`, `resetFieldsValidation`
+- **State queries:** `isFieldValid`, `isFieldInvalid`, `isFieldTouched`, `isValid`, `isDirty`
+- **Errors:** `getFieldError`, `setFieldError`
+
+### Validation Rules
+
+Async rule-based system. Each rule is an object with one of these properties:
+
+| Rule | Description |
+|------|-------------|
+| `required` | Field must have a value |
+| `type` | Type check: `email`, `url`, `number`, `integer`, `date`, `hex`, etc. |
+| `pattern` | Regex pattern match |
+| `min` / `max` | Length or value constraints |
+| `enum` | List of allowed values |
+| `whitespace` | Must contain non-whitespace content |
+| `validator` | Custom async function: `(rule, value) => Promise<void>` |
+
+### Field Integration
+
+Fields with a `name` prop inside `<Form>` automatically register with the form instance — no `<Field>` wrapper needed. The `useFieldProps` hook handles this internally.

package/docs/tasty/styles.md

@@ -489,33 +489,40 @@ If the name is not a semantic name, it is used as a literal CSS property name.
 
 ### `scrollbar`
 
-Cross-browser scrollbar styling. Sets Firefox (`scrollbar-width`, `scrollbar-color`) and WebKit (`::-webkit-scrollbar` pseudo-elements) properties.
+Scrollbar styling using CSS standard properties (`scrollbar-width`, `scrollbar-color`, `scrollbar-gutter`).
 
-**Syntax:** `[modifiers...] [size] [thumb-color] [track-color] [corner-color]`
+**Syntax:** `[width] [modifiers...] [thumb-color] [track-color]`
 
-**Modifiers:**
+**Width values** (controls `scrollbar-width`, default is `thin`):
+
+| Value | Effect |
+|-------|--------|
+| `thin` | Thin scrollbar (default) |
+| `auto` | Browser-default scrollbar width |
+| `none` | Hide scrollbar (still scrollable, no colors applied) |
+
+**Modifiers** (controls gutter and overflow behavior):
 
 | Modifier | Effect |
 |----------|--------|
-| `thin` | Thin scrollbar (`scrollbar-width: thin`) |
-| `none` | Hide scrollbar (still scrollable) |
-| `auto` | Browser-default scrollbar width |
 | `stable` | Reserve space for scrollbar (`scrollbar-gutter: stable`) |
 | `both-edges` | Reserve space on both sides (`scrollbar-gutter: stable both-edges`) |
 | `always` | Force scrollbars visible (`overflow: scroll` + `scrollbar-gutter: stable`) |
-| `styled` | Enhanced appearance with rounded thumb, transitions, and custom sizing |
 
-**Colors:** Up to 3 color values for thumb, track, and corner (optional).
+**Colors:** Up to 2 color values for thumb and track (optional), applied via `scrollbar-color`.
+
+**Defaults:** When no colors are specified, the thumb color comes from the `#scrollbar-thumb` token (`#text.5`) and the track color from the `#scrollbar-track` token (`#dark-bg`). These tokens are provided by the base token set. If the base tokens are not loaded, the track falls back to `transparent` via a CSS fallback, while the thumb has no CSS-level fallback — the browser treats the entire `scrollbar-color` declaration as invalid and reverts to the platform-default scrollbar appearance.
 
-**Defaults:** size = `8px`, thumb = `$scrollbar-thumb-color`, track = `transparent`, corner = same as track
+**Note:** `none` takes precedence over all other modifiers and colors. Combining `none` with other tokens (e.g., `"none always #red"`) produces a warning, and only `scrollbar-width: none` is applied.
 
 | Value | Effect |
 |-------|--------|
 | `true` | Thin scrollbar with default thumb/track colors |
 | `"none"` | Hidden scrollbar (still scrollable) |
-| `"thin 10px #purple.40 #dark.04"` | Thin, 10px, thumb `#purple.40`, track `#dark.04` |
-| `"styled 12px #purple.40 #dark.04 #white.10"` | Styled, 12px, thumb `#purple.40`, track `#dark.04`, corner `#white.10` |
-| `"always 8px #primary.50 #white.02"` | Always visible, 8px, thumb `#primary.50`, track `#white.02` |
+| `"thin #purple.40 #dark.04"` | Thin scrollbar with custom colors |
+| `"auto #red #blue"` | Browser-default width with custom colors |
+| `"always #primary.50 #white.02"` | Always visible with custom colors |
+| `"thin stable #red #blue"` | Thin, gutter reserved, custom colors |
 
 ### `fade`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.121.2",
+  "version": "0.121.3",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {
@@ -45,7 +45,7 @@
     "@react-types/shared": "^3.32.1",
     "@tabler/icons-react": "^3.31.0",
     "@tanstack/react-virtual": "^3.13.12",
-    "@tenphi/tasty": "0.8.0",
+    "@tenphi/tasty": "0.9.0",
     "clipboard-copy": "^4.0.1",
     "clsx": "^1.1.1",
     "diff": "^8.0.3",