@timbal-ai/timbal-react 1.3.0 → 1.4.0

package/dist/{chart-artifact-Q5QgMtbj.d.ts → chart-artifact-CMnDys2t.d.ts}

@@ -426,6 +426,15 @@ interface AppShellProps {
     onNavOpenChange?: (open: boolean) => void;
     className?: string;
     mainClassName?: string;
+    /**
+     * Make the content region a bounded, non-scrolling flex column instead of the
+     * default padded scroll area. Use for full-bleed pages that own their own
+     * scroll — a full-page chat (`TimbalChat` / `Thread`), a canvas, a map, an
+     * editor — so a `h-full` / `flex-1 min-h-0` child fills exactly and a pinned
+     * footer (e.g. the chat composer) stays put instead of riding down on scroll.
+     * Do **not** combine with `h-[calc(100dvh-…)]` guesses on the child.
+     */
+    contentFill?: boolean;
 }
 /**
  * App-first layout: sidebar + topbar + main, with optional **floating** copilot.
@@ -557,7 +566,8 @@ type AppDensityClassKey = keyof typeof APP_DENSITY_CLASSES;
 declare function appDensityClass(key: AppDensityClassKey, density?: AppDensity): string;
 
 interface PageHeaderProps {
-    title: ReactNode;
+    /** Page title. Omit for a headerless page (no `<h1>` rendered). */
+    title?: ReactNode;
     description?: ReactNode;
     actions?: ReactNode;
     className?: string;
@@ -573,6 +583,13 @@ interface PageProps extends PageHeaderProps {
      * `compact` tightens page insets, section gaps, and card padding.
      */
     density?: AppDensity;
+    /**
+     * Make the page a bounded, full-height flex column instead of a centered,
+     * content-sized column. Pair with `AppShell contentFill` for full-bleed pages
+     * (a full-page chat, a canvas, an editor) whose body should fill the viewport
+     * and own its own scroll. Give the fill child `min-h-0 flex-1`.
+     */
+    fill?: boolean;
     className?: string;
 }
 declare const Page: FC<PageProps>;

package/dist/{chunk-YCXN67SD.esm.js → chunk-VOWNCS3F.esm.js}

@@ -239,6 +239,40 @@ You are **not** required to copy any example layout, page title, section order,
 
 When in doubt: compose from the **component menu** + **guidelines**, then adapt creatively to the request.
 
