@tcn/ui 0.17.0 → 0.18.1

package/src/stacks/box/box.tsx

@@ -7,8 +7,6 @@ import { removeUndefinedProperties } from '../utils/remove_undefined_properties.
 import { BottomResizeHandle } from './bottom_resize_handle.js';
 import { EndResizeHandle } from './end_resize_handle.js';
 import { HandleProps } from './handle_props.js';
-import { LeftResizeHandle } from './left_resize_handle.js';
-import { RightResizeHandle } from './right_resize_handle.js';
 import { StartResizeHandle } from './start_resize_handle.js';
 import { TopResizeHandle } from './top_resize_handle.js';
 import type {
@@ -43,20 +41,47 @@ export interface BoxProps<T extends HTMLElement = HTMLElement> extends HTMLAttri
   overflow?: React.CSSProperties['overflow'];
   overflowX?: React.CSSProperties['overflowX'];
   overflowY?: React.CSSProperties['overflowY'];
+  /** @deprecated Use Resizable + ResizeHandle instead */
   enableResizeOnTop?: boolean;
+  /** @deprecated Use Resizable + ResizeHandle instead */
   enableResizeOnEnd?: boolean;
+  /** @deprecated Use Resizable + ResizeHandle instead */
   enableResizeOnBottom?: boolean;
+  /** @deprecated Use Resizable + ResizeHandle instead */
   enableResizeOnStart?: boolean;
+  /** @deprecated Use Resizable + ResizeHandle instead */
   enableResizeOnLeft?: boolean;
+  /** @deprecated Use Resizable + ResizeHandle instead */
   enableResizeOnRight?: boolean;
+  /** @deprecated Use Resizable + ResizeHandle instead */
   horizontalHandleProps?: HandleProps;
+  /** @deprecated Use Resizable + ResizeHandle instead */
   verticalHandleProps?: HandleProps;
+  /** @deprecated Use Resizable + ResizeHandle instead */
   onWidthResize?: OnWidthResize;
+  /** @deprecated Use Resizable + ResizeHandle instead */
   onHeightResize?: OnHeightResize;
+  /** @deprecated Use Resizable + ResizeHandle instead */
   onWidthResizeEnd?: OnWidthResizeEnd;
+  /** @deprecated Use Resizable + ResizeHandle instead */
   onHeightResizeEnd?: OnHeightResizeEnd;
 }
 
