@tcn/ui 0.16.0 → 0.17.0

package/src/layouts/__stories__/rows.stories.tsx

@@ -0,0 +1,77 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { LayoutStoryDecorator } from './utils/layout_theme_provider.js';
+import { Row } from '../containers/rows/row.js';
+import { Rows } from '../containers/rows/rows.js';
+import { Detail, Section } from '../section/index.js';
+
+const meta: Meta = {
+  title: 'Layouts/Rows',
+  component: () => <></>,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Vertical container for fixed-height Row components. Theme controls row separation via the `.tcn-rows` context selector.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+/**
+ * Simple example of two rows stacked vertically.
+ */
+/**
+ * rowsMinHeight sets a default minHeight on all child Rows.
+ * An explicit minHeight prop on a Row overrides it.
+ */
+export const RowsMinHeight: Story = {
+  render: () => (
+    <LayoutStoryDecorator>
+      <Rows rowsMinHeight="80px">
+        <Row>
+          <Section>
+            <Detail>default (80px)</Detail>
+          </Section>
+        </Row>
+        <Row>
+          <Section>
+            <Detail>default (80px)</Detail>
+          </Section>
+        </Row>
+        <Row minHeight="160px">
+          <Section>
+            <Detail>override (160px)</Detail>
+          </Section>
+        </Row>
+      </Rows>
+    </LayoutStoryDecorator>
+  ),
+};
+
+/**
+ * Simple example of two rows stacked vertically.
+ */
+export const Baseline: Story = {
+  render: () => (
+    <LayoutStoryDecorator>
+      <Rows>
+        <Row minHeight="120px">
+          <Section>
+            <Detail>120px row</Detail>
+          </Section>
+        </Row>
+        <Row minHeight="120px">
+          <Section>
+            <Detail>120px row</Detail>
+          </Section>
+        </Row>
+      </Rows>
+    </LayoutStoryDecorator>
+  ),
+};

package/src/layouts/__stories__/utils.tsx

@@ -2,15 +2,9 @@ import type { PropsWithChildren } from 'react';
 import clsx from 'clsx';
 
 import { Scaffold, type ScaffoldProps } from '../containers/scaffold.js';
-import { Header } from '../header/header.js';
-import { Footer } from '../footer/footer.js';
-import { UtilityBar } from '../utility_bar/utility_bar.js';
 
 import { Rail, type RailProps } from '../containers/rail.js';
-import { Column } from '../containers/columns/column.js';
-import { Box, Spacer } from '../../stacks/index.js';
-import { UtilityStrip } from '../containers/utility_strip/utility_strip.js';
-import { SearchIcon } from '@tcn/icons/search_icon.js';
+import { Box } from '../../stacks/index.js';
 
 import styles from './composed_stories.module.css';
 
@@ -22,10 +16,6 @@ const FloatingLabel = ({ children }: { children: React.ReactNode }) => {
   );
 };
 
-const VerticalLabel = ({ children }: { children: React.ReactNode }) => {
-  return <span className={styles.verticalLabel}>{children}</span>;
-};
-
 export const SBContent: React.FC<
   PropsWithChildren<{ className?: string; minHeight?: string; minWidth?: string }>
 > = ({ className, children, minHeight = '200px', minWidth = '200px' }) => {
@@ -42,43 +32,14 @@ export const SBContent: React.FC<
   );
 };
 