+### Layout archetypes \u2014 pick the shape that fits (don't default to one)
+
+The most common failure is shipping the **same** layout every time: sidebar + topbar + \`Page\` + one \`MetricRow\` + one full-width \`DataTable\`. That is *one* archetype, not *the* layout. Choose deliberately \u2014 different domains want different shapes, and varying the shell/page composition is encouraged.
+
+| Archetype | When | Compose |
+|-----------|------|---------|
+| **Sidebar dashboard** | Multi-section product (CRM, billing, ops) with nav | \`StudioSidebar\` in \`AppShell.sidebar\` + \`Page\` \u2192 \`Section\` |
+| **Focused / no-chrome** | A single tool or one-screen utility | \`AppShell\` (no sidebar) + \`Page\` (optionally just \`AppShellTopbar\`); or a centered narrow column |
+| **Bento overview** | Home / at-a-glance dashboards | \`Page\` + an **asymmetric grid** of \`SurfaceCard\` / \`ChartPanel\` / \`StatTile\` spanning different widths (not a uniform row + table) |
+| **Split master\u2013detail** | Inbox, triage queue, record browser, log explorer | \`AppShell contentFill\` + \`Page fill\` + a two-column flex row, each pane \`min-h-0 overflow-y-auto\` |
+| **Full-page chat / canvas** | Chat-first app, editor, map, single full-bleed surface | \`AppShell contentFill\` + headerless \`Page fill\` + a \`min-h-0 flex-1\` child (e.g. \`TimbalChat\`) |
+| **Copilot overlay** | A data app that also wants an assistant | any of the above + \`AppShell chat={<AppChatPanel />}\` (floating, never a second column) |
+| **Section-switcher** | One page, several views | \`SubNav\` / \`PillSegmentedTabs\` (\`trackVariant="flush"\`) switching panels with state/router |
+
+Mix them: vary the grid columns, density, header placement (\`Page\` actions vs. a global \`AppShellTopbar\`), and whether there's a sidebar at all. Two dashboards for two domains should not look identical.
+
+### Full-height pages (chat, canvas, split views)
+
+The content region is a **padded scroll area** by default \u2014 great for stacked \`Page\` \u2192 \`Section\` content, wrong for a surface that must fill the viewport. For full-bleed pages:
+
+- Pass **\`contentFill\`** to \`AppShell\` \u2192 the content region becomes a bounded, non-scrolling flex column (clipped, no bottom padding).
+- Pass **\`fill\`** to \`Page\` \u2192 the page becomes a \`min-h-0 flex-1\` flex column.
+- Give the filling child **\`min-h-0 flex-1\`** (or \`h-full\`) so its own scroll/footer resolves \u2014 e.g. \`<TimbalChat className="min-h-0 flex-1" />\`, or a two-pane row where each pane is \`min-h-0 overflow-y-auto\`.
+
+\`\`\`tsx
+<AppShell contentFill topbar={<AppShellTopbar actions={<ModeToggle />} />}>
+  <Page fill>                                  {/* headerless: omit title */}
+    <TimbalChat workforceId="\u2026" className="min-h-0 flex-1" />
+  </Page>
+</AppShell>
+\`\`\`
+
+**Don't** size full-height content with \`h-[calc(100dvh-\u2026)]\` (guesses chrome height \u2192 spurious scrollbar) or \`min-h-[\u2026]\` (free-growing floor \u2192 a pinned footer like the chat composer rides down on scroll). Let \`contentFill\` + \`fill\` provide the bounded height. \`Page\` with no \`title\` renders **no header** \u2014 you don't need to abandon \`Page\` to drop a heading.
+
 ### Module layout (source folders)
 
 Presentational groups \u2014 import from the package root, not from these paths:
@@ -297,12 +331,12 @@ The cause of slop is dropping **below** the curated block layer into raw primiti
 
 | Component | Use for |
 |-----------|---------|
-| \`AppShell\` | Shell: optional \`sidebar\`, \`topbar\`, main \`children\`, optional floating \`chat\`. Props: \`chatTriggerLabel\`, \`chatCollapsible\`, \`chatWidth\`, \`chatHeight\`, controlled \`chatOpen\`. |
+| \`AppShell\` | Shell: optional \`sidebar\`, \`topbar\`, main \`children\`, optional floating \`chat\`. Props: \`chatTriggerLabel\`, \`chatCollapsible\`, \`chatWidth\`, \`chatHeight\`, controlled \`chatOpen\`, **\`contentFill\`** (bounded non-scrolling content region for full-bleed pages \u2014 chat/canvas/split view). |
 | \`AppShellTopbar\` | Full-width top bar: \`start\`, \`actions\` slots. |
 | \`AppCopilotProvider\` | React context for copilot-aware tools (page, filters, selection, etc.). |
 | \`AppChatPanel\` | Floating thread: \`workforceId\`, \`welcome\`, \`debug\`. |
 | \`useAppShellChat\` | Custom open/close trigger when \`hideChatTrigger\` on shell. |
-| \`Page\` | Page title, description, \`breadcrumbs\`, \`actions\`, \`density\` (\`"default"\` | \`"compact"\`), children. |
+| \`Page\` | Page title, description, \`breadcrumbs\`, \`actions\`, \`density\` (\`"default"\` | \`"compact"\`), children. **\`title\` is optional** \u2014 omit it for a headerless page (no \`<h1>\`). **\`fill\`** makes it a \`min-h-0 flex-1\` column for full-height content (pair with \`AppShell contentFill\`). |
 | \`Section\` | Titled block inside a page. Optional \`density\` overrides inherited page density. |
 | \`SubNav\` | **Section switcher** (Overview / Reports pill bar): \`items\`, \`activeId\`, \`onChange\`. Never use Radix/shadcn \`Tabs\` \u2014 it is not in this package. Switch panels with state or the router. |
 | **Menus** | **Select** = short list, no search. **Combobox** = searchable (same trigger as Select). **Command** only inside \`PopoverContent variant="list"\` or Combobox \u2014 never padded default Popover. See \`examples/app-kit/src/recipes/primitives-catalog.ts\`. |
@@ -395,8 +429,11 @@ Ready-made **section patterns** assembled from the components above. Each is a c
 - **Empty states** \u2014 no-data / no-results / first-run. Compose \`EmptyState\` + \`Card\` + \`Button\`.
 - **Sign-in card** \u2014 centered auth entry. Compose \`Card\` + \`Input\` + \`Label\` + \`Button\`.
 
-**Shells & theming**
+**Shells & layouts**
 - **Minimal shell** \u2014 \`AppShell\` + \`Page\` (no sidebar/chat).
+- **Bento dashboard** \u2014 \`Page\` + an asymmetric grid of \`SurfaceCard\` / \`ChartPanel\` / \`StatTile\` (varied spans) for overview/home screens.
+- **Split view** \u2014 master\u2013detail: \`AppShell contentFill\` + \`Page fill\` + a two-pane flex row (list + detail), each pane \`min-h-0 overflow-y-auto\`.
+- **Full-page chat** \u2014 \`AppShell contentFill\` + headerless \`Page fill\` + \`TimbalChat className="min-h-0 flex-1"\` (composer pinned; no \`h-[calc(...)]\`).
 - **Copilot overlay** \u2014 \`AppShell\` + floating \`AppChatPanel\`.
 - **Theme presets** \u2014 apply a brand preset programmatically (\`applyThemePreset\` / \`applyTimbalTheme\`); never hand-author OKLCH and don't expose a theme picker to end users.
 
@@ -1600,6 +1637,7 @@ var AppShellBody = ({
   sidebar,
   topbarContent,
   mainClassName,
+  contentFill = false,
   insetPaddingPx,
   insetExpanded,
   children
@@ -1622,7 +1660,10 @@ var AppShellBody = ({
         "div",
         {
           className: cn(
-            "aui-app-shell-scroll flex min-h-0 flex-1 flex-col overflow-y-auto",
+            "aui-app-shell-scroll flex min-h-0 flex-1 flex-col",
+            // Padded scroll region by default; a full-bleed page (chat / canvas) owns
+            // its own scroll, so clip here and let the bounded `main` fill exactly.
+            contentFill ? "overflow-hidden" : "overflow-y-auto",
             !topbarContent && appShellInsetTopClass
           ),
           children: [
@@ -1631,8 +1672,11 @@ var AppShellBody = ({
               "main",
               {
                 className: cn(
-                  "aui-app-shell-main min-w-0 flex-1",
-                  appShellInsetBottomClass,
+                  // Bounded flex column by default so `h-full` / `flex-1 min-h-0` children
+                  // (full-page chat, canvas) resolve a height without `mainClassName` surgery.
+                  "aui-app-shell-main flex min-h-0 min-w-0 flex-1 flex-col",
+                  // Bottom breathing room for scrolling content; full-bleed pages skip it.
+                  !contentFill && appShellInsetBottomClass,
                   mainClassName
                 ),
                 children
@@ -1662,7 +1706,8 @@ var AppShell = ({
   defaultNavOpen = false,
   onNavOpenChange,
   className,
-  mainClassName
+  mainClassName,
+  contentFill = false
 }) => {
   const topbarContent = topbar ?? header;
   const hasChat = Boolean(chat);
@@ -1709,6 +1754,7 @@ var AppShell = ({
       sidebar,
       topbarContent,
       mainClassName,
+      contentFill,
       insetPaddingPx,
       insetExpanded,
       children
@@ -1858,11 +1904,14 @@ var PageHeader = ({
   className
 }) => {
   const pageHeaderClass = useAppDensityClass("pageHeader");
+  if (title == null && description == null && actions == null) {
+    return null;
+  }
   return /* @__PURE__ */ jsxs7("header", { className: cn("aui-app-page-header", pageHeaderClass, className), children: [
-    /* @__PURE__ */ jsxs7("div", { className: "min-w-0", children: [
-      /* @__PURE__ */ jsx10("h1", { className: "text-2xl font-semibold tracking-tight text-foreground", children: title }),
+    title != null || description != null ? /* @__PURE__ */ jsxs7("div", { className: "min-w-0", children: [
+      title != null ? /* @__PURE__ */ jsx10("h1", { className: "text-2xl font-semibold tracking-tight text-foreground", children: title }) : null,
       description ? /* @__PURE__ */ jsx10("p", { className: "mt-1 text-sm text-muted-foreground", children: description }) : null
-    ] }),
+    ] }) : null,
     actions ? /* @__PURE__ */ jsx10("div", { className: "aui-app-page-header-actions flex shrink-0 flex-wrap items-center gap-2", children: actions }) : null
   ] });
 };
@@ -1872,6 +1921,7 @@ import { jsx as jsx11, jsxs as jsxs8 } from "react/jsx-runtime";
 var PageFrame = ({
   children,
   breadcrumbs,
+  fill = false,
   className,
   ...headerProps
 }) => {
@@ -1880,7 +1930,11 @@ var PageFrame = ({
   return /* @__PURE__ */ jsxs8(
     "div",
     {
-      className: cn("aui-app-page", pageColumnClass, className),
+      className: cn(
+        "aui-app-page",
+        fill ? "flex min-h-0 min-w-0 flex-1 flex-col" : pageColumnClass,
+        className
+      ),
       "data-density": density,
       children: [
         breadcrumbs,
@@ -1894,10 +1948,20 @@ var Page = ({
   density = "default",
   children,
   breadcrumbs,
+  fill = false,
   className,
   ...headerProps
 }) => {
-  return /* @__PURE__ */ jsx11(AppDensityProvider, { density, children: /* @__PURE__ */ jsx11(PageFrame, { breadcrumbs, className, ...headerProps, children }) });
+  return /* @__PURE__ */ jsx11(AppDensityProvider, { density, children: /* @__PURE__ */ jsx11(
+    PageFrame,
+    {
+      breadcrumbs,
+      fill,
+      className,
+      ...headerProps,
+      children
+    }
+  ) });
 };
 
 // src/app/layout/Section.tsx
@@ -2810,6 +2874,7 @@ var Breadcrumbs = ({ items, className }) => {
 };
 
 // src/app/forms/Field.tsx
+import { useId as useId4 } from "react";
 import { jsx as jsx36, jsxs as jsxs28 } from "react/jsx-runtime";
 var Field = ({
   label,
@@ -2835,7 +2900,8 @@ var FieldInput = ({
   id,
   ...inputProps
 }) => {
-  const inputId = id ?? inputProps.name;
+  const autoId = useId4();
+  const inputId = id ?? inputProps.name ?? autoId;
   return /* @__PURE__ */ jsx36(
     Field,
     {
@@ -2858,6 +2924,7 @@ var FieldInput = ({
 };
 
 // src/app/forms/FieldTextarea.tsx
+import { useId as useId5 } from "react";
 import { jsx as jsx37 } from "react/jsx-runtime";
 var textareaClass = cn(
   appInputClass,
@@ -2872,7 +2939,8 @@ var FieldTextarea = ({
   id,
   ...props
 }) => {
-  const textareaId = id ?? props.name;
+  const autoId = useId5();
+  const textareaId = id ?? props.name ?? autoId;
   return /* @__PURE__ */ jsx37(
     Field,
     {
@@ -2895,6 +2963,7 @@ var FieldTextarea = ({
 };
 
 // src/app/forms/FieldSelect.tsx
+import { useId as useId6 } from "react";
 import { ChevronDownIcon } from "lucide-react";
 import { jsx as jsx38, jsxs as jsxs29 } from "react/jsx-runtime";
 var selectWrapClass = "relative";
@@ -2912,7 +2981,8 @@ var FieldSelect = ({
   id,
   ...props
 }) => {
-  const selectId = id ?? props.name;
+  const autoId = useId6();
+  const selectId = id ?? props.name ?? autoId;
   return /* @__PURE__ */ jsx38(
     Field,
     {
@@ -2945,6 +3015,7 @@ var FieldSelect = ({
 };
 
 // src/app/forms/FieldSwitch.tsx
+import { useId as useId7 } from "react";
 import { jsx as jsx39, jsxs as jsxs30 } from "react/jsx-runtime";
 var trackClass = cn(
   "relative inline-flex h-5 w-9 shrink-0 items-center rounded-full transition-[background,box-shadow,border-color] duration-200",
@@ -2965,7 +3036,8 @@ var FieldSwitch = ({
   id,
   ...props
 }) => {
-  const inputId = id ?? props.name ?? "switch";
+  const autoId = useId7();
+  const inputId = id ?? props.name ?? autoId;
   return /* @__PURE__ */ jsxs30(
     "label",
     {
@@ -3430,7 +3502,7 @@ function DataTable({
 }
 
 // src/app/data/ChartPanel.tsx
-import { useId as useId4 } from "react";
+import { useId as useId8 } from "react";
 import { jsx as jsx45, jsxs as jsxs35 } from "react/jsx-runtime";
 var ChartPanel = ({
   title,
@@ -3446,7 +3518,7 @@ var ChartPanel = ({
   const height = heightProp ?? APP_DENSITY_CHART_HEIGHT[density];
   const metricChartPlotRegionClass = useAppDensityClass("metricChartPlotRegion");
   const chartPanelBodyClass = useAppDensityClass("chartPanelBody");
-  const titleId = useId4();
+  const titleId = useId8();
   const resolvedTitle = title ?? artifact?.title;
   const hasHeader = Boolean(resolvedTitle || description || actions);
   const body = loading ? /* @__PURE__ */ jsx45(Skeleton, { className: "w-full rounded-lg", style: { height }, "aria-hidden": true }) : children ?? (artifact ? /* @__PURE__ */ jsx45(ChartArtifactView, { artifact, embedded: true, height }) : null);
@@ -3489,7 +3561,7 @@ var ChartPanel = ({
 };
 
 // src/app/data/MetricRow.tsx
-import { useId as useId5, useState as useState5 } from "react";
+import { useId as useId9, useState as useState5 } from "react";
 import { jsx as jsx46, jsxs as jsxs36 } from "react/jsx-runtime";
 var MetricRow = ({
   title,
@@ -3504,7 +3576,7 @@ var MetricRow = ({
   className
 }) => {
   const metricTileClass = useAppDensityClass("metricTile");
-  const titleId = useId5();
+  const titleId = useId9();
   const selectable = onMetricChange != null || activeMetricId != null;
   const [internalId, setInternalId] = useState5(
     defaultActiveMetricId ?? metrics[0]?.id
@@ -3573,7 +3645,7 @@ var MetricRow = ({
 };
 
 // src/app/data/MetricChartCard.tsx
-import { useId as useId6, useState as useState6 } from "react";
+import { useId as useId10, useState as useState6 } from "react";
 import { jsx as jsx47, jsxs as jsxs37 } from "react/jsx-runtime";
 var MetricChartCard = ({
   title,
@@ -3597,7 +3669,7 @@ var MetricChartCard = ({
   const height = heightProp ?? APP_DENSITY_CHART_HEIGHT[density];
   const metricChartRegionClass = useAppDensityClass("metricChartRegion");
   const metricTileClass = useAppDensityClass("metricTile");
-  const titleId = useId6();
+  const titleId = useId10();
   const [internalId, setInternalId] = useState6(
     defaultActiveMetricId ?? metrics[0]?.id
   );
@@ -3794,7 +3866,7 @@ function useLiveQuery(fetcher, options = {}) {
 }
 
 // src/charts/sparkline.tsx
-import { useId as useId7 } from "react";
+import { useId as useId11 } from "react";
 import { Fragment as Fragment6, jsx as jsx48, jsxs as jsxs38 } from "react/jsx-runtime";
 var Sparkline = ({
   data,
@@ -3807,7 +3879,7 @@ var Sparkline = ({
   className,
   ariaLabel = "Trend"
 }) => {
-  const uid = useId7();
+  const uid = useId11();
   const values = data.map((d) => typeof d === "number" ? d : toNum(d[dataKey]));
   if (values.length === 0) {
     return /* @__PURE__ */ jsx48("span", { className: cn("inline-block", className), style: { width, height } });