@lotics/ui 36.0.0 → 37.0.0

package/MIGRATION.md

@@ -4,6 +4,33 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 37.0.0 — `PageContent`'s side gutter is a token, and responsive
+
+`PageContent` padded `16` at every width. It now uses `pagePad` from
+`@lotics/ui/spacing` — **16 on a phone, 32 wider**. Nothing to pass; the only visible
+change is that a wide page breathes where it used to sit 16px off the chrome.
+
+```ts
+import { pagePad } from "@lotics/ui/spacing";
+pagePad(small); // SPACE.md | SPACE.xl
+```
+
+**Why a token rather than a prop.** A screen that cannot use this shell — one with a
+rail, a side panel, or a scroller it must hold a ref to — still has to land on the
+same left edge, and a list and the record it opens are one reading column seen twice:
+a gutter that differs between them slides the content sideways as the reader crosses.
+Left to each app this lands on hand-picked numbers; the case that prompted this had
+14 and 28, one of them not even a multiple of 4, against a scale whose own doc says
+that reads as broken.
+
+It is also COUPLED to `ROW_WASH_BLEED`: a register row bleeds its wash outward to
+`pagePad − ROW_WASH_BLEED`. Two numbers that must be read together should not live in
+two repositories.
+
+**If you hand-roll a page shell, import `pagePad` instead of choosing.** And check
+whether `PageContent` would do — it carries the centred `maxWidth` column and the
+title band most screens re-type by hand.
+
 ## 36.0.0 — seven components stopped announcing English; their strings moved to the pack
 
 **Nothing to change if you pass a shipped pack** (`en` / `vi`) — both carry every

package/docs/catalog.md

