@tcn/ui 0.16.0 → 0.18.0

package/src/surfaces/card/card.stories.tsx

@@ -6,7 +6,10 @@ import { Box, Spacer } from '../../stacks/index.js';
 import { Title } from '../../typography/title/title.js';
 import { Button } from '../../actions/index.js';
 import { Card } from './card.js';
-import { Scaffold } from '../../layouts/index.js';
+import { Detail, Row, Rows, Scaffold } from '../../layouts/index.js';
+import { Key } from '../../tokens/key/key.js';
+import { Term } from '../../tokens/term/term.js';
+import { Value } from '../../tokens/value/value.js';
 
 // Styles
 import styles from './card_stories.module.css';
@@ -52,13 +55,68 @@ export const Default = () => {
           <Box className={styles['content-box']} />
           <Box className={styles['content-box']} />
         </Scaffold>
-        {/* Cards typically do not have a footer */}
-        {/* <Footer>
-          <Title>Footer</Title>
-          <Spacer />
-          <Button hierarchy="secondary">Secondary</Button>
-          <Button hierarchy="primary">Primary</Button>
-        </Footer> */}
+      </Card>
+    </div>
+  );
+};
+
+/**
+ * Rows inside a Card body. Fixed-height rows stack vertically with a
+ * fill row consuming remaining space — mirrors the Login Information
+ * card pattern from the app.
+ */
+export const CardWithRows = () => {
+  return (
+    <div className={styles['stories-container']}>
+      <Card maxHeight="500px" maxWidth="400px">
+        <Header>
+          <Title>Login Information</Title>
+        </Header>
+        <Scaffold>
+          <Rows>
+            <Row>
+              <Detail>
+                <Term>
+                  <Key>Username:</Key>
+                  <Value>1026223MinhtestCreateAgent1</Value>
+                </Term>
+                <Term>
+                  <Key>Email:</Key>
+                  <Value severity="encouraged">jsmith@example.com</Value>
+                </Term>
+              </Detail>
+            </Row>
+
+            <Row>
+              <Detail>
+                <Term>
+                  <Key>Force Password Reset:</Key>
+                  <Value>No</Value>
+                </Term>
+                <Term>
+                  <Key>Two-Factor Status:</Key>
+                  <Value severity="encouraged">Enabled</Value>
+                </Term>
+                <Term>
+                  <Key>Two-Factor Type:</Key>
+                  <Value>Email</Value>
+                </Term>
+              </Detail>
+            </Row>
+            <Row>
+              <Detail>
+                <Term>
+                  <Key>Access Token:</Key>
+                  <Value>••••••••••••</Value>
+                </Term>
+                <Term>
+                  <Key>Expiration Date:</Key>
+                  <Value>02/27/2024</Value>
+                </Term>
+              </Detail>
+            </Row>
+          </Rows>
+        </Scaffold>
       </Card>
     </div>
   );

package/src/surfaces/card/card.tsx

@@ -1,7 +1,7 @@
 import { clsx } from 'clsx';
 import React from 'react';
 import { Scaffold, type ScaffoldProps } from '../../layouts/containers/scaffold.js';
-
+import styles from './card.module.css';
 export interface CardProps extends Omit<ScaffoldProps, 'as' | 'children'> {
   children?: React.ReactNode;
 }
@@ -11,7 +11,11 @@ export const Card = React.forwardRef<HTMLElement, CardProps>(function Card(
   ref
 ) {
   return (
-    <Scaffold ref={ref} className={clsx(className, 'tcn-surface', 'tcn-card')} {...props}>
+    <Scaffold
+      ref={ref}
+      className={clsx(className, styles.card, 'tcn-surface', 'tcn-card')}
+      {...props}
+    >
       {children}
     </Scaffold>
   );

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

@@ -1,3 +1,4 @@
+import { useState } from 'react';
 import { Header } from '../../layouts/header/header.js';
 import { Detail, Footer, Scaffold } from '../../layouts/index.js';
 import { Column } from '../../layouts/containers/columns/column.js';
@@ -7,6 +8,10 @@ import { Title } from '../../typography/title/title.js';
 import { Page } from './page.js';
 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/decorators/resizable/resizable.js';
+import { ResizeHandle } from '../../utils/decorators/resizable/resize_handle.js';
 
 export default {
   title: 'Surfaces/Page',
@@ -40,14 +45,38 @@ export const WithColumns = () => {
     <ZStack height="100%" width="100%" minHeight="600px" minWidth="600px">
       <Page>
         <Columns>
+          <Column minWidth="400px">
+            <Scaffold>
+              <Header>
+                <Title>Tooling Header</Title>
+              </Header>
+              <Scaffold>
+                <Detail>
+                  <Card>
+                    <Header>Tooling 1</Header>
+                    <Scaffold>
+                      <SBContent />
+                    </Scaffold>
+                  </Card>
+
+                  <Card>
+                    <Header>Tooling 2</Header>
+                    <Scaffold>
+                      <SBContent />
+                    </Scaffold>
+                  </Card>
+                </Detail>
+              </Scaffold>
+            </Scaffold>
+          </Column>
           <Column minWidth="400px" width="fill">
             <Panel>
               <Header>
-                <Title>Left Panel</Title>
+                <Title>Primary</Title>
               </Header>
               <Scaffold>
                 <Detail>
-                  <BodyText>Left panel content</BodyText>
+                  <BodyText>Content</BodyText>
                 </Detail>
               </Scaffold>
             </Panel>
@@ -55,15 +84,66 @@ export const WithColumns = () => {
           <Column minWidth="400px">
             <Panel>
               <Header>
-                <Title>Right Panel</Title>
+                <Title>Secondary</Title>
+              </Header>
+              <Scaffold>
+                <Detail>
+                  <BodyText>Content</BodyText>
+                </Detail>
+              </Scaffold>
+            </Panel>
+          </Column>
+        </Columns>
+      </Page>
+    </ZStack>
+  );
+};
+
+/** WIP: Testing Resizable + ResizeHandle with a two-column layout */
+export const ResizableSecondaryColumn = () => {
+  const MIN_WIDTH = 200;
+  const MAX_WIDTH = 600;
+  const [secondaryWidth, setSecondaryWidth] = useState(350);
+
+  const atMin = secondaryWidth <= MIN_WIDTH;
+  const atMax = secondaryWidth >= MAX_WIDTH;
+  const constraint = atMin ? ' (At Min)' : atMax ? ' (At Max)' : '';
+
+  return (
+    <ZStack height="100%" width="100%" minHeight="600px" minWidth="600px">
+      <Page>
+        <Columns>
+          <Column width="fill">
+            <Panel>
+              <Header>
+                <Title>Primary</Title>
               </Header>
               <Scaffold>
                 <Detail>
-                  <BodyText>Right panel content</BodyText>
+                  <BodyText>Primary content fills remaining space.</BodyText>
                 </Detail>
               </Scaffold>
             </Panel>
           </Column>
+          <Resizable onWidthResize={({ width }) => setSecondaryWidth(Math.round(width))}>
+            <Column
+              width={`${secondaryWidth}px`}
+              minWidth={`${MIN_WIDTH}px`}
+              maxWidth={`${MAX_WIDTH}px`}
+            >
+              <Panel>
+                <Header>
+                  <Title>{`Secondary (${secondaryWidth}px)${constraint}`}</Title>
+                </Header>
+                <Scaffold>
+                  <Detail>
+                    <BodyText>Drag the start edge to resize this column.</BodyText>
+                  </Detail>
+                </Scaffold>
+              </Panel>
+            </Column>
+            <ResizeHandle position="start" />
+          </Resizable>
         </Columns>
       </Page>
     </ZStack>

package/src/surfaces/panel/__stories__/panel.stories.tsx

@@ -4,7 +4,7 @@ import { Footer } from '../../../layouts/footer/footer.js';
 import { Header } from '../../../layouts/header/header.js';
 import { Column } from '../../../layouts/containers/columns/column.js';
 import { Columns } from '../../../layouts/containers/columns/columns.js';
-import { Detail, Heading, Scaffold, Section } from '../../../layouts/index.js';
+import { Detail, Heading, Row, Rows, Scaffold, Section } from '../../../layouts/index.js';
 import { UtilityBar } from '../../../layouts/utility_bar/utility_bar.js';
 import { Box, HStack, Spacer } from '../../../stacks/index.js';
 import { Title } from '../../../typography/title/title.js';
@@ -345,21 +345,19 @@ export const WithColumns = () => {
                 <Heading>General</Heading>
                 <Detail>
                   <Term>
-                    <Key>Agent</Key>
-                    <Value>John Doe</Value>
+                    <Key>Email</Key>
+                    <Value>john.doe@example.com</Value>
                   </Term>
                   <Term>
-                    <Key>Queue</Key>
-                    <Value>Support</Value>
+                    <Key>Phone</Key>
+                    <Value>+1 555 000 1234</Value>
                   </Term>
                   <Term>
-                    <Key>Status</Key>
-                    <Value>Active</Value>
+                    <Key>Start Date</Key>
+                    <Value>05/27/2023</Value>
                   </Term>
                 </Detail>
               </Section>
-            </Column>
-            <Column minWidth="300px">
               <Section>
                 <Heading>Contact</Heading>
                 <Detail>
@@ -378,6 +376,83 @@ export const WithColumns = () => {
                 </Detail>
               </Section>
             </Column>
+            <Column minWidth="300px">
+              <Rows>
+                <Row>
+                  <Detail>
+                    <Term>
+                      <Key>Email</Key>
+                      <Value>john.doe@example.com</Value>
+                    </Term>
+                    <Term>
+                      <Key>Phone</Key>
+                      <Value>+1 555 000 1234</Value>
+                    </Term>
+                    <Term>
+                      <Key>Start Date</Key>
+                      <Value>05/27/2023</Value>
+                    </Term>
+                  </Detail>
+                </Row>
+                <Row>
+                  <Detail>
+                    <Term>
+                      <Key>Email</Key>
+                      <Value>john.doe@example.com</Value>
+                    </Term>
+                    <Term>
+                      <Key>Phone</Key>
+                      <Value>+1 555 000 1234</Value>
+                    </Term>
+                    <Term>
+                      <Key>Start Date</Key>
+                      <Value>05/27/2023</Value>
+                    </Term>
+                  </Detail>
+                </Row>
+              </Rows>
+            </Column>
+            <Column minWidth="300px">
+              <Card>
+                <Header>General</Header>
+                <Scaffold>
+                  <Detail>
+                    <Term>
+                      <Key>Email</Key>
+                      <Value>john.doe@example.com</Value>
+                    </Term>
+                    <Term>
+                      <Key>Phone</Key>
+                      <Value>+1 555 000 1234</Value>
+                    </Term>
+                    <Term>
+                      <Key>Start Date</Key>
+                      <Value>05/27/2023</Value>
+                    </Term>
+                  </Detail>
+                </Scaffold>
+              </Card>
+
+              <Card>
+                <Header>Contact</Header>
+                <Scaffold>
+                  <Detail>
+                    <Term>
+                      <Key>Email</Key>
+                      <Value>john.doe@example.com</Value>
+                    </Term>
+                    <Term>
+                      <Key>Phone</Key>
+                      <Value>+1 555 000 1234</Value>
+                    </Term>
+                    <Term>
+                      <Key>Start Date</Key>
+                      <Value>05/27/2023</Value>
+                    </Term>
+                  </Detail>
+                </Scaffold>
+              </Card>
+            </Column>
           </Columns>
         </Scaffold>
         <Footer>

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/test-setup.ts

@@ -0,0 +1,11 @@
+// ResizeObserver is not available in vitest's jsdom environment.
+// `use_resize_observer.ts` instantiates a registry singleton at module load
+// time, so this stub must be in place before any imports run.
+globalThis.ResizeObserver = class ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+};
+
+// Required for React's act() to work correctly in jsdom tests.
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;

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/theme.tsx

@@ -5,7 +5,6 @@ import { clsx } from 'clsx';
 // Styles
 import './stylesheets/reset.css';
 import styles from './theme_provider.module.css';
-import layers from '../css/layers.css?raw';
 
 export interface ThemeProps extends BoxProps {
   styleSheets: CSSStyleSheet[];
@@ -14,27 +13,18 @@ export interface ThemeProps extends BoxProps {
 }
 
 export function Theme({ styleSheets, children, className, ...boxProps }: ThemeProps) {
-  useLayoutEffect(() => {
-    document.adoptedStyleSheets = styleSheets;
-  }, [styleSheets]);
+  const ref = React.useRef<HTMLElement>(null);
 
-  // I used this approach instead to guarantee the order of the stylesheets
   useLayoutEffect(() => {
-    if (document.getElementById('critical-css')) return;
-
-    const style = document.createElement('style');
-    style.id = 'critical-css';
-    style.textContent = layers;
+    const root = ref.current?.getRootNode();
+    if (!root || !('adoptedStyleSheets' in root)) return;
 
-    document.head.prepend(style);
-
-    return () => {
-      document.getElementById('critical-css')?.remove();
-    };
-  }, []);
+    (root as Document | ShadowRoot).adoptedStyleSheets = styleSheets;
+  }, [styleSheets]);
 
   return (
     <Box
+      ref={ref}
       className={clsx('tcn-theme-root', styles['tcn-theme-provider'], className)}
       {...boxProps}
     >

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.