@cube-dev/ui-kit 0.209.0 → 0.211.0

package/dist/utils/react/useQaProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.209.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.211.0 | Cube Dev Team */
 //#region src/utils/react/useQaProps.ts
 /**
 * Processes QA props.

package/dist/utils/react/useScheme.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.209.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.211.0 | Cube Dev Team */
 import { useSyncExternalStore } from "react";
 //#region src/utils/react/useScheme.ts
 /**

package/dist/utils/react/useViewportSize.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.209.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.211.0 | Cube Dev Team */
 import { c } from "react/compiler-runtime";
 import { useEffect, useState } from "react";
 //#region src/utils/react/useViewportSize.ts

package/dist/utils/react/wrapNodeIfPlain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.209.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.211.0 | Cube Dev Team */
 import { Fragment, isValidElement } from "react";
 //#region src/utils/react/wrapNodeIfPlain.ts
 function wrapNodeIfPlain(children, render) {

package/dist/utils/selection.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.209.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.211.0 | Cube Dev Team */
 //#region src/utils/selection.ts
 /**
 * Deduplicate/toggle keys in a selection: if a key appears twice it is

package/dist/utils/styles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.209.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.211.0 | Cube Dev Team */
 import { isSelector, mergeStyles } from "@tenphi/tasty";
 //#region src/utils/styles.ts
 function isRecord(value) {

package/dist/utils/tree.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.209.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.211.0 | Cube Dev Team */
 //#region src/utils/tree.ts
 function toFlatTree(tree, includingFolders) {
 	return tree.reduce((result, node) => {

package/dist/utils/warnings.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.209.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.211.0 | Cube Dev Team */
 import { isDevEnvOrTest } from "./is-dev-env.js";
 //#region src/utils/warnings.ts
 const SUGGESTED_PROP_MAP = {

package/dist/version.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.209.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.211.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.209.0";
+const VERSION = "0.211.0";
 const TASTY_VERSION = "3.18.0";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/Usage.md

@@ -412,7 +412,7 @@ Most components are a design contract: customize them through their own props (`
 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`, `Alert`, `Result`, `Skeleton`, and `Layout` and `GridLayout` with their sub-components) also keep the ones that lay out their content: `display`, `padding`, `gap`, `flow`, `place*`, `align*`, `justify*`, `grid*`, `overflow` and `scrollbar`. `Placeholder` keeps `radius`, the shape of what it stands in for. Root `styles` that sets only allowed props passes too;
+- style props other than the ones that place or size the component (`width`, `height`, `gridArea`, `margin`, `inset`, …). Containers (`Card`, `Panel`, `ResizablePanel`, `Content`, `Header`, `Footer`, `Alert`, `Result`, `Skeleton`, and `Layout` and `GridLayout` with their sub-components) also keep the ones that lay out their content: `display`, `padding`, `gap`, `flow`, `place*`, `align*`, `justify*`, `grid*`, `overflow`, `scrollbar`, `textAlign`, and `container` for container queries. A container that draws no fill and no border of its own (`Layout`, `GridLayout`, `Panel`, `ResizablePanel`, `Content`, `Header` and `Footer`) also keeps `fill` and `border`. `Layout`'s sections (`Layout.Content`, `Header`, `Footer`, `Toolbar`, `Block`, `Flex`, `Grid`, `Center` and `Container`) keep `fill`, but not `border`: the border that separates stacked sections is UI Kit's. `Placeholder` keeps `radius`, the shape of what it stands in for. Root `styles` that sets only allowed props passes too;
 - `tasty()` wrappers that restyle a protected component, and wrappers of those wrappers.
 
 On an input, the style props that place or size it act on its outer element: the field wrapper when it renders (see [Field properties](./FieldProperties.md)), the input itself otherwise. Its `styles` always style the input, so a root `styles` that only sizes it passes the rule but sizes the input inside the field, not the field. To size the input alone, beside a side label for example, use its `controlWidth` prop. Input components take no other style props.

package/docs/components/content/Layout.md

@@ -110,6 +110,7 @@ A semantic page header with title, breadcrumbs, subtitle, and action areas.
 
 - **`title`** `ReactNode` — Page/section title. A string title that runs out of room is truncated and shown in full in a tooltip; when the title and `extra` both overflow, they share the shortfall
 - **`level`** `1-6` (default: `3`) — Heading level for accessibility
+- **`titlePreset`** `h1-h6` (default: the preset of `level`) — The title's typography preset, apart from its level: `level={1} titlePreset="h3"` gives an `h1` in the document outline that looks like an `h3`
 - **`breadcrumbs`** `[label, href][]` — Navigation breadcrumbs
 - **`subtitle`** `ReactNode` — Text below the title
 - **`suffix`** `ReactNode` — Content next to the title
@@ -451,6 +452,14 @@ A variant of Layout that enables CSS Grid for the content area.
 </Layout>
 ```
 
+### Page Title Sized Apart From Its Level
+
+A page keeps one `h1`, but in an app's chrome it often looks like an `h3`. `titlePreset` sets the title's look; `level` still sets its heading element.
+
+```jsx
+<Layout.Header title="Page title" level={1} titlePreset="h3" />
+```
+
 ### With Back Button
 
 ```jsx

package/docs/components/fields/FilterListBox.md

@@ -29,7 +29,7 @@ A searchable list selection component that combines a ListBox with an integrated
 - **`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
+- **`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. It wraps to the list's width, so a long message, or an action in it, stays in view.
 - **`allowsCustomValue`** `boolean` (default: `false`) — Whether to allow custom values not in the options list
 - **`isCheckable`** `boolean` (default: `false`) — Whether to show checkboxes for multiple selection
 - **`shouldFocusWrap`** `boolean` (default: `false`) — Whether keyboard navigation should wrap around

package/docs/components/fields/FilterPicker.md

@@ -44,7 +44,7 @@ Choose a different component when the interaction has another shape:
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of the picker component
 - **`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
+- **`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. It wraps to the list's width, so a long message, or an action in it, stays in view.
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function for determining if an option should be included in search results
 - **`header`** `ReactNode` — Custom header content
 - **`footer`** `ReactNode` — Custom footer content

package/docs/components/fields/ListBox.md

@@ -31,7 +31,7 @@ A versatile list selection component that allows users to select one or more ite
 - **`shape`** `'card' | 'plain' | 'popover'` (default: `card`) — Visual shape of the ListBox
 - **`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
+- **`emptyLabel`** `ReactNode` (default: `No items`) — Label shown when no items are available. The empty listbox stays in the document, described by this label. It wraps to the list's width, so a long message, or an action in it, stays in view.
 - **`header`** `ReactNode` — Custom header content
 - **`footer`** `ReactNode` — Custom footer content
 - **`focusOnHover`** `boolean` (default: `false`) — Whether moving the pointer over an option will move DOM focus to that option

package/docs/components/form/ModernForm.md

@@ -172,7 +172,7 @@ Use `setValue(path, value)` for one path and `setValues(partial)` for several to
 | Validation case | Start here |
 | --- | --- |
 | Required field with a visible marker | Input `isRequired`; it adds required validation too. |
-| Email, length, range, pattern, or enum | Input `rules` using the built-in constraints, or descriptor `rules` when using `field`. |
+| Email, length, range, pattern, or enum | Input `rules` using the built-in constraints, or descriptor `rules` when using `field`. They skip an empty value (`''`, `undefined`, `null`; an empty array is not one), so an optional field passes while empty; add `required` to reject one. |
 | Custom domain check | Descriptor `validate(value, context)` for an inferred field value and checked reads. |
 | Several custom rules or existing shared rule objects | `rules: [{ validator(rule, value, context) { ... } }]`; use `ModernValidationRule` for strict modern rule typing. |
 | Validation depends on another form value | `dependsOn: ['password']`, or nested tuples such as `dependsOn: [['account', 'password']]`. |
@@ -289,6 +289,6 @@ function EditProfileDialog({ initialProfile, save }) {
 
 The dialog closes only after successful submission, including `form.submit()` and controller-configured callbacks. Validation or save errors keep it open. Closing cancels pending submission; late responses cannot close a reopened session. By default, ending the session resets values. Use `preserve` to retain the draft in a controller owned outside the dialog. `preserve` does not keep an unmounted controller alive.
 
-While a field the user edited differs from its default, Escape, a click outside and the close button ask "Discard changes?" first. That holds for a `<Form>` you place in a `Dialog` yourself too: the root reports its edits to the `DialogTrigger` or `DialogContainer` that owns the dialog, with no wiring. A value set from code is not an edit, and a successful submit saves what it carried, so a dialog that stays open after saving (to show a created key, say) closes at once until the user types again. Set `confirmDismiss={false}` on the trigger or container when backing out loses nothing. See [Unsaved edits](https://cube-ui-kit.vercel.app/?path=/docs/overlays-dialogtrigger--docs#unsaved-edits).
+While a field the user edited differs from its default, Escape, a click outside and the close button ask "Discard changes?" first. That holds for a `<Form>` you place in a `Dialog` yourself too: the root reports its edits to the `DialogTrigger` or `DialogContainer` that owns the dialog, with no wiring. A value set from code is not an edit, nor is a field typed into and cleared back to an empty default (`''` over `undefined` or `null`), though `isDirty` still reports it. A successful submit saves what it carried, so a dialog that stays open after saving (to show a created key, say) closes at once until the user types again. Set `confirmDismiss={false}` on the trigger or container when backing out loses nothing. See [Unsaved edits](https://cube-ui-kit.vercel.app/?path=/docs/overlays-dialogtrigger--docs#unsaved-edits).
 
 See the [DialogForm reference](https://cube-ui-kit.vercel.app/?path=/docs/overlays-dialogform--docs) for custom actions, container lifecycle, and legacy behavior.

package/docs/modern-form-guide.md

@@ -172,7 +172,7 @@ Use `setValue(path, value)` for one path and `setValues(partial)` for several to
 | Validation case | Start here |
 | --- | --- |
 | Required field with a visible marker | Input `isRequired`; it adds required validation too. |
-| Email, length, range, pattern, or enum | Input `rules` using the built-in constraints, or descriptor `rules` when using `field`. |
+| Email, length, range, pattern, or enum | Input `rules` using the built-in constraints, or descriptor `rules` when using `field`. They skip an empty value (`''`, `undefined`, `null`; an empty array is not one), so an optional field passes while empty; add `required` to reject one. |
 | Custom domain check | Descriptor `validate(value, context)` for an inferred field value and checked reads. |
 | Several custom rules or existing shared rule objects | `rules: [{ validator(rule, value, context) { ... } }]`; use `ModernValidationRule` for strict modern rule typing. |
 | Validation depends on another form value | `dependsOn: ['password']`, or nested tuples such as `dependsOn: [['account', 'password']]`. |
@@ -289,6 +289,6 @@ function EditProfileDialog({ initialProfile, save }) {
 
 The dialog closes only after successful submission, including `form.submit()` and controller-configured callbacks. Validation or save errors keep it open. Closing cancels pending submission; late responses cannot close a reopened session. By default, ending the session resets values. Use `preserve` to retain the draft in a controller owned outside the dialog. `preserve` does not keep an unmounted controller alive.
 
-While a field the user edited differs from its default, Escape, a click outside and the close button ask "Discard changes?" first. That holds for a `<Form>` you place in a `Dialog` yourself too: the root reports its edits to the `DialogTrigger` or `DialogContainer` that owns the dialog, with no wiring. A value set from code is not an edit, and a successful submit saves what it carried, so a dialog that stays open after saving (to show a created key, say) closes at once until the user types again. Set `confirmDismiss={false}` on the trigger or container when backing out loses nothing. See [Unsaved edits](https://cube-ui-kit.vercel.app/?path=/docs/overlays-dialogtrigger--docs#unsaved-edits).
+While a field the user edited differs from its default, Escape, a click outside and the close button ask "Discard changes?" first. That holds for a `<Form>` you place in a `Dialog` yourself too: the root reports its edits to the `DialogTrigger` or `DialogContainer` that owns the dialog, with no wiring. A value set from code is not an edit, nor is a field typed into and cleared back to an empty default (`''` over `undefined` or `null`), though `isDirty` still reports it. A successful submit saves what it carried, so a dialog that stays open after saving (to show a created key, say) closes at once until the user types again. Set `confirmDismiss={false}` on the trigger or container when backing out loses nothing. See [Unsaved edits](https://cube-ui-kit.vercel.app/?path=/docs/overlays-dialogtrigger--docs#unsaved-edits).
 
 See the [DialogForm reference](https://cube-ui-kit.vercel.app/?path=/docs/overlays-dialogform--docs) for custom actions, container lifecycle, and legacy behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.209.0",
+  "version": "0.211.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {

package/tasty.config.ts

@@ -67,6 +67,49 @@ export const componentTokens = [
   '$overlay-inset-top',
 ];
 
+/**
+ * The style props a container keeps: those that place or size it, and those
+ * that lay out the content the consumer puts in it, including `textAlign` and
+ * the `container` that its container queries read. `Layout` and `GridLayout`
+ * cover their sub-components, such as `Layout.Content`, whose `scrollbar` is
+ * their own prop; `ResizablePanel`'s `direction` is the side it resizes from.
+ * `display` picks the layout: a block `Card` needs `flex` or `grid` before
+ * `flow`, `grid*` or `place*` do anything.
+ */
+const containerStyleProps = [
+  'position',
+  'dimension',
+  'display',
+  'flow',
+  'gap',
+  'columnGap',
+  'rowGap',
+  'place',
+  'placeItems',
+  'placeContent',
+  'align',
+  'alignItems',
+  'alignContent',
+  'justify',
+  'justifyItems',
+  'justifyContent',
+  'gridColumns',
+  'gridRows',
+  'gridTemplate',
+  'gridAreas',
+  'gridAutoFlow',
+  'gridAutoColumns',
+  'gridAutoRows',
+  'padding',
+  'blockPadding',
+  'inlinePadding',
+  'overflow',
+  'scrollbar',
+  'textAlign',
+  'container',
+  'direction',
+];
+
 export default {
   extends: '@tenphi/tasty',
 
@@ -152,17 +195,47 @@ export default {
       include: ['GridProvider'],
       allowedStyleProps: ['position', 'dimension', 'gap'],
     },
-    // Containers. `Layout` and `GridLayout` cover their sub-components, such
-    // as `Layout.Content`, whose `scrollbar` is their own prop;
-    // `ResizablePanel`'s `direction` is the side it resizes from. `Alert`,
-    // `Result` and `Skeleton` hold content the consumer supplies, so how that
-    // content is spaced is the consumer's call. `display` picks the layout:
-    // a block `Card` needs `flex` or `grid` before `flow`, `grid*` or `place*`
-    // do anything.
+    // Containers that draw a surface of their own: a fill, a border, a
+    // radius or a theme. `Alert`, `Result` and `Skeleton` hold content the
+    // consumer supplies, so how that content is spaced is the consumer's
+    // call. A member path decides before the export it hangs off, so
+    // `Layout.Panel` and `Layout.PanelHeader` are listed before `Layout`.
     {
       source: '@cube-dev/ui-kit',
       include: [
         'Card',
+        'Layout.Panel',
+        'Layout.PanelHeader',
+        'Alert',
+        'Result',
+        'Skeleton',
+      ],
+      allowedStyleProps: containerStyleProps,
+    },
+    // Layout's sections draw no fill, so the backdrop is the consumer's; their
+    // border is UI Kit's, which separates stacked sections or underlines a
+    // header, so it stays protected.
+    {
+      source: '@cube-dev/ui-kit',
+      include: [
+        'Layout.Content',
+        'Layout.Header',
+        'Layout.Footer',
+        'Layout.Toolbar',
+        'Layout.Block',
+        'Layout.Flex',
+        'Layout.Grid',
+        'Layout.Center',
+        'Layout.Container',
+      ],
+      allowedStyleProps: [...containerStyleProps, 'fill'],
+    },
+    // Frames that draw neither a fill nor a border, such as a page `Layout`
+    // or a plain `Panel`: there is no surface to protect, so a fill or a
+    // border on one is the consumer's, as on a `Block`.
+    {
+      source: '@cube-dev/ui-kit',
+      include: [
         'Panel',
         'ResizablePanel',
         'Content',
@@ -170,41 +243,8 @@ export default {
         'Footer',
         'Layout',
         'GridLayout',
-        'Alert',
-        'Result',
-        'Skeleton',
-      ],
-      allowedStyleProps: [
-        'position',
-        'dimension',
-        'display',
-        'flow',
-        'gap',
-        'columnGap',
-        'rowGap',
-        'place',
-        'placeItems',
-        'placeContent',
-        'align',
-        'alignItems',
-        'alignContent',
-        'justify',
-        'justifyItems',
-        'justifyContent',
-        'gridColumns',
-        'gridRows',
-        'gridTemplate',
-        'gridAreas',
-        'gridAutoFlow',
-        'gridAutoColumns',
-        'gridAutoRows',
-        'padding',
-        'blockPadding',
-        'inlinePadding',
-        'overflow',
-        'scrollbar',
-        'direction',
       ],
+      allowedStyleProps: [...containerStyleProps, 'fill', 'border'],
     },
     // A placeholder stands in for content of any shape, so `radius` is its
     // shape, like `dimension`.