@usethrottle/builder-react 0.3.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CLAUDE.md CHANGED
@@ -146,6 +146,30 @@ below `BuilderProvider`, and it builds its own appearance from that design.
146
146
  external: at most 35 KB (`pnpm --filter @usethrottle/builder-react size`, the
147
147
  limit is in `size-limit.json`).
148
148
 
149
+ ## Interactions, countdown, entrance, custom CSS (0.4.0, agent v2)
150
+
151
+ - **Sections.** `renderSection` resolves `resolveInteraction`/`resolveEntrance` per device and draws each distinct result
152
+ once with `tb-v tb-only-*` classes (like a widget's markup variants). Modes are `src/interactions/{tabs,accordion,carousel,toggle}.tsx`;
153
+ columns are the panels (`panelTitle`, else "Tab n" / "Section n"; a column hidden on every device is not a panel).
154
+ No `interaction` on any device = the old markup, byte for byte (`parity-markup.test.tsx` holds the 19 parity fixtures to a
155
+ SHA-256 golden made by the 0.3.1 renderer; regenerate only for an intended markup change, `WRITE_PARITY_GOLDEN=1`).
156
+ - **Works without script.** Tabs: every panel in the HTML with its title; the tab list, carousel buttons and Pause show only
157
+ under `html[data-b-js]`. Accordion and toggle are native `<details>` (`name` groups the exclusive accordion). Entrance rules
158
+ start with `html[data-b-js]` and sit inside `prefers-reduced-motion: no-preference`: never hidden without script.
159
+ - **Runtime** (`interactions/runtime.ts`, plain DOM, no imports, 3 KB budget, `pnpm size` measures the separate
160
+ `dist/interactions-runtime.js`; the same code is inside the core bundle). `InteractionRuntime` mounts it from the renderer
161
+ (only when the document has an interaction or entrance) and from `basic.countdown`; holds are counted, listeners are
162
+ delegated on `document`. It emits the `tb-interactions` stylesheet (`INTERACTIONS_CSS`), hoisted by React, only when used.
163
+ - **`interactive={false}`** (editor edit mode; `BuilderProvider` and `BuilderRenderer` prop, `WidgetRenderProps.interactive`):
164
+ plain rows, no entrance attributes, countdown drawn once.
165
+ - **Entrance** is drawn by the wrapper (`NodeWrapper entrance`): `data-b-entrance` plus `--tb-ed` (the delay). Widgets read it
166
+ from their validated settings (a common setting), columns and sections from `resolveEntrance` (a column uses desktop).
167
+ - **Countdown** server text is UTC (`YYYY-MM-DD HH:mm UTC`) so server and client agree; the ticking boxes are filled by the
168
+ runtime only (no `Date.now()` in a live render, so no hydration mismatch and ISR stays valid).
169
+ - **Custom CSS.** `theme.ts` `customCssOf(settings)` runs `sanitizeThemeCss` again (never the stored string; over the cap is
170
+ skipped) and the provider emits it once in `@layer throttle,throttle-custom;@layer throttle-custom{...}` when non-empty. The
171
+ renderer root gets `data-b-root` only when the provider says there is CSS (`scopeCustomCss`), so a page without it is unchanged.
172
+
149
173
  ## SEO (`src/next/seo.ts`)
150
174
 
151
175
  `createBuilderPage().generateMetadata` is `metadataOf(page, ...)`: the page's own `seo` over the
@@ -232,3 +256,10 @@ type renderers take, so the two server entries' copies of `RenderBudget` stay in
232
256
  `node_modules` the way an app has them. Vitest never uses the `react-server` condition, so only this catches a server entry
233
257
  that evaluates something React's `react-server` build lacks (`PartBoundary extends Component` crashed 0.1.0). Build the
234
258
  package first. Do not point it at a link into the workspace: Next only skips its client-hook check for code under node_modules.
259
+
260
+ ## Code widgets and saved sections (v2)
261
+
262
+ - Code runs only on a live store page where the site's code switch is on and `isCodeRoute(pathname, ...)` is true. The deny words (`checkout`, `cart`, `account`, `sign-in`, ...) are checked on every path segment, whatever `routes.page` is. Without `pathname` no code runs.
263
+ - Leaving a code route by client navigation (into checkout, account, sign-in, cart) triggers a full page load (`useLeaveCodeRoutes` in `BuilderProvider`), because a loaded script cannot be unloaded.
264
+ - Saved-section ids and anchors are prefixed `<reference id>-`; a page holds at most 20,000 nodes with its saved sections expanded.
265
+ - The "code was written" flag is module state set by `CodeWidget` (not a DOM query: page code could remove its script tag). While it is set and the path is not a code route, `BuilderProvider` draws a placeholder and reloads; it checks on unmount too.