@textui/widgets 0.1.0

package/src/shells/index.ts

@@ -0,0 +1,66 @@
+import type { ComponentDefinition, ShellDefinition } from '@textui/core';
+import { ConsoleShell } from './console-shell.js';
+import { PaperShell } from './paper-shell.js';
+import { PlainShell } from './plain-shell.js';
+import { WorkbenchShell } from './workbench-shell.js';
+
+/**
+ * Shells.
+ *
+ * A shell decides where the surfaces go, and that is the whole of what it
+ * decides. The three below are the same application in three house styles -
+ * a dense bordered console, an airy report, and a workbench frame - and
+ * nothing in the component catalog knows which one is mounted.
+ *
+ * That is the test the whole architecture exists to pass: if a shell needs a
+ * component the others cannot use, the boundary is in the wrong place.
+ */
+export * from './console-shell.js';
+export * from './paper-shell.js';
+export * from './plain-shell.js';
+export * from './workbench-shell.js';
+export type { ShellProps } from './shared.js';
+
+export const SHELL_COMPONENTS: ComponentDefinition[] = [
+  { component: 'PlainShell', category: 'chrome', renderer: { kind: 'function', render: PlainShell }, description: 'Main and status, no frame.' },
+  { component: 'ConsoleShell', category: 'chrome', renderer: { kind: 'function', render: ConsoleShell }, description: 'Dense bordered operator console.' },
+  { component: 'PaperShell', category: 'chrome', renderer: { kind: 'function', render: PaperShell }, description: 'Airy and borderless.' },
+  { component: 'WorkbenchShell', category: 'chrome', renderer: { kind: 'function', render: WorkbenchShell }, description: 'Full frame: rail, sidebar, tabs, panel, status.' },
+];
+
+export const BUILTIN_SHELLS: ShellDefinition[] = [
+  {
+    id: 'plain',
+    title: 'Plain',
+    description: 'Main and status only. The default.',
+    component: 'PlainShell',
+    surfaces: ['main', 'status', 'overlay', 'notify'],
+  },
+  {
+    id: 'console',
+    title: 'Console',
+    description: 'Dense, bordered, every region labelled.',
+    component: 'ConsoleShell',
+    theme: 'console',
+    surfaces: ['header', 'sidebar', 'main', 'panel', 'aside', 'status', 'overlay', 'notify'],
+    minSize: { width: 60, height: 12 },
+  },
+  {
+    id: 'paper',
+    title: 'Paper',
+    description: 'Borderless. Whitespace and alignment do the separating.',
+    component: 'PaperShell',
+    theme: 'paper',
+    surfaces: ['header', 'main', 'panel', 'status', 'overlay', 'notify'],
+    minSize: { width: 50, height: 10 },
+  },
+  {
+    id: 'workbench',
+    title: 'Workbench',
+    description: 'Persistent frame with a rail, sidebar, tabs and a panel.',
+    component: 'WorkbenchShell',
+    theme: 'workbench',
+    surfaces: ['header', 'rail', 'sidebar', 'main', 'panel', 'aside', 'status', 'overlay', 'notify'],
+    minSize: { width: 80, height: 20 },
+  },
+];

package/src/shells/paper-shell.ts

@@ -0,0 +1,31 @@
+import { defineComponent, h, useTheme } from '@textui/core';
+import { ToastHost } from '../overlay/index.js';
+import { SurfaceArea } from '../surface/index.js';
+import type { ShellProps } from './shared.js';
+
+/**
+ * Direction B: airy and borderless.
+ *
+ * Whitespace does the separating; there is no frame, and the surfaces that
+ * would be chrome elsewhere are simply spaced sections. Also the shell that
+ * reads best when the output is piped to a file.
+ */
+export const PaperShell = defineComponent<ShellProps>('PaperShell', (props) => {
+  const theme = useTheme();
+  return h('box', {
+    direction: 'column',
+    width: '100%',
+    height: '100%',
+    bg: 'canvas',
+    fg: 'text',
+    padding: [1, theme.spacing.md],
+    gap: 1,
+    ...props,
+  },
+    h(SurfaceArea, { surface: 'header' }),
+    h(SurfaceArea, { surface: 'main', flex: 1 }),
+    h(SurfaceArea, { surface: 'panel' }),
+    h(SurfaceArea, { surface: 'status' }),
+    h(ToastHost, { anchor: 'bottom' }),
+  );
+});

package/src/shells/plain-shell.ts