@@ -418,7 +418,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   scales and `getCssVariables()` — an OPT-IN serializer to `--lotics-*` CSS variables for
   hand-rolled plain DOM/CSS (nothing injects them automatically; `@lotics/ui` components
   don't need them).
-- **`spacing`** — the `SPACE` scale + `SpaceToken`.
+- **`spacing`** — the `SPACE` scale + `SpaceToken`, and **`pagePad(small)`** — the page's
+  side gutter (`SPACE.md` on a phone, `SPACE.xl` wider). `PageContent` applies it; a screen
+  that cannot use that shell — one with a rail, a side panel or its own scroller — imports it
+  rather than picking a number, because a list and the record it opens are one reading column
+  seen twice and must not shift sideways between them. It is also COUPLED to `ROW_WASH_BLEED`:
+  a register row bleeds its wash outward to `pagePad − ROW_WASH_BLEED`, so the two are read
+  together and neither belongs to the app.
 - **`control_surface`** — `CONTROL_HEIGHT` (40), `CONTROL_CONTENT_HEIGHT` (28 — the tallest
   FIXED-height node a 40px band seats, 6 per side of air; what `InlineButton` and a `md`
   `IconButton` already used, now named so an avatar or any other child lands on it too. Text
@@ -513,7 +519,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `CONTAINER_SIZES`).
 - **`page_header`** — `PageHeader`: the page's title band; `actions` puts page-level CTAs on the title row (right-aligned), while `left`/`right` form a separate nav row above.
 - **`page_content`** — `PageContent` + `PAGE_SIZES`: the page's padded, width-capped content
-  region.
+  region — a centred column with optional `title`/`titleRight`/`description`, `header`/`footer`
+  slots and `fullscreen`. **Reach for it before hand-rolling a screen shell**: a scroller, a
+  centred `maxWidth` column and a title band re-typed per screen is how two pages of one app end
+  up on different gutters. Its side padding is `pagePad` (`@lotics/ui/spacing`), so a screen that
+  genuinely cannot use it — one with a rail, a side panel, or a scroller it must hold a ref to —
+  still lands on the same edge by importing that token. It OWNS its `ScrollView` and exposes no
+  scroll props, which is the real limit on adoption.
 - **`accordion`** — `Accordion` + `AccordionHeader`/`AccordionTitle`/`AccordionMeta`:
   expandable section rows.
 - **`tabs`** — `Tabs`: switch between content sections; WAI-ARIA tablist + roving tabindex;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "36.0.0",
+  "version": "37.0.0",
   "type": "module",
   "exports": {
     "./vite": {

package/src/page_content.tsx

@@ -4,6 +4,7 @@ import { colors } from "@lotics/ui/colors";
 import { Spacer } from "@lotics/ui/spacer";
 import { ReactNode } from "react";
 import { useContainerSize } from "@lotics/ui/size_boundary";
+import { pagePad } from "@lotics/ui/spacing";
 
 interface PageContentProps {
   children: ReactNode;
@@ -26,6 +27,10 @@ export function PageContent(props: PageContentProps) {
   const screenSize = useContainerSize();
 
   const maxWidth = !screenSize.small && size ? PAGE_SIZES[size] : undefined;
+  // The gutter is a TOKEN, not this component's own number — a screen that cannot
+  // use this shell (one with a rail, a side panel, its own scroller) still has to
+  // land on the same edge, and it can only do that if the number has one home.
+  const pad = pagePad(screenSize.small);
 
   if (fullscreen) {
     return (
@@ -33,7 +38,7 @@ export function PageContent(props: PageContentProps) {
         {!!header && (
           <View
             style={{
-              paddingHorizontal: 16,
+              paddingHorizontal: pad,
               paddingTop: 16,
               width: "100%",
             }}
@@ -51,7 +56,7 @@ export function PageContent(props: PageContentProps) {
       {!!header && (
         <View
           style={{
-            paddingHorizontal: 16,
+            paddingHorizontal: pad,
             paddingTop: 16,
             maxWidth,
             width: "100%",
@@ -73,7 +78,7 @@ export function PageContent(props: PageContentProps) {
             maxWidth,
             width: "100%",
             marginHorizontal: "auto",
-            paddingHorizontal: 16,
+            paddingHorizontal: pad,
           }}
         >
           <View
@@ -101,19 +106,25 @@ export function PageContent(props: PageContentProps) {
         </View>
       </ScrollView>
       {!!footer && (
-        <View
-          style={{
-            borderTopWidth: 1,
-            borderTopColor: colors.border,
-            padding: 16,
-            paddingBottom: 24,
-          }}
-        >
+        // The RULE spans the page; the CONTENT sits on the body's column. Those
+        // are two different widths, which is why they are two elements.
+        <View style={{ borderTopWidth: 1, borderTopColor: colors.border }}>
+          {/* ONE box carries the cap AND the gutter, exactly as the body's does.
+              Split across two — the padding outside, the cap inside — they
+              compute different edges the moment a cap is in play and the viewport
+              is wider than it: the body's content starts `pad` inside a centred
+              1280 box, while the footer's starts wherever 1280 centres inside a
+              padded full-width box. That put a footer's totals 32px off the column
+              they total, and it is invisible at phone width, where nothing is
+              capped. */}
           <View
             style={{
               maxWidth,
               width: "100%",
               marginHorizontal: "auto",
+              paddingHorizontal: pad,
+              paddingTop: 16,
+              paddingBottom: 24,
             }}
           >
             {footer}

package/src/spacing.ts

@@ -21,3 +21,23 @@ export const SPACE = {
 } as const;
 
 export type SpaceToken = keyof typeof SPACE;
+
+/**
+ * The page's side gutter, by width — what a full-page surface pads by.
+ *
+ * ONE number, because a list and the record it opens are the same reading column
+ * seen twice: a gutter that differs between them slides the content sideways at
+ * the moment the reader changes screens. `PageContent` applies it; a screen that
+ * hand-rolls its own shell imports it rather than picking again.
+ *
+ * ON THE LADDER above, deliberately. Left to each app this lands on numbers like
+ * 14 and 28 — one of them not even a multiple of 4 — which is the "reads as
+ * broken" case this scale exists to prevent. `md` on a phone, where 28 a side
+ * spends 15% of a 375px screen on margin and 16 is the platform norm besides;
+ * `xl` wider, where 16 leaves a capped column nearly touching the chrome.
+ *
+ * COUPLED to `ROW_WASH_BLEED` (`control_surface`): a register row bleeds its wash
+ * OUTWARD past this, landing at `pagePad − ROW_WASH_BLEED`. Two numbers that must
+ * be read together is exactly why this one does not belong to the app.
+ */
+export const pagePad = (small: boolean): number => (small ? SPACE.md : SPACE.xl);