+/** Union of deprecated resize-related prop names on BoxProps. Useful for Omit<BoxProps, DeprecatedBoxResizeProps>. */
+export type DeprecatedBoxResizeProps =
+  | 'enableResizeOnTop'
+  | 'enableResizeOnEnd'
+  | 'enableResizeOnBottom'
+  | 'enableResizeOnStart'
+  | 'enableResizeOnLeft'
+  | 'enableResizeOnRight'
+  | 'horizontalHandleProps'
+  | 'verticalHandleProps'
+  | 'onWidthResize'
+  | 'onHeightResize'
+  | 'onWidthResizeEnd'
+  | 'onHeightResizeEnd';
+
 export const Box = React.forwardRef<HTMLElement, BoxProps>(function Box(
   {
     style,
@@ -206,7 +231,7 @@ export const Box = React.forwardRef<HTMLElement, BoxProps>(function Box(
         />
       )}
       {enableResizeOnLeft && (
-        <LeftResizeHandle
+        <StartResizeHandle
           onWidthResize={onWidthResize}
           onWidthResizeEnd={onWidthResizeEnd}
           targetRef={boxRef}
@@ -214,7 +239,7 @@ export const Box = React.forwardRef<HTMLElement, BoxProps>(function Box(
         />
       )}
       {enableResizeOnRight && (
-        <RightResizeHandle
+        <EndResizeHandle
           onWidthResize={onWidthResize}
           onWidthResizeEnd={onWidthResizeEnd}
           targetRef={boxRef}

package/src/stacks/box/end_resize_handle.tsx

@@ -15,7 +15,7 @@ export function EndResizeHandle({
     targetRef,
     onWidthResize,
     onWidthResizeEnd,
-    'right'
+    'end'
   );
   const offset = handleProps?.offset ? handleProps.offset : -8;
 

package/src/stacks/box/resize_handlers.ts

@@ -19,7 +19,7 @@ export function createHorizontalResizeHandler(
   targetRef: React.MutableRefObject<HTMLElement | null>,
   onWidthResize?: OnWidthResize,
   onWidthResizeEnd?: (width: number, origin: WidthResizeOrigin) => void,
-  origin: WidthResizeOrigin = 'right',
+  origin: WidthResizeOrigin = 'end',
   invert = false,
   disableDirection = false
 ) {

package/src/stacks/box/start_resize_handle.tsx

@@ -16,7 +16,7 @@ export function StartResizeHandle({
     targetRef,
     onWidthResize,
     onWidthResizeEnd,
-    'left',
+    'start',
     true
   );
 

package/src/stacks/box/types.ts

@@ -1,7 +1,8 @@
 import type { HandleProps } from './handle_props.js';
+import type { HorizontalSide, VerticalSide } from '../../utils/types/sides.js';
 
-export type WidthResizeOrigin = 'left' | 'right';
-export type HeightResizeOrigin = 'top' | 'bottom';
+export type WidthResizeOrigin = HorizontalSide;
+export type HeightResizeOrigin = VerticalSide;
 
 export interface BaseOnResizePayload<
   Origin extends WidthResizeOrigin | HeightResizeOrigin,

package/src/stacks/collapsible_box.stories.tsx

@@ -1,7 +1,7 @@
 import { ChevronLeftIcon as ChevronLeft } from '@tcn/icons/chevron_left_icon.js';
 import { PlusIcon as Plus } from '@tcn/icons/plus_icon.js';
 import React from 'react';
-import { Button, SlimButton } from '../actions/index.js';
+import { Button } from '../actions/index.js';
 import { Title } from '../typography/index.js';
 import { HCollapsibleBox } from './h_collapsible_box.js';
 import { HStack } from './h_stack.js';
@@ -26,14 +26,14 @@ function MyPanel() {
   return (
     <VStack height="100%" vAlign="start" style={{ backgroundColor: 'white' }}>
       <HStack padding="8px">
-        <SlimButton hierarchy="tertiary">
+        <Button utility hierarchy="tertiary">
           <ChevronLeft size="lg" />
-        </SlimButton>
+        </Button>
         <Title emphasis="strong">Foo</Title>
         <Spacer />
-        <SlimButton size="md" hierarchy="primary">
+        <Button utility size="md" hierarchy="primary">
           <Plus />
-        </SlimButton>
+        </Button>
       </HStack>
     </VStack>
   );

package/src/stacks/demo.stories.tsx

@@ -6,7 +6,7 @@ import { BodyText, Headline, Subheadline, Title } from '../typography/index.js';
 import { MoreHorizontalIcon } from '@tcn/icons/more_horizontal_icon.js';
 import { PlayFilledIcon } from '@tcn/icons/play_filled_icon.js';
 import { ShuffleIcon } from '@tcn/icons/shuffle_icon.js';
-import { Button, SlimButton } from '../actions/index.js';
+import { Button } from '../actions/index.js';
 import { CloudDownloadIcon } from '@tcn/icons/cloud_download_icon.js';
 import { Spacer } from './spacer.js';
 import styles from './demo.module.css';
@@ -28,9 +28,9 @@ export function Track() {
       </HStack>
       <HStack width="auto" gap="8px">
         <BodyText>2:00</BodyText>
-        <SlimButton hierarchy="tertiary" gap="4px">
+        <Button utility hierarchy="tertiary" gap="4px">
           <MoreHorizontalIcon size="lg" />
-        </SlimButton>
+        </Button>
       </HStack>
     </HStack>
   );
@@ -83,12 +83,12 @@ export function Playing() {
             </Button>
             <Spacer />
             <HStack width="auto" gap="8px">
-              <SlimButton hierarchy="secondary" gap="4px">
+              <Button utility hierarchy="secondary" gap="4px">
                 <CloudDownloadIcon size="lg" />
-              </SlimButton>
-              <SlimButton hierarchy="secondary" gap="4px">
+              </Button>
+              <Button utility hierarchy="secondary" gap="4px">
                 <MoreHorizontalIcon size="lg" />
-              </SlimButton>
+              </Button>
             </HStack>
           </HStack>
         </VStack>

package/src/surfaces/page/page.stories.tsx

@@ -10,8 +10,8 @@ import { ZStack } from '../../stacks/z_stack.js';
 import { Panel } from '../panel/panel.js';
 import { Card } from '../card/card.js';
 import { SBContent } from '../../layouts/__stories__/utils.js';
-import { Resizable } from '../../utils/resize/resizable.js';
-import { ResizeHandle } from '../../utils/resize/resize_handle.js';
+import { Resizable } from '../../utils/decorators/resizable/resizable.js';
+import { ResizeHandle } from '../../utils/decorators/resizable/resize_handle.js';
 
 export default {
   title: 'Surfaces/Page',
@@ -137,12 +137,12 @@ export const ResizableSecondaryColumn = () => {
                 </Header>
                 <Scaffold>
                   <Detail>
-                    <BodyText>Drag the left edge to resize this column.</BodyText>
+                    <BodyText>Drag the start edge to resize this column.</BodyText>
                   </Detail>
                 </Scaffold>
               </Panel>
             </Column>
-            <ResizeHandle position="left" />
+            <ResizeHandle position="start" />
           </Resizable>
         </Columns>
       </Page>

package/src/surfaces/window/window.stories.tsx

@@ -6,7 +6,7 @@ import { Spacer } from '../../stacks/spacer.js';
 import { Button } from '../../actions/index.js';
 import { CrossIcon } from '@tcn/icons/cross_icon.js';
 import { ZStack } from '../../stacks/z_stack.js';
-import { DragHandle } from '../../utils/dnd/handle.js';
+import { DragHandle } from '../../utils/decorators/draggable/drag_handle.js';
 import { BugIcon } from '@tcn/icons/bug_icon.js';
 
 export default {

package/src/themes/stories/button_showcase.tsx

@@ -7,11 +7,13 @@ import { VStack } from '../../stacks/v_stack.js';
 import { Spacer } from '../../stacks/spacer.js';
 import { Field } from '../../form/field/field.js';
 import { FieldSet } from '../../form/field_set/field_set.js';
+import { Legend } from '../../form/field_set/legend.js';
 import { BodyText } from '../../typography/index.js';
 
 export function ButtonShowcase() {
   return (
-    <FieldSet legend="Button Showcase">
+    <FieldSet>
+      <Legend>Button Showcase</Legend>
       {/* Basic Buttons */}
       <Field label="Basic Buttons">
         <HStack width="400px" gap="8px">

package/src/themes/stories/controls_fieldset.tsx

@@ -21,6 +21,7 @@ import { HStack } from '../../stacks/h_stack.js';
 import { Spacer } from '../../stacks/spacer.js';
 import { Field } from '../../form/field/field.js';
 import { FieldSet } from '../../form/field_set/field_set.js';
+import { Legend } from '../../form/field_set/legend.js';
 
 export function ControlsFieldSet() {
   const [disabled, setDisabled] = useState<boolean>(false);
@@ -49,7 +50,8 @@ export function ControlsFieldSet() {
         <Switch checked={disabled} onChange={setDisabled} />
       </Field>
       <Spacer height="8px" />
-      <FieldSet legend="Inputs">
+      <FieldSet>
+        <Legend>Inputs</Legend>
         <Field label="Input">
           <Input disabled={disabled} />
         </Field>

package/src/themes/stories/menu_showcase.tsx

@@ -18,6 +18,7 @@ import { Spacer } from '../../stacks/spacer.js';
 import { ZStack } from '../../stacks/z_stack.js';
 import { Field } from '../../form/field/field.js';
 import { FieldSet } from '../../form/field_set/field_set.js';
+import { Legend } from '../../form/field_set/legend.js';
 import { BodyText } from '../../typography/index.js';
 import { Checkbox } from '../../inputs/index.js';
 import { Divider } from '../../layouts/divider/divider.js';
@@ -117,7 +118,8 @@ export function MenuShowcase() {
   };
 
   return (
-    <FieldSet legend="Menu Showcase">
+    <FieldSet>
+      <Legend>Menu Showcase</Legend>
       {/* Basic Dropdown Menus */}
       <Field label="Basic Dropdown Menus">
         <VStack gap="8px" hAlign="end">

package/src/themes/themes/ergo/INTERACTIVE.md

@@ -0,0 +1,89 @@
+# `.tcn-interactive` — The Interaction State Primitive
+
+## What it is
+
+`.tcn-interactive` is a CSS class that provides the foundational interaction state system for all clickable/tappable elements. It is an atomic theme concept — alongside material, surface, and elevation — that doesn't define what something looks like, but how something responds to user interaction.
+
+## What it provides
+
+### CSS custom properties (state vocabulary)
+
+These variables form the "interaction vocabulary" that all interactive components share:
+
+| Variable | Purpose |
+|----------|---------|
+| `--ink` | Text/foreground color (defaults to `--on-material`) |
+| `--act` | Action accent color (defaults to `--action`) |
+| `--mat` | Background/material color (defaults to `--material`) |
+| `--act-down` | Active/pressed state — darkened material (`black 12%` mix) |
+| `--act-raised` | Hover state — action tinted into material (`--act 12%` mix) |
+| `--act-focus` | Focus state — stronger action tint (`--act 16%` mix) |
+| `--act-drag` | Drag state — strongest action tint (`--act 24%` mix) |
+
+### Presentational defaults
+
+| Property | Value | Why |
+|----------|-------|-----|
+| `cursor` | `pointer` | Signals clickability |
+| `user-select` | `none` | Prevents accidental text selection during interaction |
+| `background` | `var(--mat)` | Material background |
+| `color` | `var(--ink)` | Foreground color |
+| `transition` | `background 0.1s, color 0.1s` | Smooth state changes |
+
+### Pseudo-state mapping
+
+| State | Selector | Background |
+|-------|----------|------------|
+| Focus | `:focus-visible`, `[data-focus-visible]` | `--act-focus` + 2px outline |
+| Hover | `:hover`, `[data-hover]` | `--act-raised` |
+| Active | `:active`, `[data-active]` | `--act-down` |
+| Disabled | `[data-is-disabled="true"]` | `pointer-events: none` |
+
+The `data-*` attribute selectors exist alongside pseudo-classes so that components can programmatically force states (e.g., showing a hover state in Storybook without actual mouse interaction).
+
+## Why we have it
+
+Without `.tcn-interactive`, every clickable component would need to independently implement:
+- Its own hover/focus/active/disabled background logic
+- Its own color-mixing math for state changes
+- Its own transition timing
+
+By centralizing this in a single class, components opt into a consistent interaction model. A button, a toggle, a tab item, and a list item all respond to hover/focus/active in the same way — the only difference is what `--act`, `--mat`, and `--ink` resolve to in context.
+
+This is what makes the "material system" work: a button inside a modal header automatically picks up the header's `--material` and `--on-material`, and the interactive states remix those colors correctly. No component needs to know what surface it's sitting on.
+
+## Which components apply it
+
+| Component | File | Additional classes |
+|-----------|------|--------------------|
+| `BaseButton` | `actions/button/base_button/base_button.tsx` | `.tcn-base-button` |
+| `TabItem` | `navigation/tabs/primitives/tabs_list.tsx` | `.tcn-tab-item` |
+| `Item` (list) | `layouts/list/item.tsx` | `.tcn-item` |
+
+All button variants (`Button`, `Toggle`, `MobileButton`) inherit `.tcn-interactive` through `BaseButton`. This means the class is active on every button, toggle, tab, and list item in the system.
+
+## How components customize it
+
+Components override the vocabulary variables rather than the properties:
+
+```css
+/* Button sets --mat and --ink based on hierarchy */
+.tcn-button[data-hierarchy="primary"] {
+  --mat: var(--tcn-button-color, var(--btn-primary));
+  --ink: var(--tcn-button-text-color, var(--btn-on-primary));
+}
+
+/* Toggle overrides for selected state */
+.tcn-toggle[data-is-selected="true"] {
+  --mat: var(--tcn-button-color, var(--tgl-true));
+  --ink: var(--tcn-button-text-color, var(--ergo-white));
+}
+
+/* Tab item overrides for selected state */
+.tcn-tab-item[data-is-selected="true"] {
+  --mat: var(--tcn-button-color, var(--material));
+  --ink: var(--tcn-button-text-color, var(--ergo-primary));
+}
+```
+
+Because the state backgrounds (`--act-raised`, `--act-down`, `--act-focus`) are computed from `--mat` and `--act` via `color-mix()`, changing the input variables automatically produces correct state colors for any context.

package/src/themes/themes/ergo/ROADMAP.md

@@ -0,0 +1,116 @@
+# Ergo Theme — Part File Cascade
+
+Tracks the split of the monolithic `ergo_theme.css` into modular part files loaded in a strict cascade order via `buildStyleSheet()`.
+
+## Load Order & Status
+
+| # | File | Status | Contains |
+|---|------|--------|----------|
+| 1 | `tokens/theme_tokens.css` | Done | Ergo palette, spacing, sizing, shape tokens |
+| 2 | `tokens/system_tokens.css` | Done | Blackcat system tokens (maps palette to semantics) |
+| 3 | `parts/base.css` | Done | `.tcn-theme-root`, `.tcn-interactive`, `.material` |
+| 4 | `parts/actions.css` | Done | `.tcn-base-button`, `.tcn-button`, `.tcn-toggle`, `.tcn-fab`, `.tcn-mobile-button`, `.tcn-button-group`, `.tcn-select-group` |
+| 5 | `parts/inputs.css` | Done | `.tcn-entry`, `.tcn-control`, `.tcn-input`, `.tcn-textarea`, `.tcn-control-set`, `.tcn-checkbox`, `.tcn-switch-wrapper`, `.tcn-slider`, `.tcn-radio-label`, `.tcn-select-selected-label`, `.tcn-multiselect-*` |
+| 6 | `parts/form.css` | Done | `.tcn-field-set`, `.tcn-field-set-legend` |
+| 7 | `parts/navigation.css` | Done | `.tcn-tabs-bar`, `.tcn-tabs-list`, `.tcn-tab-item` (default + inline variants) |
+| 8 | `parts/tokens_display.css` | TODO | `.tcn-chip`, `.tcn-datum`, `.tcn-key`, `.tcn-value`, `.tcn-term` |
+| 9 | `parts/decorators.css` | TODO | `.tcn-draggable`, `.tcn-drag-handle`, `.tcn-resize-handle` (new theme coverage) |
+| 10 | `parts/layouts.css` | TODO | `.tcn-scaffold`, `.tcn-header`, `.tcn-footer`, `.tcn-utility-bar`, `.tcn-utility-strip`, `.tcn-bar`, `.tcn-group`, `.tcn-section`, `.tcn-heading`, `.tcn-detail`, `.tcn-caret`, `.tcn-columns`, `.tcn-rows`, `.tcn-divider-line` |
+| 11 | `parts/table.css` | TODO | `.tcn-table`, `.tcn-thead`, `.tcn-tbody`, `.tcn-tfoot`, `.tcn-tr`, `.tcn-td`, `.tcn-th` |
+| 12 | `parts/overlay.css` | TODO | `.tcn-tethered`, `.tcn-tooltip`, `.tcn-frame-dialog`, `.tcn-frame-veil` |
+| 13 | `parts/surfaces.css` | TODO | `.tcn-page`, `.tcn-panel`, `.tcn-aside`, `.tcn-card`, `.tcn-modal`, `.tcn-drawer`, `.tcn-window`, `.tcn-pop-confirm`, `.tcn-confirm`, `.tcn-list`, `.tcn-item` |
+| 14 | `parts/typography.css` | TODO | `.tcn-body-text`, `.tcn-headline`, `.tcn-title`, etc. (`[data-emphasis="faint"]`) |
+
+> Once all parts are extracted, `ergo_theme.css` is deleted and this file may be renamed to `LAYERS.md`.
+
+## Dependency Chain
+
+Each layer can reference CSS custom properties and class behaviors defined in layers above it. Reverse references (later layer depending on an earlier one's internals) are not allowed.
+
+```
+tokens/theme_tokens.css
+  Defines: --ergo-* palette, spacing, sizing, shape
+  Depends on: nothing
+
+tokens/system_tokens.css
+  Defines: --font-*, --gap-*, --padding-*, --status-color-*, --action-severity-*, --*-color-*
+  Depends on: theme_tokens (references --ergo-* variables)
+
+parts/base.css
+  Defines: --action, --on-action, --material, --on-material (on .tcn-theme-root)
+           --ink, --act, --mat, --act-down, --act-raised, --act-focus, --act-drag (on .tcn-interactive)
+           .material background/color
+  Depends on: theme_tokens (--ergo-primary, --ergo-white, --ergo-accent-blue)
+              system_tokens (--font-family, --font-color)
+
+parts/actions.css
+  Defines: --btn-*, --tgl-* button/toggle sizing and color system
+  Depends on: base (--action, --on-action, --material, --on-material, --ink, --act, --mat)
+              theme_tokens (--ergo-shape-radius-medium, severity colors)
+              system_tokens (--padding-small, --action-severity-*)
+
+parts/navigation.css
+  Defines: tab indicator positioning, variant styles
+  Depends on: base (--material, --on-material, interactive vocabulary)
+              actions (uses --mat, --ink, --act from interactive chain)
+              theme_tokens (--ergo-primary, --ergo-accent-blue, --ergo-material-divider)
+
+parts/inputs.css
+  Defines: form control chrome (border, focus, disabled states), multiselect containers
+  Depends on: base (--action, --material, --act, --mat)
+              theme_tokens (--ergo-grey, --ergo-sizing-action-md, --ergo-shape-radius-medium, --ergo-primary)
+              system_tokens (--ergo-text-size-input, --gap-small)
+
+parts/form.css
+  Defines: field-set layout, legend chrome, disabled entry within field-set
+  Depends on: theme_tokens (--ergo-sizing-bar-md, --ergo-material-divider, --ergo-material-disabled-outline, --ergo-text-color-disabled-outline)
+              system_tokens (--gap-medium, --padding-medium)
+
+parts/tokens_display.css
+  Defines: chip, datum, key/value/term display atoms
+  Depends on: base (--action, --on-material)
+              theme_tokens (--ergo-primary, --ergo-accent-blue, status colors)
+
+parts/decorators.css
+  Defines: drag handle cursors, resize handle indicators
+  Depends on: theme_tokens (--ergo-grey-light, --ergo-grey-dark, --ergo-shape-radius-medium)
+  Note: must precede layouts and surfaces since handles appear inside both
+
+parts/layouts.css
+  Defines: scaffold structure, section nesting depth system, bar/group dividers, columns/rows, caret, divider-line
+  Depends on: base (--material, --on-material)
+              theme_tokens (--ergo-sizing-bar-*, --ergo-material-border, section depth colors)
+              system_tokens (--padding-*, --gap-*)
+
+parts/table.css
+  Defines: table chrome (header/body/footer colors, alternating rows, sticky borders)
+  Depends on: base (--material, --on-material, --action, --on-action)
+              theme_tokens (--ergo-white, --ergo-accent-blue-light, --ergo-grey)
+              system_tokens (--padding-medium)
+              layouts (inherits --pad-inline concept from scaffold/surface context)
+
+parts/overlay.css
+  Defines: tethered positioning, tooltip chrome, frame-dialog border, veil backdrop
+  Depends on: base (--material, --on-material)
+              theme_tokens (--ergo-secondary-dark, --ergo-shape-triangle-medium)
+              system_tokens (--padding-medium)
+
+parts/surfaces.css — LAST
+  Defines: page/panel/card/modal/drawer/window/pop-confirm composition
+  Depends on: ALL previous layers
+  Note: surfaces are the final composition layer. They set --material, --on-material,
+        --divide-header, --pad-inline for their children (scaffold, sections, inputs,
+        actions). This is why surfaces must be last — they orchestrate all other layers.
+```
+
+### Why this order matters
+
+The cascade within `@layer tcn-theme` is determined by declaration order. Later declarations win on conflicts for equal specificity. This means:
+
+1. **Tokens first** — everything references them, nothing references back
+2. **Base before actions** — actions use `--ink`, `--act`, `--mat` defined by `.tcn-interactive` in base
+3. **Actions before navigation** — tabs extend the interactive/action vocabulary
+4. **Inputs independent** — form controls don't depend on actions or navigation
+5. **Decorators before layouts/surfaces** — handles appear inside both; their base styles must exist first
+6. **Layouts before surfaces** — surfaces set `--pad-inline`, `--divide-header` that scaffold/section read; layout structure rules must exist for surfaces to override them
+7. **Surfaces last** — they compose everything: inputs inside cards, actions inside modals, layout slots inside panels. Surface-specific overrides (e.g., `.tcn-card .tcn-section`) must win over base layout rules