@@ -0,0 +1,19 @@
+import { defineComponent, h } from '@textui/core';
+import { ToastHost } from '../overlay/index.js';
+import { SurfaceArea } from '../surface/index.js';
+import type { ShellProps } from './shared.js';
+
+/** No chrome at all: `main` fills the terminal. For a single-screen tool. */
+export const PlainShell = defineComponent<ShellProps>('PlainShell', (props) =>
+  h('box', {
+    direction: 'column', width: '100%', height: '100%',
+    // Ink as well as page: a themed background with the terminal's own
+    // foreground on top is how a light theme comes out white on white.
+    bg: 'canvas', fg: 'text',
+    ...props,
+  },
+    h(SurfaceArea, { surface: 'main', flex: 1 }),
+    h(SurfaceArea, { surface: 'status' }),
+    h(ToastHost, { anchor: 'bottom-right' }),
+  ),
+);

package/src/shells/shared.ts

@@ -0,0 +1,24 @@
+import type { BindingPath, BoxProps, SurfaceName } from '@textui/core';
+import { useRuntime, useStoreSubtree } from '@textui/core';
+
+export type ShellProps = BoxProps;
+
+/**
+ * Whether a surface has anything to show.
+ *
+ * `SurfaceArea` already renders nothing for an empty surface, but a region
+ * with a fixed width reserves its column either way - which is how an
+ * application that never mounts a sidebar still gets an empty gutter down the
+ * left of every screen. A shell has to ask before it spends the space.
+ */
+export function useSurfaceMounted(surface: SurfaceName): boolean {
+  const runtime = useRuntime();
+  useStoreSubtree(`$/layout/surfaces/${surface}` as BindingPath);
+  useStoreSubtree(`$/layout/mounts/${surface}` as BindingPath);
+
+  const app = runtime.app();
+  if (!app) return false;
+  const state = app.surfaces.state(surface);
+  if (!state.visible || state.collapsed) return false;
+  return app.surfaces.mounts(surface).length > 0;
+}

package/src/shells/workbench-shell.ts

@@ -0,0 +1,62 @@
+import { defineComponent, h, useSize, useStoreValue, useTheme } from '@textui/core';
+import { ToastHost } from '../overlay/index.js';
+import { SurfaceArea } from '../surface/index.js';
+import type { ShellProps } from './shared.js';
+import { useSurfaceMounted } from './shared.js';
+
+/**
+ * Direction C: the workbench.
+ *
+ * A persistent frame - rail, sidebar, tabbed main, panel, status - inside a
+ * rounded border. The richest shell, and the one that needs the most room, so
+ * it declares a minimum size and the app falls back when the terminal is small.
+ */
+export const WorkbenchShell = defineComponent<ShellProps>('WorkbenchShell', (props) => {
+  const theme = useTheme();
+  const size = useSize();
+  const sidebarCollapsed = useStoreValue<boolean>('$/ui/sidebar/collapsed', false);
+  const asideVisible = useStoreValue<boolean>('$/ui/aside/visible', false);
+  const sidebar = useSurfaceMounted('sidebar');
+  const aside = useSurfaceMounted('aside');
+  const narrow = size.width < 90;
+
+  return h('box', {
+    direction: 'column',
+    width: '100%',
+    height: '100%',
+    bg: 'canvas',
+    fg: 'text',
+    border: theme.border,
+    ...props,
+  },
+    h(SurfaceArea, { surface: 'header' }),
+
+    h('box', { direction: 'row', flex: 1 },
+      h(SurfaceArea, { surface: 'rail' }),
+
+      sidebar && !sidebarCollapsed && !narrow
+        ? h('box', {
+            width: 24,
+            border: { style: theme.border, sides: { right: true } },
+            direction: 'column',
+            padding: { left: 1 },
+          }, h(SurfaceArea, { surface: 'sidebar', flex: 1 }))
+        : null,
+
+      h('box', { flex: 1, direction: 'column', padding: { left: 1 } },
+        h(SurfaceArea, { surface: 'main', flex: 1 }),
+        h(SurfaceArea, { surface: 'panel' })),
+
+      aside && asideVisible && !narrow
+        ? h('box', {
+            width: 30,
+            border: { style: theme.border, sides: { left: true } },
+            direction: 'column',
+            padding: { left: 1 },
+          }, h(SurfaceArea, { surface: 'aside', flex: 1 }))
+        : null),
+
+    h(SurfaceArea, { surface: 'status' }),
+    h(ToastHost, { anchor: 'bottom-right' }),
+  );
+});

