Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(storybook): add capped Bottom Sheet example (#5085)

Xinzi Zhou464a44560a2d
diff --git a/apps/storybook/LOCAL_STARTUP_INVESTIGATION.md b/apps/storybook/LOCAL_STARTUP_INVESTIGATION.md
new file mode 100644
index 0000000000..1e0c80c146
--- /dev/null
+++ b/apps/storybook/LOCAL_STARTUP_INVESTIGATION.md
@@ -0,0 +1,188 @@
+# Local Storybook startup reliability investigation
+
+Date: 2026-08-15
+
+## Summary
+
+Local Storybook is usually not failing to compile. The recurring failure mode is
+that `storybook dev` announces that Storybook is ready after the manager and
+preview shell are available, while Vite is still optimizing dependencies and
+the requested story is still being transformed. Opening the URL at that point
+can show a manager with an incomplete or indefinitely loading preview.
+
+Cold worktree caches make this frequent in the Astryx workspace. Storybook's
+cache is stored inside each worktree, the workspace aliases large packages to
+source, and the default development command always asks for port 6006. Together,
+those choices make a fresh or recently updated worktree slow to become usable
+and make it easy to open a stale server from another worktree.
+
+The Bottom Sheet story that prompted this investigation is not a compile
+failure. TypeScript, ESLint, formatting, and a full production Storybook build
+all passed.
+
+## Evidence from this incident
+
+### Storybook reported ready before optimization finished
+
+The development server printed:
+
+```text
+Storybook ready!
+- Local: http://localhost:6007/
+2.71 s for manager and 295 ms for preview
+Vite [optimizer] bundling dependencies...
+```
+
+The URL was shared after the ready banner, but before the final optimizer line
+had settled. The manager, `index.json`, and the story iframe shell all returned
+HTTP 200; that only proved that the server and HTML shell were available. It did
+not prove that the story module had executed in the browser.
+
+This is expected dev-server behavior: stories and much of their dependency
+graph are transformed on demand. The ready banner is therefore not a reliable
+"selected story is rendered" signal.
+
+### The worktree required dependency re-optimization
+
+Startup also printed:
+
+```text
+Vite Re-optimizing dependencies because lockfile has changed
+```
+
+The resulting worktree-local optimizer cache contained 136 generated files.
+There are currently 17 separate Storybook cache roots across Astryx worktrees.
+A new worktree, a dependency install, a lockfile update, a Storybook version
+change, or a relevant Vite configuration change can create another cold cache.
+
+Vite's metadata explicitly keys this cache from both the lockfile and resolved
+configuration hashes. Frequent rebases onto `main` therefore make cold starts a
+normal part of local work rather than an exceptional event.
+
+### Astryx has a large transform graph
+
+The full build succeeded, but it transformed 4,077 modules and took 21.10
+seconds for the Vite build alone. Plugin timing reported these largest shares:
+
+- Storybook project annotations: 53%
+- Storybook mock loader: 14%
+- StyleX: 13%
+- React docgen: 12%
+- CSF processing: 6%
+
+The Storybook configuration aliases Core, Lab, Charts, Vega, and themes to their
+source trees. That is useful for component development, but a cold preview must
+process a substantial source and StyleX graph before some stories can render.
+
+### The default port can point at the wrong worktree
+
+`apps/storybook/package.json` hardcodes port 6006. During this incident, port
+6006 was already owned by a two-day-old Storybook process from the
+`bottom-sheet-orchestrator` worktree. The requested preview had to use 6007.
+
+Without an exact-port check and an explicit URL, a developer can either fail to
+start Storybook or open a valid-looking but stale Storybook from another
+worktree.
+
+### Dependency setup can add more churn
+
+The first formatting, lint, and typecheck commands in this worktree reconciled
+the pnpm workspace and ran postinstall hooks. Concurrent invocations also
+contended on the shared bare repository's Git config during `husky install`.
+Those commands eventually passed and did not cause the story failure, but they
+are another reason not to start or assess Storybook while first-use dependency
+setup is still running.
+
+## Existing mitigation and unrelated warnings
+
+The repository already sets `optimizeDeps.holdUntilCrawlEnd` to `false`. This is
+a valid Vite 8 option and was added specifically because StyleX transforms had
+previously kept the dependency crawl open. It mitigates the worst spinner case,
+but it does not make the ready banner wait for a selected story to render.
+
+The following warnings appeared but did not fail the full build:
+
+- no `stories/**/*.mdx` files were found;
+- `optimizeDeps.esbuildOptions` is deprecated in Vite 8 in favor of Rolldown
+ options;
+- Lexical has pure-annotation placement warnings;
+- some production chunks exceed 500 kB;
+- the neutral theme uses runtime style injection in development.
+
+They should not be used as evidence that a local preview failed. The deprecated
+optimizer configuration deserves cleanup, but it did not block this build.
+
+## Recommendations
+
+### 1. Verify the story, not the server banner
+
+For local review automation, do not share the URL as soon as Storybook prints
+`ready`. Load the exact story and wait for a browser-level assertion, such as
+the expected trigger text appearing without a Storybook error screen. An HTTP
+200 from `/`, `index.json`, or `iframe.html` is insufficient because those can
+all succeed before the story module renders.
+
+Where browser automation is unavailable, use a full static build before
+sharing a review URL:
+
+```sh
+pnpm -F @astryxdesign/storybook build
+```
+
+Serve `apps/storybook/dist` only after that command completes successfully.
+This is slower and has no hot reload, but it proves every story compiled.
+
+### 2. Make port ownership explicit
+
+Use an explicitly selected free port and Storybook's `--exact-port` option for
+development. Print the worktree path and final URL together. This turns a stale
+6006 process into an obvious startup failure instead of a plausible but wrong
+preview.
+
+### 3. Add a deterministic local-review command
+
+Add a repository script that performs one of these flows:
+
+- development: select an unused port, start with `--exact-port`, navigate to a
+ requested story ID, and wait for a browser-level ready assertion;
+- static review: build all of Storybook, serve `dist` on an unused port, and
+ verify that the requested story ID exists in `index.json`.
+
+The static flow is the better default for review handoff. The development flow
+is better when the user needs hot reload.
+
+### 4. Stabilize dependency setup before startup
+
+Run one workspace install/reconciliation to completion before launching
+parallel lint, typecheck, or Storybook processes in a fresh worktree. Avoid
+multiple simultaneous first-use pnpm commands because their lifecycle hooks
+share the bare repository's Git configuration.
+
+### 5. Profile cold development startup before changing optimization
+
+The current crawl workaround is still supported. Do not remove it based on the
+Vite 8 deprecation warning, which applies to `esbuildOptions`, not
+`holdUntilCrawlEnd`.
+
+As a separate performance task, measure whether an explicit
+`optimizeDeps.include` list plus `noDiscovery` improves cold startup. That can
+avoid a full crawl, but it is only safe if every CommonJS dependency needed by
+Storybook is listed. Also evaluate narrower package subpath imports or aliases
+to reduce the amount of Core, Lab, Charts, and Rich Text source transformed for
+an individual story.
+
+### 6. Migrate the deprecated optimizer target configuration
+
+Move or remove the Vite 7-era `optimizeDeps.esbuildOptions.target` setting after
+verifying the equivalent Vite 8 Rolldown configuration. This is maintenance,
+not the immediate reliability fix, but it will keep the local startup path on
+supported configuration and make future warnings more actionable.
+
+## Conclusion
+
+The recurring impression that Storybook is "not fully built" is accurate, but
+the primary issue is the handoff timing and local workflow rather than broken
+stories. Astryx's dev server is intentionally lazy, its readiness signal is too
+early for review handoff, and worktree-local caches make cold optimization
+common. A browser-level story readiness check or a completed static build is the
+reliable gate.
diff --git a/apps/storybook/README.md b/apps/storybook/README.md
index 5f43003528..e0ee085252 100644
--- a/apps/storybook/README.md
+++ b/apps/storybook/README.md
@@ -4,9 +4,10 @@ Storybook application for component development and visual documentation.
<!-- SYNC: When files in this directory change, update this document. -->
-| File | Role | Purpose |
-| -------------------- | ------ | ------------------------------------------------------------- |
-| `.storybook/main.ts` | Config | Storybook Vite integration, preview build target, and aliases |
-| `package.json` | Config | Package dependencies and scripts |
-| `tsconfig.json` | Config | TypeScript compiler configuration |
-| `vite.config.ts` | Config | Vite bundler configuration with path aliases |
+| File | Role | Purpose |
+| -------------------------------- | ------------- | ------------------------------------------------------------- |
+| `.storybook/main.ts` | Config | Storybook Vite integration, preview build target, and aliases |
+| `LOCAL_STARTUP_INVESTIGATION.md` | Investigation | Why local Storybook previews can appear before they are ready |
+| `package.json` | Config | Package dependencies and scripts |
+| `tsconfig.json` | Config | TypeScript compiler configuration |
+| `vite.config.ts` | Config | Vite bundler configuration with path aliases |
diff --git a/apps/storybook/stories/BottomSheet.stories.tsx b/apps/storybook/stories/BottomSheet.stories.tsx
index 0a9bb3d1c2..b90b890f7e 100644
--- a/apps/storybook/stories/BottomSheet.stories.tsx
+++ b/apps/storybook/stories/BottomSheet.stories.tsx
@@ -330,6 +330,43 @@ export const HugHeightWithLongContent: Story = {
},
};
+export const CappedHeightWithLongContent: Story = {
+ name: 'Capped height — Long content',
+ render: () => {
+ const [isOpen, setIsOpen] = useState(false);
+ return (
+ <>
+ <Button label="View saved places" onClick={() => setIsOpen(true)} />
+ <BottomSheet
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ label="Saved places"
+ height="capped">
+ <Section padding={4}>
+ <VStack gap={4}>
+ <Heading level={3}>Saved places</Heading>
+ <Text type="supporting" color="secondary">
+ The sheet opens at a capped height while the long list scrolls
+ within it.
+ </Text>
+ <Divider />
+ {Array.from({length: 12}, (_, i) => (
+ <VStack key={i} gap={1}>
+ <Text type="label">Saved place {i + 1}</Text>
+ <Text type="supporting" color="secondary">
+ Notes and details about this saved place.
+ </Text>
+ </VStack>
+ ))}
+ <Button label="Done" onClick={() => setIsOpen(false)} />
+ </VStack>
+ </Section>
+ </BottomSheet>
+ </>
+ );
+ },
+};
+
export const MobileKeyboard: Story = {
name: 'Mobile keyboard',
render: () => {