@lotics/ui 11.8.4 → 11.8.9

package/docs/catalog.md

@@ -360,7 +360,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   useSeparator` inserts and what menus/popovers put between option groups.
 - **`container`** — `Container`: centers content at a max width (`ContainerSize` sm|md|lg,
   `CONTAINER_SIZES`).
-- **`page_header`** — `PageHeader`: the page's title band.
+- **`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.
 - **`accordion`** — `Accordion` + `AccordionHeader`/`AccordionTitle`/`AccordionMeta`:
@@ -392,9 +392,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   name), `color` = emphasis/risk.
 - **`icon_button`** — `IconButton`: the icon-only circular action (see
   [Actions](#actions)).
-- **`back_button`** — `BackButton`: the chevron-left `IconButton` (lg, secondary) heading a
-  screen/panel: `onPress` + `accessibilityLabel` (defaults to the locale's `nav.back` —
-  "Back" / "Quay lại"); the one go-back glyph — don't hand-roll it.
+- **`back_button`** — `BackButton`: the one go-back control — don't hand-roll it (an
+  `arrow-left` `MenuButton` reads as another nav ITEM, not an exit). `onPress` +
+  `accessibilityLabel` (defaults to `label`, else the locale's `nav.back` — "Back" /
+  "Quay lại"). Bare, it's the chevron-left `IconButton` (lg, secondary) heading a
+  screen/panel; pass **`label`** to name where back GOES ("Danh sách") and it becomes ONE
+  pressable over glyph + words — never an icon button beside unclickable prose.
 - **`link`** — `Link`: the EXTERNAL hyperlink — fixed underline+blue + `role="link"`;
   `onPress` only (the consumer wires the opener).
 - **`text_link`** — `TextLink`: underlined text that's optionally an `onPress` action or an

package/docs/templates.md

@@ -244,6 +244,26 @@ Top → bottom:
 - A LEFT OUTLINE RAIL (`MenuButton` + `useSectionNav`) jumps between the sections and
   scroll-spies the active one; on narrow containers it becomes the pinned current-section
   bar opening a section-picker `Modal`.
+- **The page layout is the DOCS layout — the reading column is CENTRED IN THE VIEWPORT, and
+  the rail sits in its left gutter.** The `ScrollView` is FULL-WIDTH — **never cap it at
+  `CONTENT_MAX`, or the scroll container becomes the column and the gutters go wheel-dead**
+  (measured: a 720px scroller in a 1440px window leaves half the page ignoring the wheel).
+  Inside it sits one centred row (`width: "100%"`,
+  `maxWidth: GUTTER * 2 + CONTENT_MAX`, `alignSelf: "center"`, `flexDirection: "row"`) of
+  three parts: a gutter RESERVED for the rail (`width: GUTTER` — the rail's own `RAIL_W`
+  PLUS `RAIL_GAP`, the docs' 3rem of breathing room, so the rail never butts against the
+  column), the reading column (`flex: 1, minWidth: 0`), and an EMPTY right gutter of the
+  same `GUTTER` that BALANCES the rail — without it the column sits half a rail right of centre. (The public docs pages get
+  this balance for free: their right-hand TOC is the counterweight. A record surface has no
+  TOC, so the gutter is simply reserved.) The rail is NOT window chrome: no full-height
+  border, not glued to the window edge — it FLOATS over its reserved gutter
+  (`position: "absolute"`, `left` mirroring the row's centring maths), so it stays put while
+  the record scrolls **without** web-only `position: sticky` (which RN does not type —
+  `position` is `"absolute" | "relative" | "static"`) and without stealing the page's
+  scrollable width. The rail earns its place only while the centred column still has room
+  beside it (`pageWidth >= GUTTER * 2 + 560`); below that it collapses to the pinned bar.
+  Sizing the column is the SHELL's job — inner blocks are plain `width: "100%"`, never a
+  second `maxWidth` + `alignSelf: "center"`.
 
 ### `tpl_tasks` — the quick list
 

package/examples/tpl_record.tsx

@@ -367,6 +367,17 @@ function InvoiceBand({
   );
 }
 
+/** The section rail's width — and, mirrored as an empty right gutter, what
+ *  keeps the reading column centred in the viewport. */
+const RAIL_W = 208;
+/** Breathing room between the rail and the reading column (the docs' 3rem). */
+const RAIL_GAP = 48;
+/** The reserved gutter: the rail plus its gap. Mirrored empty on the right, this
+ *  is what centres the column. */
+const GUTTER = RAIL_W + RAIL_GAP;
+/** The reading column's ceiling. */
+const CONTENT_MAX = 720;
+
 export function TplRecord() {
   const id = useRef(1);
   const nextId = (prefix: string) => `${prefix}_${(id.current += 1)}`;
@@ -626,21 +637,25 @@ export function TplRecord() {
   // it opens a full-page section picker (Escape / the close control dismiss).
   const [sectionsOpen, setSectionsOpen] = useState(false);
   const [pageWidth, setPageWidth] = useState<number | null>(null);
-  const wide = pageWidth != null && pageWidth >= 760;
+  // The rail lives in the page's LEFT GUTTER and an equal spacer balances it on
+  // the right, so the reading column lands dead-centre in the viewport (the docs
+  // layout, where the right-hand TOC is the balancer). The rail only earns its
+  // place once the centred column still has room beside it: 2 × rail + a
+  // readable column — below that it collapses to the pinned bar.
+  const wide = pageWidth != null && pageWidth >= GUTTER * 2 + 560;
+  // The rail floats over its RESERVED gutter rather than sitting in the scroll
+  // row, so the ScrollView keeps the FULL page width — wheel anywhere and the
+  // record scrolls. (Capping the ScrollView at the column's width instead makes
+  // the gutters dead zones.) Mirrors the flex maths the row does below: the
+  // group is centred inside the 28px content padding.
+  const groupW = pageWidth == null ? 0 : Math.min(pageWidth - 28 * 2, GUTTER * 2 + CONTENT_MAX);
+  const railLeft = pageWidth == null ? 0 : 28 + Math.max(0, (pageWidth - 28 * 2 - groupW) / 2);
 
   return (
     // Measure-then-reveal: hidden until the width is known, so the rail/bar
     // choice never visibly reshuffles the page on first paint.
-    <View style={{ flex: 1, flexDirection: wide ? "row" : "column", backgroundColor: colors.white, opacity: pageWidth == null ? 0 : 1 }} onLayout={(e) => setPageWidth(e.nativeEvent.layout.width)}>
-      {pageWidth == null ? null : wide ? (
-        <View style={{ width: 208, borderRightWidth: 1, borderRightColor: colors.zinc[200], padding: 8 }}>
-          <View style={{ gap: 2 }}>
-            {SECTIONS.map((sec) => (
-              <MenuButton key={sec.key} icon={sec.icon} title={sec.label} selected={nav.activeKey === sec.key} onPress={() => nav.jumpTo(sec.key)} />
-            ))}
-          </View>
-        </View>
-      ) : (
+    <View style={{ flex: 1, backgroundColor: colors.white, opacity: pageWidth == null ? 0 : 1 }} onLayout={(e) => setPageWidth(e.nativeEvent.layout.width)}>
+      {pageWidth == null || wide ? null : (
         // Narrow: a pinned bar names the CURRENT section (the spy keeps it
         // honest while scrolling); tapping opens the full-page section picker —
         // no tab strip the thumb has to scroll.
@@ -653,11 +668,19 @@ export function TplRecord() {
           />
         </View>
       )}
+    <View style={{ flex: 1 }}>
+    {/* FULL-WIDTH scroller: the whole page scrolls, wherever the pointer is. */}
     <ScrollView ref={nav.scrollRef} onScroll={nav.onScroll} scrollEventThrottle={16} style={{ flex: 1 }} contentContainerStyle={{ padding: 28, paddingBottom: 96 }}>
+      {/* The centred group: a gutter RESERVED for the rail, the reading column,
+          and an equal empty gutter that balances it — so the column's centre is
+          the window's centre. Both gutters live INSIDE the scroller, so they
+          scroll like everything else. */}
+      <View style={{ width: "100%", maxWidth: wide ? GUTTER * 2 + CONTENT_MAX : CONTENT_MAX, alignSelf: "center", flexDirection: "row" }}>
+      {wide ? <View style={{ width: GUTTER, flexShrink: 0 }} /> : null}
       {/* the page column is a SectionStack — it owns the 56px beat + the
           hairline BETWEEN top-level blocks (a conditional block that renders
           null never leaves a stray divider) */}
-      <SectionStack style={{ width: "100%", maxWidth: 720, alignSelf: "center" }}>
+      <SectionStack style={{ flex: 1, minWidth: 0 }}>
         {/* header band — app bar + summary + key facts read as ONE block */}
         <View style={{ gap: 32 }}>
         {/* app bar — CREATE is one click; the surface is where everything is refined */}
@@ -1342,7 +1365,25 @@ export function TplRecord() {
           <Button title="Issue" color="primary" onPress={() => confirmIssue && issue(confirmIssue)} />
         </DialogFooter>
       </Dialog>
+      {/* Balances the rail so the reading column lands dead-centre. In the docs
+          layout the right-hand TOC does this job; a record surface has no TOC,
+          so the gutter is simply reserved. */}
+      {wide ? <View style={{ width: GUTTER, flexShrink: 0 }} /> : null}
+      </View>
     </ScrollView>
+    {/* The rail floats over its reserved gutter — pinned while the record
+        scrolls, and out of the scroll row so the page stays wheel-scrollable
+        edge to edge. */}
+    {pageWidth == null || !wide ? null : (
+      <View style={{ position: "absolute", top: 28, left: railLeft, width: RAIL_W }}>
+        <View style={{ gap: 2 }}>
+          {SECTIONS.map((sec) => (
+            <MenuButton key={sec.key} icon={sec.icon} title={sec.label} selected={nav.activeKey === sec.key} onPress={() => nav.jumpTo(sec.key)} />
+          ))}
+        </View>
+      </View>
+    )}
+    </View>
     </View>
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "11.8.4",
+  "version": "11.8.9",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",

package/src/back_button.tsx

@@ -1,26 +1,64 @@
 import { IconButton } from "./icon_button";
-import { View } from "react-native";
+import { Pressable, View } from "react-native";
+import { Icon } from "./icon";
+import { Text } from "./text";
+import { colors } from "./colors";
 import { useLoticsLocale } from "./locale";
 
 interface BackButtonProps {
   onPress: () => void;
-  /** Accessible name. Defaults to the locale's `nav.back` ("Back" / "Quay lại"). */
+  /** Names where back GOES ("Orders", "Danh sách"). Renders beside the glyph as
+   *  part of the SAME control — a label you can't press is a lie. Omit for the
+   *  bare glyph. */
+  label?: string;
+  /** Accessible name. Defaults to `label`, else the locale's `nav.back`
+   *  ("Back" / "Quay lại"). */
   accessibilityLabel?: string;
 }
 
 export function BackButton(props: BackButtonProps) {
   const locale = useLoticsLocale();
-  const { onPress, accessibilityLabel = locale.nav.back } = props;
+  const { onPress, label, accessibilityLabel = label ?? locale.nav.back } = props;
+  // Bare glyph — the circular icon IS the control.
+  if (label === undefined) {
+    return (
+      <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+        <IconButton
+          icon="chevron-left"
+          size="lg"
+          color="secondary"
+          accessibilityLabel={accessibilityLabel}
+          onPress={onPress}
+          style={{ alignSelf: "flex-start" }}
+        />
+      </View>
+    );
+  }
+  // Labelled — ONE pressable over glyph + label, so the words are a target too
+  // (an IconButton beside a Text would be a control next to unclickable prose).
   return (
-    <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-      <IconButton
-        icon="chevron-left"
-        size="lg"
-        color="secondary"
-        accessibilityLabel={accessibilityLabel}
-        onPress={onPress}
-        style={{ alignSelf: "flex-start" }}
-      />
-    </View>
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel}
+      onPress={onPress}
+      style={({ pressed, hovered }) => [
+        {
+          flexDirection: "row",
+          alignItems: "center",
+          gap: 6,
+          alignSelf: "flex-start",
+          paddingVertical: 6,
+          paddingLeft: 6,
+          paddingRight: 10,
+          borderRadius: 8,
+        },
+        (hovered || pressed) && { backgroundColor: colors.zinc[100] },
+      ]}
+    >
+      <Icon name="chevron-left" size={16} color={colors.zinc[500]} />
+      <Text size="sm" weight="medium" color="muted" numberOfLines={1}>
+        {label}
+      </Text>
+    </Pressable>
   );
 }

package/src/page_header.tsx

@@ -7,13 +7,29 @@ interface PageHeaderProps {
   description?: string | null;
   left?: ReactNode;
   right?: ReactNode;
+  /** Page-level actions (CTAs), rendered on the title row, right-aligned —
+   *  distinct from `left`/`right`, which form a separate nav row above. */
+  actions?: ReactNode;
 }
 
 export function PageHeader(props: PageHeaderProps) {
-  const { title, description, left, right } = props;
+  const { title, description, left, right, actions } = props;
 
   const hasNav = !!left || !!right;
 
+  const titleRow = actions ? (
+    <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", gap: 12 }}>
+      <Text size="xxl" weight="semibold">
+        {title}
+      </Text>
+      {actions}
+    </View>
+  ) : (
+    <Text size="xxl" weight="semibold">
+      {title}
+    </Text>
+  );
+
   return (
     <View style={{ paddingBottom: 16 }}>
       {hasNav ? (
@@ -22,14 +38,10 @@ export function PageHeader(props: PageHeaderProps) {
             {left}
             {right}
           </View>
-          <Text size="xxl" weight="semibold">
-            {title}
-          </Text>
+          {titleRow}
         </>
       ) : (
-        <Text size="xxl" weight="semibold">
-          {title}
-        </Text>
+        titleRow
       )}
       {!!description && (
         <Text color="zinc-500">{description}</Text>