-const SBActionBox = ({ children }: { children: React.ReactNode }) => {
-  return <span className={styles.actionBox}>{children}</span>;
-};
-
-const SBActions = () => {
-  return (
-    <>
-      <Spacer />
-      <SBActionBox>
-        <SearchIcon />
-      </SBActionBox>
-      <SBActionBox>
-        <SearchIcon />
-      </SBActionBox>
-      <SBActionBox>
-        <SearchIcon />
-      </SBActionBox>
-    </>
-  );
-};
-
 interface SBNestedRailProps extends RailProps {
   depth?: number;
-  scaffold?: boolean;
-  side?: boolean;
-  utilityStrip?: boolean;
-  label?: boolean;
 }
 
 export const SBNestedRail: React.FC<PropsWithChildren<SBNestedRailProps>> = ({
   children,
   className,
   depth = 1,
-  scaffold = true,
-  side = true,
-  utilityStrip = true,
-  label = true,
   height = '100%',
   ...props
 }) => {
@@ -89,51 +50,20 @@ export const SBNestedRail: React.FC<PropsWithChildren<SBNestedRailProps>> = ({
       data-depth={depth}
       {...props}
     >
-      {label && <FloatingLabel>Rail</FloatingLabel>}
-      {utilityStrip && (
-        <UtilityStrip className={clsx(styles.utilityStrip, styles.secondary)}>
-          <VerticalLabel>Utility Strip</VerticalLabel>
-          <SBActions />
-        </UtilityStrip>
-      )}
+      <FloatingLabel>Rail</FloatingLabel>
       {children}
-      {side && (
-        <Column className={clsx(styles.side, styles.secondary)} minWidth="200px">
-          <span>Column</span>
-        </Column>
-      )}
-      {scaffold && (
-        <SBNestedScaffold
-          depth={depth + 1}
-          utilityBar={false}
-          footer={false}
-          minWidth={'fit-content'}
-        >
-          <Scaffold>
-            <SBContent />
-            <SBContent />
-            <SBContent />
-          </Scaffold>
-        </SBNestedScaffold>
-      )}
     </Rail>
   );
 };
 
 interface SBNestedScaffoldProps extends ScaffoldProps {
   depth?: number;
-  header?: boolean;
-  utilityBar?: boolean;
-  footer?: boolean;
 }
 
 export const SBNestedScaffold: React.FC<PropsWithChildren<SBNestedScaffoldProps>> = ({
   children,
   className,
   depth = 1,
-  header = true,
-  utilityBar = true,
-  footer = true,
   height = '100%',
   ...props
 }) => {
@@ -145,19 +75,7 @@ export const SBNestedScaffold: React.FC<PropsWithChildren<SBNestedScaffoldProps>
       {...props}
     >
       <FloatingLabel>Scaffold</FloatingLabel>
-      {header && (
-        <Header className={clsx(styles.header, styles.secondary)}>Header</Header>
-      )}
-      {utilityBar && (
-        <UtilityBar className={clsx(styles.utilityBar, styles.secondary)}>
-          Utility Bar
-          <SBActions />
-        </UtilityBar>
-      )}
       {children}
-      {footer && (
-        <Footer className={clsx(styles.footer, styles.secondary)}>Footer</Footer>
-      )}
     </Scaffold>
   );
 };

package/src/layouts/containers/columns/column.module.css

@@ -2,8 +2,9 @@
   :where(.column) {
     height: 100%;
     min-height: 100%;
-    width: auto;
-    min-width: 0;
+    width: var(--columns-width, auto);
+    min-width: var(--columns-min-width, 0);
+    max-width: var(--columns-max-width, none);
     flex-grow: 0;
   }
 

package/src/layouts/containers/columns/columns.tsx

@@ -1,15 +1,41 @@
 import React from 'react';
 import { clsx } from 'clsx';
 import { Rail, type RailProps } from '../rail.js';
+import { removeUndefinedProperties } from '../../../stacks/utils/remove_undefined_properties.js';
 