package/src/surface/bar-layout.ts

@@ -0,0 +1,11 @@
+import { defineComponent, h } from '@textui/core';
+import { MountView } from './mount-view.js';
+import type { LayoutProps } from './shared.js';
+
+/** Every mount on one line. Headers and status bars use this. */
+export const BarLayout = defineComponent<LayoutProps>('BarLayout', (props) => {
+  const { mounts, surface: _surface, state: _state, ...rest } = props;
+  return h('box', { direction: 'row', height: 1, gap: 2, ...rest },
+    ...mounts.map((mount) => h(MountView, { key: mount.key, mount })),
+  );
+});

package/src/surface/index.ts

@@ -0,0 +1,53 @@
+import type { ComponentDefinition } from '@textui/core';
+import { BarLayout } from './bar-layout.js';
+import { InlineLayout } from './inline-layout.js';
+import { MountView } from './mount-view.js';
+import { RailLayout } from './rail-layout.js';
+import { SingleLayout } from './single-layout.js';
+import { SplitLayout } from './split-layout.js';
+import { StackLayout } from './stack-layout.js';
+import { SurfaceArea } from './surface-area.js';
+import { TabsLayout } from './tabs-layout.js';
+
+/**
+ * Surfaces, mounts and layouts.
+ *
+ * `SurfaceArea` is the only bridge between the registries and the render tree:
+ * it reads a surface's mounts and its state, then hands both to whichever
+ * layout that surface is currently using. Because the layout is store state
+ * rather than code, a sidebar can be tabs now and a stack a keystroke later.
+ */
+export * from './bar-layout.js';
+export * from './inline-layout.js';
+export * from './mount-view.js';
+export * from './rail-layout.js';
+export * from './single-layout.js';
+export * from './split-layout.js';
+export * from './stack-layout.js';
+export * from './surface-area.js';
+export * from './tabs-layout.js';
+export type { LayoutProps } from './shared.js';
+
+export const SURFACE_COMPONENTS: ComponentDefinition[] = [
+  { component: 'SurfaceArea', category: 'chrome', renderer: { kind: 'function', render: SurfaceArea }, description: 'Renders one surface through its active layout.' },
+  { component: 'MountView', category: 'chrome', renderer: { kind: 'function', render: MountView }, description: 'Renders one mount target.' },
+  { component: 'SingleLayout', category: 'chrome', renderer: { kind: 'function', render: SingleLayout }, description: 'Only the active mount.' },
+  { component: 'TabsLayout', category: 'chrome', renderer: { kind: 'function', render: TabsLayout }, description: 'Tab strip plus the active mount.' },
+  { component: 'StackLayout', category: 'chrome', renderer: { kind: 'function', render: StackLayout }, description: 'All mounts, stacked with headings.' },
+  { component: 'SplitLayout', category: 'chrome', renderer: { kind: 'function', render: SplitLayout }, description: 'All mounts, side by side.' },
+  { component: 'BarLayout', category: 'chrome', renderer: { kind: 'function', render: BarLayout }, description: 'All mounts on one line.' },
+  { component: 'RailLayout', category: 'chrome', renderer: { kind: 'function', render: RailLayout }, description: 'Icons only.' },
+  { component: 'InlineLayout', category: 'chrome', renderer: { kind: 'function', render: InlineLayout }, description: 'All mounts, no chrome.' },
+];
+
+export const BUILTIN_LAYOUTS = [
+  { name: 'single' as const, component: 'SingleLayout', title: 'Single' },
+  { name: 'tabs' as const, component: 'TabsLayout', title: 'Tabs' },
+  { name: 'stack' as const, component: 'StackLayout', title: 'Stack' },
+  { name: 'split' as const, component: 'SplitLayout', title: 'Split' },
+  { name: 'bar' as const, component: 'BarLayout', title: 'Bar' },
+  { name: 'rail' as const, component: 'RailLayout', title: 'Rail' },
+  { name: 'inline' as const, component: 'InlineLayout', title: 'Inline' },
+  { name: 'floating' as const, component: 'InlineLayout', title: 'Floating' },
+  { name: 'toast' as const, component: 'StackLayout', title: 'Toast' },
+];

package/src/surface/inline-layout.ts

