@cube-dev/ui-kit 0.199.1 → 0.200.0

package/docs/Usage.md

@@ -46,13 +46,18 @@ These CSS custom properties are defined in `src/tokens/base.ts` and applied glob
 | `$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) |
+| `$outline-width` | `3px` | Width of a field's thick focus ring (used with `ow` multiplier) |
+| `$outline-offset` | `1px` | Gap between a focus outline and its element |
+| `$ring-width` | `1px` | Width of a hairline focus or selection ring |
+| `$item-gap` | `1px` | Hairline gap between adjacent items in a list, menu or action group |
 | `$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 |
+| `$overlay-transition` | `250ms` | Modal, tray and underlay enter/exit duration |
+| `$scrollbar-transition` | `150ms` | Auto-hiding (tiny) scrollbar fade duration |
 | `$large-radius` | `(1r + .5x)` | Larger radius for cards/dialogs |
 | `$card-radius` | `(1r + .5x)` | Card border radius |
 | `$dialog-max-size` | `calc(100dvw - 8x)`, `calc(100dvw - 4x)` up to 700px | Maximum dialog width |
@@ -88,7 +93,7 @@ Defined in `src/tokens/shadows.ts`. Shadow colors (`#shadow-sm`, `#shadow-md`, `
 
 | Token            | Value                     |
 | ---------------- | ------------------------- |
-| `$item-shadow`   | `0 1bw 0.375x #shadow-sm` |
+| `$item-shadow`   | `0 1px 0.375x #shadow-sm` |
 | `$card-shadow`   | `0 0.5x 2x #shadow-md`    |
 | `$shadow`        | `0 0.5x 2x #shadow-md`    |
 | `$dialog-shadow` | `0 1x 4x #shadow-lg`      |
@@ -400,6 +405,46 @@ Component themes are set via the `theme` prop or `theme=name` modifier:
 | `note` | Informational / note states |
 | `current` | No palette of its own — every color is mixed from the inherited text color (`#current`), so the component adopts whatever its container paints with. Supported by `Button`, `Item` (and `ItemButton`, `Item.Action`, `ItemBadge`) |
 
+## Customizing components
+
+Most components are a design contract: customize them through their own props (`type`, `theme`, `size`, …), `tokens` and `mods` rather than by restyling them. The layout and typography primitives (`Element`, `Block`, `Flex`, `Flow`, `Grid`, `Space`, `Prefix`, `Suffix`, `Text`, `TextItem`, `Title`, `Paragraph`, `Typography`, `ButtonGroup` and `Button.Group`), the `Action` base and the icons (including `IconSwitch`) are the exception: their `styles` are their API.
+
+The package's `tasty.config.ts` lists the other components as `protectedComponents`, and `tasty/no-protected-restyle` from `@tenphi/eslint-plugin-tasty` 1.12.0 or newer reports a restyle of one in your code:
+
+- instance `styles`, and every `*Styles` prop such as `inputStyles`;
+- style props other than the ones that place or size the component (`width`, `height`, `gridArea`, `margin`, `inset`, …). Containers (`Card`, `Panel`, `ResizablePanel`, `Content`, `Header`, `Footer`, and `Layout` and `GridLayout` with their sub-components) also keep the ones that lay out their content: `padding`, `gap`, `flow`, `place*`, `align*`, `justify*`, `grid*`, `overflow` and `scrollbar`. Root `styles` that sets only allowed props passes too;
+- `tasty()` wrappers that restyle a protected component, and wrappers of those wrappers.
+
+A component's own prop that shares a name with a style passes, such as a field's `direction` and `filter`, a text field's `resize`, `ColorSwatch`'s `color` or `AlertDialog`'s `content`.
+
+A sub-component counts as the component it hangs off, so `Button.Split` is protected like `Button`, and `Layout.Content` is a container like `Layout`. The list names the exceptions, such as `Button.Group`.
+
+To turn it on, extend the package's config and enable the rule:
+
+```ts
+// tasty.config.ts
+export default { extends: '@cube-dev/ui-kit' };
+```
+
+```jsonc
+// .oxlintrc.json
+{
+  "jsPlugins": [{ "name": "tasty", "specifier": "@tenphi/eslint-plugin-tasty" }],
+  "rules": { "tasty/no-protected-restyle": "warn" },
+}
+```
+
+An intended override takes a disable comment with its reason on the line before it. Among JSX children, only the `{/* … */}` form works:
+
+```tsx
+<Space>
+  {/* oxlint-disable-next-line tasty/no-protected-restyle -- the empty state's call to action takes the brand fill */}
+  <Button fill="#purple">Get started</Button>
+</Space>
+```
+
+With this rule on, `tasty/no-styles-prop` can stay off, so the primitives keep their `styles`.
+
 ## Recipes
 
 Reusable style presets applied via the `recipe` style property. Defined in `src/components/Root.tsx`.

package/docs/Utilities.md

@@ -146,13 +146,16 @@ function filterBaseProps(
 | Category | Examples |
 | --- | --- |
 | DOM ids | `id` |
-| Base props | `role`, `as`, `children`, `style`, `className`, `href`, `target`, `tabIndex`, `hidden`, `disabled` |
+| Base props | `role`, `title`, `as`, `children`, `style`, `className`, `href`, `target`, `tabIndex`, `hidden`, `disabled` |
+| Tasty props | `qa`, `qaVal`, `mods`, `tokens`, `theme` (rendered as `data-theme`), `isHidden`, `isDisabled`, `isChecked` |
 | ARIA attributes | `aria-label`, `aria-describedby`, etc. |
 | Data attributes | `data-qa`, `data-testid`, etc. |
 | Event handlers (opt-in) | `onClick`, `onFocus`, `onKeyDown`, etc. (when `eventProps: true`) |
 | Custom (opt-in) | Any prop name added to `opts.propNames` |
 
-Style props (`width`, `fill`, `padding`, `border`, etc.), tasty-specific props (`mods`, `qa`, `styles`), and React Aria interaction props (`onPress`, `onHoverStart`, `onHoverEnd`, `onPressStart`, `onPressEnd`) are filtered out.
+Style props (`width`, `fill`, `padding`, `border`, etc.), `styles`, and React Aria interaction props (`onPress`, `onHoverStart`, `onHoverEnd`, `onPressStart`, `onPressEnd`) are filtered out.
+
+An explicit prop written after the spread wins, so set a wrapper's own `tokens` or `theme` after `{...filterBaseProps(props)}`, or merge the `tokens` objects. A component whose own `theme` prop means something else (such as `Alert`'s status theme) takes it out before filtering.
 
 ### Usage
 

package/docs/components/GridProvider.md

@@ -11,9 +11,9 @@ Provides CSS custom properties for responsive grid column calculations. Children
 ## Properties
 
 - **`columns`** `number` (default: `2`) — Number of grid columns
-- **`gap`** `Styles['gap']` (default: `'0'`) — Gap between columns
-- **`width`** `Styles['width']` — Forced container width (bypasses auto-detection)
-- **`initialWidth`** `Styles['width']` — Initial width before resize observer kicks in
+- **`gap`** `string | number` (default: `0`) — Gap between columns, as a single Tasty value such as `'1x'`, or a number of pixels. A string needs a unit: `'0'` makes `--column-width` invalid
+- **`width`** `string | number` — Forced container width (bypasses auto-detection), as a single Tasty value or a number of pixels
+- **`initialWidth`** `string | number` — Initial width before resize observer kicks in, as a single Tasty value or a number of pixels
 
 ### CSS Custom Properties Provided
 

package/docs/components/content/HotKeys.md

@@ -95,11 +95,11 @@ The `inherit` type uses the current text color for the border and text, making i
 The inherit type is particularly useful when the HotKeys component needs to match the surrounding text color:
 
 ```jsx
-<div style={{ color: '#2563eb' }}>
+<Block color="#purple-text">
   <span>Press </span>
   <HotKeys type="inherit" aria-label="Search">mod+k</HotKeys>
   <span> to search</span>
-</div>
+</Block>
 ```
 
 ### Inside a Translation

package/docs/components/content/InlineInput.md

@@ -211,9 +211,9 @@ A common pattern: a `Select` is replaced by a styled `InlineInput` when the user
 When the value is wider than its container, the display text is truncated with an ellipsis. The full value is shown as a tooltip on hover/focus — no extra props required.
 
 ```jsx
-<div style={{ width: 200 }}>
+<Block width="25x">
   <InlineInput defaultValue="A very long inline value that gets truncated…" />
-</div>
+</Block>
 ```
 
 To always show a custom tooltip (regardless of overflow), pass a string. To disable the tooltip entirely, pass `false`:

package/docs/components/content/Item.md

@@ -405,17 +405,17 @@ By default, Item shows an auto tooltip when content overflows. The label and a s
 
 ```jsx
 {/* Auto tooltip on overflow (default) */}
-<Item style={{ width: '200px' }}>
+<Item width="25x">
   This is a very long text that will show a tooltip when overflowed
 </Item>
 
 {/* A truncated description shows in the tooltip too */}
-<Item description="participant.with.a.long.address@example-company.com" style={{ width: '200px' }}>
+<Item description="participant.with.a.long.address@example-company.com" width="25x">
   Jane Doe
 </Item>
 
 {/* Disable tooltip */}
-<Item tooltip={false} style={{ width: '200px' }}>
+<Item tooltip={false} width="25x">
   This text will be truncated without a tooltip
 </Item>
 
@@ -425,14 +425,14 @@ By default, Item shows an auto tooltip when content overflows. The label and a s
 </Item>
 
 {/* Auto tooltip with custom placement */}
-<Item tooltip={{ placement: 'right' }} style={{ width: '200px' }}>
+<Item tooltip={{ placement: 'right' }} width="25x">
   Long text with tooltip on the right when overflowed
 </Item>
 
 {/* Custom tooltip only on overflow */}
 <Item
   tooltip={{ title: 'Custom overflow tooltip', auto: true }}
-  style={{ width: '200px' }}
+  width="25x"
 >
   This shows custom tooltip only when text overflows
 </Item>

package/docs/components/content/Layout.md

@@ -394,14 +394,14 @@ A variant of Layout that enables CSS Grid for the content area.
 <GridLayout
   height="100dvh"
   columns="repeat(2, 1fr)"
-  rows="auto 1fr"
+  rows="auto auto 1fr"
   gap="2x"
   padding="2x"
 >
-  <Layout.Header title="Grid Dashboard" />
-  <div style={{ gridColumn: '1 / -1' }}>Full-width card</div>
-  <div>Left card</div>
-  <div>Right card</div>
+  <Layout.Header gridColumn="1 / 3" title="Grid Dashboard" />
+  <Card gridColumn="1 / 3">Full-width card</Card>
+  <Card>Left card</Card>
+  <Card>Right card</Card>
 </GridLayout>
 ```
 
@@ -764,9 +764,9 @@ To prevent dismissing the overlay by clicking, pressing Escape or moving focus t
   <Layout.Header title="Tiny Scrollbar" />
   <Layout.Content scrollbar="tiny">
     {Array.from({ length: 20 }, (_, i) => (
-      <div key={i} style={{ padding: '8px' }}>
+      <Block key={i} padding="1x">
         <Text>Line {i + 1}: Hover to reveal scrollbar indicator.</Text>
-      </div>
+      </Block>
     ))}
   </Layout.Content>
 </Layout>
@@ -818,7 +818,7 @@ function ApplicationShell() {
           title="Navigation"
           onClose={() => setSidebarOpen(false)}
         />
-        <Layout.Content padding=".5x" scrollbar="tiny" gap="1bw">
+        <Layout.Content padding=".5x" scrollbar="tiny" gap="$item-gap">
           {['Dashboard', 'Analytics', 'Reports'].map((item) => (
             <ItemButton key={item} type="clear" width="100%">
               {item}

package/docs/components/content/Text.md

@@ -51,7 +51,7 @@ These properties allow direct style application without using the `styles` prop:
 ```jsx
 <Text>Inline text</Text>
 
-<Text ellipsis style={{ maxWidth: 200 }}>
+<Text ellipsis styles={{ maxWidth: '25x' }}>
   Long text that will be truncated with ellipsis
 </Text>
 

package/docs/components/fields/ComboBox.md

@@ -35,7 +35,7 @@ A combobox component that combines a text input with a dropdown list, allowing u
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function or false to disable filtering. If not provided, uses default contains filter
 - **`hideTrigger`** `boolean` (default: `false`) — Whether to hide the trigger button
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — ComboBox size, which the options in the list share
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 - **`necessityIndicator`** `'label' | 'icon'` — How the required state should be indicated
 - **`onSelectionChange`** `(key: Key | null) => void` — Callback fired when the selected option changes
 - **`onInputChange`** `(value: string) => void` — Callback fired when the input text changes

package/docs/components/fields/CommandTextArea.md

@@ -61,7 +61,7 @@ Supports all [Field properties](../../FieldProperties.md) (`label`, `name`, `isR
 - **`optionStyles`** — Styles for individual options.
 - **`sectionStyles`** — Styles for section containers.
 - **`headingStyles`** — Styles for section headings.
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 
 ### Style Properties
 

package/docs/components/fields/FilterListBox.md

@@ -26,7 +26,7 @@ A searchable list selection component that combines a ListBox with an integrated
 - **`disallowEmptySelection`** `boolean` (default: `false`) — Whether to disallow empty selection
 - **`disabledKeys`** `Key[]` — Array of keys for disabled items
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — FilterListBox size
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 - **`searchPlaceholder`** `string` (default: `Search...`) — Placeholder text in the search input
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function or `false` to disable filtering
 - **`emptyLabel`** `ReactNode` (default: context-aware: `No items` or `No results found`) — Label shown when the list is empty. When provided, overrides both defaults for any empty state

package/docs/components/fields/FilterPicker.md

@@ -41,7 +41,7 @@ Choose a different component when the interaction has another shape:
 - **`type`** `'outline' | 'outline-2' | 'clear' | 'primary'` (default: `outline`) — Button styling type
 - **`theme`** `'default' | 'special'` (default: `default`) — Button theme
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of the picker component
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 - **`searchPlaceholder`** `string` — Placeholder text in the search input
 - **`emptyLabel`** `ReactNode` (default: context-aware: `No items` or `No results found`) — Label shown when the list is empty. When provided, overrides both defaults for any empty state
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function for determining if an option should be included in search results

package/docs/components/fields/ListBox.md

@@ -29,7 +29,7 @@ A versatile list selection component that allows users to select one or more ite
 - **`disabledKeys`** `Key[]` — Array of keys for disabled items
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — ListBox size
 - **`shape`** `'card' | 'plain' | 'popover'` (default: `card`) — Visual shape of the ListBox
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 - **`filter`** `(nodes: Iterable<Node>) => Iterable<Node>` — Filter function for the list items
 - **`emptyLabel`** `ReactNode` (default: `No items`) — Label shown when no items are available. The empty listbox stays in the document, described by this label
 - **`header`** `ReactNode` — Custom header content
@@ -185,7 +185,7 @@ The `mods` property accepts the following modifiers you can override:
 - Use `plain` when embedding ListBox directly into another component
 - Use `popover` when using ListBox inside overlays (Dialog, ComboBox, Picker)
 
-**listGap** (`number`, default: a hairline, `1bw`)
+**listGap** (`number`, default: a hairline, `$item-gap`)
 
 - The space between options, in pixels
 - Use it rather than a margin in `optionStyles`: a virtualized list positions its options itself, so it ignores their margins

package/docs/components/fields/Picker.md

@@ -34,7 +34,7 @@ Choose a different component when the interaction has another shape:
 - **`defaultSelectedKeys`** `string[] | 'all'` — The default selected keys in uncontrolled multiple mode
 - **`items`** `Iterable<T>` — Array of items for dynamic content with render function pattern
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of the picker component
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 - **`type`** `'outline' | 'outline-2' | 'clear' | 'primary'` (default: `outline`) — Trigger button styling type
 - **`theme`** `'default' | 'danger'` (default: `default`) — Trigger button color theme
 - **`icon`** `ReactNode` — Icon displayed in the trigger button

package/docs/components/fields/SearchComboBox.md

@@ -37,7 +37,7 @@ Choose a different component when the interaction has another outcome:
 - **`isLoading`** `boolean` (default: `false`) — Whether items are being loaded (e.g. from a server)
 - **`loadingDelay`** `number` (default: `1000`) — Delay in ms before the loading indicator appears
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of the component
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 - **`disabledKeys`** `Iterable<Key>` — Keys of suggestions that cannot be selected
 - **`onSelect`** `(key: string, textValue: string) => void` — Fired when a suggestion is picked; the input clears afterwards
 - **`onSubmit`** `(value: string) => void` — Opt-in. Fired when Enter is pressed with no focused/available option; the input clears afterwards

package/docs/components/fields/Select.md

@@ -56,7 +56,7 @@ Choose a different component when the interaction has another shape:
 - **`inputStyles`** `Styles` — Styles for the input trigger element
 - **`listBoxStyles`** `Styles` — Styles for the dropdown list container
 - **`optionStyles`** `Styles` — Styles for individual option items
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 - **`overlayStyles`** `Styles` — Styles for the dropdown overlay wrapper
 - **`triggerStyles`** `Styles` — Styles for the trigger button element
 - **`inputProps`** `Props` — Additional props for the trigger button element

package/docs/components/fields/TagInput.md

@@ -39,7 +39,7 @@ A multi-value field. The user types a value into a single-line input and commits
 - **`hideTrigger`** `boolean` (default: `false`) — Whether to hide the button that toggles the popover
 - **`disabledKeys`** `Iterable<Key>` — Keys of options that cannot be picked
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of the input. The chips follow it
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 - **`direction`** `'bottom' | 'top'` (default: `bottom`) — Where the suggestions popover opens
 - **`shouldFlip`** `boolean` (default: `true`) — Whether the popover flips when there is no room
 - **`overlayOffset`** `number` (default: `8`) — Distance between the input and the popover, in pixels

package/docs/tasty/react-api.md

@@ -406,7 +406,7 @@ elements: {
 }
 ```
 
-The sub-components produced by `elements` support `mods`, `tokens`, `isDisabled`, `isHidden`, and `isChecked` props — the same modifier interface as the root component.
+The sub-components produced by `elements` support `mods`, `tokens`, `theme`, `isDisabled`, `isHidden`, and `isChecked` props — the same modifier interface as the root component. As on the root, `theme` renders as `data-theme`, and an explicit `data-theme` wins over it.
 
 If you don't need sub-components (e.g., the inner elements are already rendered by a third-party library), you can still style them by key alone — just omit `elements` and apply `data-element` manually:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.199.1",
+  "version": "0.200.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {
@@ -59,7 +59,7 @@
     "@tabler/icons-react": "^3.31.0",
     "@tanstack/react-virtual": "^3.13.12",
     "@tenphi/glaze": "2.0.0",
-    "@tenphi/tasty": "3.13.0",
+    "@tenphi/tasty": "3.14.0",
     "clipboard-copy": "^4.0.1",
     "clsx": "^1.1.1",
     "diff": "^8.0.3",
@@ -97,7 +97,7 @@
     "@statoscope/cli": "^5.20.1",
     "@storybook/addon-docs": "^10.3.6",
     "@storybook/react-vite": "^10.3.6",
-    "@tenphi/eslint-plugin-tasty": "^1.8.0",
+    "@tenphi/eslint-plugin-tasty": "^1.12.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.7.0",
     "@testing-library/react": "^16.3.0",