-export interface ColumnsProps extends Omit<RailProps, 'as'> {}
+export interface ColumnsOwnProps {
+  columnsMinWidth?: string | number;
+  columnsWidth?: string | number;
+  columnsMaxWidth?: string | number;
+}
+
+export interface ColumnsProps extends Omit<RailProps, 'as'>, ColumnsOwnProps {}
 
 export const Columns = React.forwardRef<HTMLElement, ColumnsProps>(function Columns(
-  { children, className, ...props }: ColumnsProps,
+  {
+    children,
+    className,
+    columnsMinWidth,
+    columnsWidth,
+    columnsMaxWidth,
+    style,
+    ...props
+  }: ColumnsProps,
   ref
 ) {
+  const columnVars = removeUndefinedProperties({
+    '--columns-min-width': columnsMinWidth,
+    '--columns-width': columnsWidth,
+    '--columns-max-width': columnsMaxWidth,
+  });
+
   return (
-    <Rail ref={ref} className={clsx('tcn-columns', className)} {...props}>
+    <Rail
+      ref={ref}
+      className={clsx('tcn-columns', className)}
+      style={{ ...columnVars, ...style }}
+      {...props}
+    >
       {children}
     </Rail>
   );

package/src/layouts/containers/containers.module.css

@@ -1,55 +1,53 @@
 @layer tcn-system {
+  /* Outer or standalone scaffold fills its container */
   :where(.scaffold) {
-    max-height: 100%;
+    height: 100%;
     width: 100%;
-    height: auto;
+    max-height: 100%;
+    overflow: auto;
   }
 
+  /* Outer or standalone Rail fills its container */
   :where(.rail) {
     max-width: 100%;
     height: 100%;
-    width: auto;
-  }
-
-  :where(.container) > :where(.container-stack) {
     width: 100%;
-    height: 100%;
+    overflow: auto;
   }
 
-  /* Scaffold base — layout frame only, no overflow clipping */
-  :where(.scaffold) > :where(.scaffold-stack) {
-    overflow-y: auto;
+  /* Nested Containers should grow via flex-grow */
+  :where(.container) > .container {
+    flex-grow: 1;
+    /* Important - override the Stack css  */
+    flex-shrink: unset;
   }
 
-  /* Switching direction - rail fills scaffold width */
-  :where(.scaffold) > :where(.scaffold-stack) > :where(.rail) {
-    width: 100%;
+  /* Child Scaffolds should use flex-grow to manage height - scroll vertically */
+  :where(.container) > .scaffold {
+    overflow-y: auto;
+    min-height: 0;
   }
 
-  /* Switching direction - scaffold fills rail height */
-  :where(.rail) > :where(.rail-stack) > :where(.scaffold) {
-    height: 100%;
+  :where(.scaffold) > .scaffold {
+    height: auto;
   }
 
-  /* Rail base — layout frame only, no overflow clipping */
-  :where(.rail) > :where(.rail-stack) {
+  /* Child Rails should use flex-grow to manage width - scroll horizontally */
+  :where(.container) > .rail {
     overflow-x: auto;
+    min-width: 0;
   }
 
-  /* container grows to fill remaining space */
-  :where(.container-stack) > :where(.container) {
-    flex-grow: 1;
+  :where(.rail) > .rail {
+    width: auto;
   }
 
-  /* container nested Scaffold scrolls vertically */
-  :where(.container-stack) > :where(.scaffold) {
-    min-height: 0;
-    overflow-y: auto;
+  /* The opposite axis of the flex grow should fill via height or width */
+  :where(.rail) > .container {
+    height: 100%;
   }
 
-  /*  container nested Rail scrolls horizontally */
-  :where(.container-stack) > :where(.rail) {
-    min-width: 0;
-    overflow-x: auto;
+  :where(.scaffold) > .container {
+    width: 100%;
   }
 }

package/src/layouts/containers/rail.tsx

@@ -1,44 +1,20 @@
 import React from 'react';
 import { clsx } from 'clsx';
-import { Box, type BoxProps } from '../../stacks/box/box.js';
-import type { Alignment } from '../../stacks/types/alignment.js';
-import { HStack } from '../../stacks/h_stack.js';
-
+import { HStack, type HStackProps } from '../../stacks/h_stack.js';
 import styles from './containers.module.css';
 
-export interface RailProps extends Omit<BoxProps, 'as'> {
-  vAlign?: Alignment;
-  hAlign?: Alignment;
-}
+export interface RailProps extends Omit<HStackProps, 'as'> {}
 
-// WIP: This component is not fully implemented.
 export const Rail = React.forwardRef<HTMLElement, RailProps>(function Rail(
-  {
-    children,
-    width,
-    height,
-    minWidth,
-    maxWidth,
-    minHeight,
-    maxHeight,
-    hAlign = 'start',
-    vAlign = 'start',
-    className,
-    ...props
-  }: RailProps,
+  { children, className, vAlign = 'start', hAlign = 'start', ...props }: RailProps,
   ref
 ) {
   return (
-    <Box
+    <HStack
       ref={ref}
-      width={width}
-      height={height}
-      minWidth={minWidth}
-      maxWidth={maxWidth}
-      minHeight={minHeight}
-      maxHeight={maxHeight}
-      data-h-alignment={hAlign}
-      data-v-alignment={vAlign}
+      as="section"
+      vAlign={vAlign}
+      hAlign={hAlign}
       className={clsx(
         className,
         styles['rail'],
@@ -48,25 +24,7 @@ export const Rail = React.forwardRef<HTMLElement, RailProps>(function Rail(
       )}
       {...props}
     >
-      <HStack
-        as="section"
-        minWidth={minWidth}
-        maxWidth={maxWidth}
-        minHeight={minHeight}
-        maxHeight={maxHeight}
-        hAlign={hAlign}
-        vAlign={vAlign}
-        ref={ref}
-        className={clsx(
-          styles['rail-stack'],
-          styles['container-stack'],
-          'tcn-container-stack',
-          'tcn-rail-stack'
-        )}
-        zIndex={0}
-      >
-        {children}
-      </HStack>
-    </Box>
+      {children}
+    </HStack>
   );
 });

package/src/layouts/containers/rows/index.ts

@@ -0,0 +1,2 @@
+export { Row, type RowProps } from './row.js';
+export { Rows, type RowsProps } from './rows.js';

package/src/layouts/containers/rows/row.module.css

@@ -0,0 +1,15 @@
+@layer tcn-system {
+  :where(.row) {
+    width: 100%;
+    min-width: 0;
+    height: var(--rows-height, auto);
+    min-height: var(--rows-min-height, 0);
+    max-height: var(--rows-max-height, none);
+    flex-grow: 0;
+  }
+
+  :where(.row[data-height="fill"]) {
+    flex-grow: 1;
+    height: 0; /* let flex-grow determine height, not content */
+  }
+}

package/src/layouts/containers/rows/row.tsx

@@ -0,0 +1,22 @@
+import React from 'react';
+import { clsx } from 'clsx';
+import { HStack, type HStackProps } from '../../../stacks/h_stack.js';
+import styles from './row.module.css';
+
+export interface RowProps extends Omit<HStackProps, 'as'> {}
+
+export const Row = React.forwardRef<HTMLElement, RowProps>(function Row(
+  { children, className, ...props }: RowProps,
+  ref
+) {
+  return (
+    <HStack
+      ref={ref}
+      as="section"
+      className={clsx('tcn-row', styles['row'], className)}
+      {...props}
+    >
+      {children}
+    </HStack>
+  );
+});

package/src/layouts/containers/rows/rows.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import { clsx } from 'clsx';
+import { Scaffold, type ScaffoldProps } from '../scaffold.js';
+import { removeUndefinedProperties } from '../../../stacks/utils/remove_undefined_properties.js';
+
+export interface RowsOwnProps {
+  rowsMinHeight?: string | number;
+  rowsHeight?: string | number;
+  rowsMaxHeight?: string | number;
+}
+
+export interface RowsProps extends Omit<ScaffoldProps, 'as'>, RowsOwnProps {}
+
+export const Rows = React.forwardRef<HTMLElement, RowsProps>(function Rows(
+  {
+    children,
+    className,
+    rowsMinHeight,
+    rowsHeight,
+    rowsMaxHeight,
+    style,
+    ...props
+  }: RowsProps,
+  ref
+) {
+  const rowVars = removeUndefinedProperties({
+    '--rows-min-height': rowsMinHeight,
+    '--rows-height': rowsHeight,
+    '--rows-max-height': rowsMaxHeight,
+  });
+
+  return (
+    <Scaffold
+      ref={ref}
+      className={clsx('tcn-rows', className)}
+      style={{ ...rowVars, ...style }}
+      {...props}
+    >
+      {children}
+    </Scaffold>
+  );
+});

package/src/layouts/containers/scaffold.tsx

@@ -1,42 +1,20 @@
 import React from 'react';
 import { clsx } from 'clsx';
-import { Box, type BoxProps } from '../../stacks/box/box.js';
-import type { Alignment } from '../../stacks/types/alignment.js';
-import { VStack } from '../../stacks/v_stack.js';
+import { VStack, type VStackProps } from '../../stacks/v_stack.js';
 import styles from './containers.module.css';
 
-export interface ScaffoldProps extends Omit<BoxProps, 'as'> {
-  vAlign?: Alignment;
-  hAlign?: Alignment;
-}
+export interface ScaffoldProps extends Omit<VStackProps, 'as'> {}
 
 export const Scaffold = React.forwardRef<HTMLElement, ScaffoldProps>(function Scaffold(
-  {
-    children,
-    width,
-    height,
-    minWidth,
-    maxWidth,
-    minHeight,
-    maxHeight,
-    hAlign = 'start',
-    vAlign = 'start',
-    className,
-    ...props
-  }: ScaffoldProps,
+  { children, className, vAlign = 'start', hAlign = 'start', ...props }: ScaffoldProps,
   ref
 ) {
   return (
-    <Box
+    <VStack
       ref={ref}
-      width={width}
-      height={height}
-      minWidth={minWidth}
-      maxWidth={maxWidth}
-      minHeight={minHeight}
-      maxHeight={maxHeight}
-      data-h-alignment={hAlign}
-      data-v-alignment={vAlign}
+      as="section"
+      vAlign={vAlign}
+      hAlign={hAlign}
       className={clsx(
         className,
         styles['scaffold'],
@@ -46,25 +24,7 @@ export const Scaffold = React.forwardRef<HTMLElement, ScaffoldProps>(function Sc
       )}
       {...props}
     >
-      <VStack
-        as="section"
-        minWidth={minWidth}
-        maxWidth={maxWidth}
-        minHeight={minHeight}
-        maxHeight={maxHeight}
-        hAlign={hAlign}
-        vAlign={vAlign}
-        ref={ref}
-        className={clsx(
-          styles['scaffold-stack'],
-          styles['container-stack'],
-          'tcn-container-stack',
-          'tcn-scaffold-stack'
-        )}
-        zIndex={0}
-      >
-        {children}
-      </VStack>
-    </Box>
+      {children}
+    </VStack>
   );
 });

package/src/layouts/index.ts

@@ -21,6 +21,8 @@ export { TTable, THead, TBody, TFoot, TR, TH, TD } from './table/table.js';
 
 export { Rail, type RailProps } from './containers/rail.js';
 export { Columns, type ColumnsProps } from './containers/columns/columns.js';
+export { Row, type RowProps } from './containers/rows/row.js';
+export { Rows, type RowsProps } from './containers/rows/rows.js';
 export {
   UtilityStrip,
   type UtilityStripProps,

package/src/stacks/box/detect_resize_bounds.ts

@@ -11,6 +11,7 @@ export type DetectResizeBoundsResult = {
   hitMin: boolean;
   hitMax: boolean;
   clamped: boolean;
+  clampedSize: number | null;
 };
 
 const styleKeys = {
@@ -36,10 +37,12 @@ function detectByPixelValue(nextSize: number, min: string, max: string) {
   const maxPx = parsePx(max);
   const hitMin = minPx !== null && nextSize < minPx;
   const hitMax = maxPx !== null && nextSize > maxPx;
+  const clamped = hitMin || hitMax;
   return {
     hitMin,
     hitMax,
-    clamped: hitMin || hitMax,
+    clamped,
+    clampedSize: clamped ? (hitMin ? minPx : maxPx) : null,
   };
 }
 
@@ -76,6 +79,7 @@ export function detectResizeBounds({
       hitMin,
       hitMax,
       clamped,
+      clampedSize: clamped ? renderedSize : null,
     };
   } finally {
     // revert the style change

package/src/surfaces/card/card.module.css

@@ -0,0 +1,5 @@
+@layer tcn-system {
+  .card {
+    height: auto;
+  }
+}