@@ -0,0 +1,11 @@
+import { defineComponent, h } from '@textui/core';
+import { MountView } from './mount-view.js';
+import type { LayoutProps } from './shared.js';
+
+/** Every mount, no chrome at all. */
+export const InlineLayout = defineComponent<LayoutProps>('InlineLayout', (props) => {
+  const { mounts, surface: _surface, state: _state, ...rest } = props;
+  return h('box', { direction: 'column', flex: 1, ...rest },
+    ...mounts.map((mount) => h(MountView, { key: mount.key, mount })),
+  );
+});

package/src/surface/mount-view.ts

@@ -0,0 +1,30 @@
+import type { BindingPath, BoxProps, ComponentNode, Mount } from '@textui/core';
+import { defineComponent, h, useRuntime } from '@textui/core';
+import { EmptyState } from '../display/index.js';
+
+export interface MountViewProps extends BoxProps {
+  mount: Mount;
+}
+
+/** Renders one mount's target - an inline node, or a node read from a path. */
+export const MountView = defineComponent<MountViewProps>('MountView', ({ mount, ...rest }) => {
+  const runtime = useRuntime();
+
+  const target = mount.target;
+  const node: ComponentNode | null =
+    'component' in target
+      ? target
+      : (runtime.store.get<ComponentNode>((target as { path: BindingPath }).path) ?? null);
+
+  if (!node) {
+    return h(EmptyState, { title: 'Nothing mounted', ...rest });
+  }
+
+  // A mount's data context makes relative paths inside it resolve against the
+  // record it was opened for.
+  const withContext = mount.dataContext
+    ? { ...node, dataContext: mount.dataContext }
+    : node;
+
+  return h('box', { flex: 1, direction: 'column', ...rest }, withContext);
+});

package/src/surface/rail-layout.ts

@@ -0,0 +1,27 @@
+import { defineComponent, h, useRuntime, useTheme } from '@textui/core';
+import type { LayoutProps } from './shared.js';
+
+/** Icons only, one per mount. An activity bar. */
+export const RailLayout = defineComponent<LayoutProps>('RailLayout', (props) => {
+  const runtime = useRuntime();
+  const theme = useTheme();
+  const { mounts, state, surface, ...rest } = props;
+  const app = runtime.app();
+
+  return h('box', { direction: 'column', width: 3, align: 'center', ...rest },
+    ...mounts.map((mount) => {
+      const active = mount.key === state.activeKey;
+      return h('box', {
+        key: mount.key,
+        direction: 'row',
+        gap: 0,
+        fg: active ? 'accent' : 'muted',
+        bold: active,
+        onClick: () => app?.surfaces.activate(surface, mount.key),
+      },
+        h('text', { content: active ? theme.glyphs.chevronRight : ' ' }),
+        h('text', { content: mount.display?.icon ?? mount.key.slice(0, 1).toUpperCase() }),
+      );
+    }),
+  );
+});

package/src/surface/shared.ts

@@ -0,0 +1,7 @@
+import type { BoxProps, Mount, SurfaceName, SurfaceState } from '@textui/core';
+
+export interface LayoutProps extends BoxProps {
+  surface: SurfaceName;
+  mounts: Mount[];
+  state: SurfaceState;
+}

package/src/surface/single-layout.ts

@@ -0,0 +1,25 @@
+import { defineComponent, h } from '@textui/core';
+import { MountView } from './mount-view.js';
+import type { LayoutProps } from './shared.js';
+
+/** Only the active mount. */
+export const SingleLayout = defineComponent<LayoutProps>('SingleLayout', (props) => {
+  const { mounts, state, surface: _surface, ...rest } = props;
+  const active = mounts.find((m) => m.key === state.activeKey) ?? mounts[0];
+  if (!active) return null;
+
+  // A mount that declares a title gets one drawn, the same rule `stack`
+  // follows. It matters more here: `stack` shows everything at once, so which
+  // panel you are looking at is never a question, and this one shows one of
+  // several and answers it no other way.
+  if (active.display?.title === undefined) return h(MountView, { mount: active, ...rest });
+  return h('box', { direction: 'column', flex: 1, ...rest },
+    h('box', { direction: 'row', gap: 1 },
+      h('text', { content: active.display.title, bold: true, fg: 'muted' }),
+      active.display.badge !== undefined
+        ? h('text', { content: String(active.display.badge), fg: 'subtle' })
+        : null,
+      h('spacer', { flex: 1 })),
+    h(MountView, { mount: active, flex: 1 }),
+  );
+});

package/src/surface/split-layout.ts

@@ -0,0 +1,11 @@
+import { defineComponent, h } from '@textui/core';
+import { MountView } from './mount-view.js';
+import type { LayoutProps } from './shared.js';
+
+/** Every mount, side by side, sharing the space. */
+export const SplitLayout = defineComponent<LayoutProps>('SplitLayout', (props) => {
+  const { mounts, surface: _surface, state: _state, direction = 'row', ...rest } = props;
+  return h('box', { direction, flex: 1, gap: 1, ...rest },
+    ...mounts.map((mount) => h(MountView, { key: mount.key, mount, flex: 1 })),
+  );
+});

package/src/surface/stack-layout.ts

@@ -0,0 +1,32 @@
+import { defineComponent, h, useTheme } from '@textui/core';
+import { MountView } from './mount-view.js';
+import type { LayoutProps } from './shared.js';
+
+/** Every mount, stacked, each under its own heading. */
+export const StackLayout = defineComponent<LayoutProps>('StackLayout', (props) => {
+  const theme = useTheme();
+  const { mounts, surface: _surface, state: _state, ...rest } = props;
+
+  return h('box', { direction: 'column', flex: 1, ...rest },
+    ...mounts.map((mount, i) =>
+      // Each mount fills its share of the surface rather than only what its
+      // own content needs. A content-sized wrapper hands a viewport no height
+      // to measure, and a tree inside one reports a rect of 3 rows in a
+      // twenty-row sidebar - or of 0, once its content overflows.
+      h('box', { key: mount.key, direction: 'column', flex: 1 },
+        mount.display?.title
+          ? h('box', { direction: 'row', gap: 1 },
+              h('text', { content: mount.display.title, bold: true, fg: 'muted' }),
+              mount.display.badge !== undefined
+                ? h('text', { content: String(mount.display.badge), fg: 'subtle' })
+                : null,
+              h('spacer', { flex: 1 }))
+          : null,
+        h(MountView, { mount }),
+        // A rule separates two mounts. After the last one it separates a mount
+        // from nothing, which is a line under a sidebar with one panel in it.
+        i < mounts.length - 1
+          ? h('box', { height: 1, fill: theme.borderChars().top, fg: 'borderSubtle' })
+          : null)),
+  );
+});

package/src/surface/surface-area.ts

@@ -0,0 +1,46 @@
+import type { BindingPath, BoxProps, ComponentNode, SurfaceName } from '@textui/core';
+import { defineComponent, h, useRuntime, useStoreSubtree } from '@textui/core';
+
+export interface SurfaceAreaProps extends BoxProps {
+  surface: SurfaceName;
+  /** Override the surface's stored layout. */
+  layout?: string;
+  /** Rendered when the surface has no visible mounts. */
+  fallback?: ComponentNode;
+}
+
+/**
+ * Render one surface through its active layout.
+ *
+ * This subscribes to the surface's state and mount list rather than to the
+ * whole store, so opening a tab in `main` does not re-render the status bar.
+ */
+export const SurfaceArea = defineComponent<SurfaceAreaProps>('SurfaceArea', (props) => {
+  const runtime = useRuntime();
+  const { surface, layout: layoutOverride, fallback, ...rest } = props;
+
+  // Subscribing to both paths is what makes a surface reactive.
+  useStoreSubtree(`$/layout/surfaces/${surface}` as BindingPath);
+  useStoreSubtree(`$/layout/mounts/${surface}` as BindingPath);
+
+  const app = runtime.app();
+  if (!app) return null;
+
+  const state = app.surfaces.state(surface);
+  if (!state.visible || state.collapsed) return null;
+
+  const mounts = app.surfaces.mounts(surface);
+  if (mounts.length === 0) return fallback ? h('box', { ...rest }, fallback) : null;
+
+  const layoutName = layoutOverride ?? state.layout;
+  const definition = app.layouts.get(layoutName);
+
+  if (!definition) {
+    return h('text', {
+      content: `[textui] no layout registered as "${layoutName}"`,
+      fg: 'danger',
+    });
+  }
+
+  return h(definition.component, { surface, mounts, state, ...rest });
+});

package/src/surface/tabs-layout.ts

@@ -0,0 +1,30 @@
+import { defineComponent, h, useRuntime } from '@textui/core';
+import { Tabs } from '../navigation/index.js';
+import { MountView } from './mount-view.js';
+import type { LayoutProps } from './shared.js';
+
+/** A tab strip and the active mount. */
+export const TabsLayout = defineComponent<LayoutProps>('TabsLayout', (props) => {
+  const runtime = useRuntime();
+  const { mounts, state, surface, ...rest } = props;
+  if (mounts.length === 0) return null;
+
+  const active = mounts.find((m) => m.key === state.activeKey) ?? mounts[0];
+  const app = runtime.app();
+
+  return h('box', { direction: 'column', flex: 1, ...rest },
+    mounts.length > 1
+      ? h(Tabs, {
+          items: mounts.map((m) => ({
+            id: m.key,
+            label: m.display?.title ?? m.key,
+            icon: m.display?.icon,
+            badge: m.display?.badge,
+          })),
+          activeId: active?.key,
+          onChange: (key: string) => app?.surfaces.activate(surface, key),
+        })
+      : null,
+    active ? h(MountView, { mount: active, flex: 1 }) : null,
+  );
+});

package/src/tone.ts

@@ -0,0 +1,48 @@
+import type { SemanticVariant, StyleColor } from '@textui/core';
+
+/**
+ * The two halves of a tone.
+ *
+ * `TONE` is the colour a tone is drawn *in*; `ON_TONE` is what is written *on*
+ * it once it becomes a background. They belong together and are stated once,
+ * because a component that pairs `danger` with the wrong foreground produces
+ * the one thing a status colour must never be, which is unreadable.
+ *
+ * The theme states an `on*` token per tone rather than a single "inverted" for
+ * all of them: the contrast that works on a green fill is not the one that
+ * works on a red one.
+ */
+export const TONE: Record<SemanticVariant, StyleColor> = {
+  default: 'text',
+  primary: 'primary',
+  secondary: 'secondary',
+  accent: 'accent',
+  success: 'success',
+  warning: 'warning',
+  danger: 'danger',
+  info: 'info',
+  muted: 'muted',
+};
+
+// Adding a tone, or renaming an `on*` token, means three edits and only two of
+// them are checked:
+//
+//   1. this map and its `TONE` pair;
+//   2. every theme in themes/builtin.ts, or the token resolves to nothing;
+//   3. the palette list in docs/themes/tokens.md - which `pnpm docs:check`
+//      does NOT catch, because that check reads component prop interfaces and
+//      knows nothing about token names.
+//
+// The third is the one that gets missed. `onDefault`, `onSecondary` and
+// `onMuted` were absent from that page until they were added by hand.
+export const ON_TONE: Record<SemanticVariant, StyleColor> = {
+  default: 'onDefault',
+  primary: 'onPrimary',
+  secondary: 'onSecondary',
+  accent: 'onAccent',
+  success: 'onSuccess',
+  warning: 'onWarning',
+  danger: 'onDanger',
+  info: 'onInfo',
+  muted: 'onMuted',
+};

package/src/viewport.ts

@@ -0,0 +1,45 @@
+import type { Rect, Dimension } from '@textui/core';
+
+/**
+ * How many rows a scrolling component should draw.
+ *
+ * The subtle part is knowing when the measurement means anything. A box that
+ * was stretched, flexed or given a height fills what the layout handed it, and
+ * measuring tells it how much that was. A box with none of those is sized *by*
+ * its own content - measuring it just reports back how many rows it drew last
+ * frame, and clamping to that would mean an expanding tree could never grow
+ * past the size it had when it was first drawn.
+ *
+ * So: layout-sized components fill and scroll, content-sized ones draw
+ * everything, and which one you get is decided by the props you passed.
+ */
+export interface SizedProps {
+  flex?: number;
+  height?: Dimension;
+  maxHeight?: number;
+  basis?: Dimension;
+}
+
+export function sizedByLayout(props: SizedProps): boolean {
+  return (
+    props.flex !== undefined ||
+    props.height !== undefined ||
+    props.maxHeight !== undefined ||
+    props.basis !== undefined
+  );
+}
+
+/**
+ * The row count to render: what was asked for, else what fits, else all of it.
+ * `reserved` takes off rows the component spends on chrome, like a header.
+ */
+export function viewportRows(
+  props: SizedProps,
+  measured: Rect,
+  content: number,
+  options: { requested?: number; reserved?: number } = {},
+): number {
+  if (options.requested !== undefined) return Math.max(1, options.requested);
+  if (!sizedByLayout(props) || measured.height <= 0) return content;
+  return Math.max(1, measured.height - (options.reserved ?? 0));
+}