duet-ui 0.1.0 → 0.2.0

package/README.md

@@ -19,15 +19,20 @@ On the closed Duo, Safari keeps a narrow column beside the page for its own butt
 ## Usage
 
 ```tsx
-import { Duet } from "duet-ui";
-import "duet-ui/styles.css";
+"use client";
+import { Duet, type DuetItem } from "duet-ui";
+
+const TABS = [
+  { id: "home", label: "Home", icon: <House size={24} /> },
+  { id: "search", label: "Search", icon: <Search size={24} /> },
+] as const satisfies readonly DuetItem[];
 
 export function App() {
-  const [tab, setTab] = useState("home");
+  const [tab, setTab] = useState<(typeof TABS)[number]["id"]>("home");
   return (
     <Duet
       tabs={{ items: TABS, selected: tab, onSelect: setTab }}
-      actions={[{ id: "share", label: "Share", icon: <Share />, onPress: share }]}
+      actions={[{ id: "share", label: "Share", icon: <Share size={22} />, onPress: share }]}
       minimizeOnScroll
     >
       <Page tab={tab} />
@@ -36,7 +41,9 @@ export function App() {
 }
 ```
 
-Add `viewport-fit=cover` to the viewport meta so the safe areas reach the page. Duet appends `shrink-to-fit=no` itself, so Safari doesn't zoom a split-view pane out to fit the column layer. On other phones and browsers Duet falls back to the `inline` strip.
+That is the whole setup. The styles come with the component, and Duet adds `viewport-fit=cover` and `shrink-to-fit=no` to the viewport meta itself (the safe areas only reach the page with the first; the second keeps Safari from zooming a split-view pane out). Each tab keeps its own scroll position, and tapping the selected tab scrolls back to the top. On other phones and browsers Duet falls back to the `inline` strip.
+
+Icons are yours, any library: 24pt in tabs, 21 to 22pt on round buttons matches the system. `as const` types the tab ids, so `onSelect` takes `setTab` without a cast.
 
 ## Modes
 
@@ -60,7 +67,27 @@ Each mode has a band the controls may use, and Duet keeps every control inside i
 
 ### Only on the Duo
 
-`useDuet().duo` is true on an iPhone Duo in any posture, Safari or Home Screen, and false on other phones and desktops. It works outside `<Duet>`, so an existing app can switch to a Duo layout on it: render `<Duet>` only when it is true. `isDuo(signals)` is the same check for your own signals. The server can't tell, so before hydration `duo` is true; remember the answer in a cookie if the server should render the right layout first.
+`useDuet().duo` is true on an iPhone Duo in any posture, Safari or Home Screen, and false on other phones and desktops. It works outside `<Duet>`, so an existing app can switch to a Duo layout on it: render `<Duet>` only when it is true. `isDuo(signals)` is the same check for your own signals.
+
+The server can't tell, so `<DuoCookie>` tells it: it keeps a `duet-duo` cookie in step with the browser, and a new device reloads once into the right layout. In the Next.js App Router:
+
+```tsx
+// app/page.tsx, a server component
+import { cookies } from "next/headers";
+import { DuoCookie } from "duet-ui";
+
+export default async function Page() {
+  const duo = (await cookies()).get("duet-duo")?.value === "1";
+  return (
+    <>
+      <DuoCookie rendered={duo} />
+      {duo ? <DuoApp /> : <DesktopApp />}
+    </>
+  );
+}
+```
+
+Pass `onChange={() => router.refresh()}` from a client component to re-render without a reload.
 
 ### In-app preview
 
@@ -74,7 +101,7 @@ Links opened from social and mail apps land in the in-app Safari preview (`SFSaf
 | `leading` | Its own group under back, like SwiftUI `.topBarLeading` |
 | `actions` | Like `.primaryAction`; collapses into "…" when it would reach the tabs. Items with `destructive: true` only ever show in "…", last, in red |
 | `primary` | The one main action (compose, new). Narrow: just above the tabs. Wide: under back, at the top. Folds into "…" last, only when the band has no room for both |
-| `tabs` | `{ items, selected, onSelect, search? }`. `search` adds a search tab as the last item |
+| `tabs` | `{ items, selected, onSelect, search? }`. `search` adds a search tab as the last item. Each tab keeps its scroll position |
 | `searchButton` | A round search button at the bottom when there are no tabs |
 | `close` | A sheet or card is open: the strip holds only a close button until it is cleared |
 | `accessory` | A view docked by the tabs, like `.tabViewBottomAccessory` (a mini player) |

package/dist/chrome.d.ts

@@ -13,7 +13,11 @@ export interface DuetItem {
     /** Deletes or discards: lives only in "…", last, in red, after a separator (blueprint). */
     destructive?: boolean;
 }
-export interface DuetProps {
+/** A tab: an item whose id is one of the app's tab ids. */
+export type DuetTab<T extends string = string> = DuetItem & {
+    id: T;
+};
+export interface DuetProps<T extends string = string> {
     /** Back button, top of the strip. */
     back?: false | {
         label?: string;
@@ -27,12 +31,14 @@ export interface DuetProps {
     /** The screen's main action (New chat, Compose), a tinted round button: by the thumb above the tabs where one
      *  pane shows, at the top under back where two do. */
     primary?: DuetItem;
-    /** Tab pill at the bottom of the strip. `search` adds a `role: .search` tab as the last item. */
+    /** Tab pill at the bottom of the strip. `search` adds a `role: .search` tab as the last item. The ids are typed
+     *  from `items`: declare them `as const` and `onSelect` gets the union, so `setTab` fits without a cast. Each tab
+     *  keeps its own scroll position, and tapping the selected tab scrolls it to the top, like a native tab bar. */
     tabs?: {
-        items: DuetItem[];
-        selected: string;
-        onSelect: (id: string) => void;
-        search?: DuetItem;
+        items: readonly DuetTab<T>[];
+        selected: NoInfer<T>;
+        onSelect: (id: NoInfer<T>) => void;
+        search?: DuetTab<T>;
     };
     /** Searchable without tabs: a round search button at the bottom of the strip. */
     searchButton?: () => void;
@@ -56,4 +62,12 @@ export interface DuetProps {
     children?: ReactNode;
 }
 export declare function useDuet(): Context;
-export declare function Duet(p: DuetProps): import("react").JSX.Element;
+/** Tells the server whether this browser is an iPhone Duo, so it can render the Duo layout from the first byte.
+ *  The server can't tell on its own, so it renders what the `duet-duo` cookie says (`"1"` on a Duo) and passes that
+ *  as `rendered`. When the browser disagrees, this sets the cookie and calls `onChange`, by default a reload, so a
+ *  new device switches layout once and never again. Renders nothing; works outside `<Duet>`. */
+export declare function DuoCookie({ rendered, onChange }: {
+    rendered: boolean;
+    onChange?: (duo: boolean) => void;
+}): null;
+export declare function Duet<T extends string = string>(props: DuetProps<T>): import("react").JSX.Element;

package/dist/chrome.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
 import { ArrowLeftRight, ChevronLeft, Ellipsis, Search, X } from "./icons.js";
 import { DUO, INLINE_WIDTH, ISLAND, MORPH, isSplit, magnet, plan, stable } from "./geometry.js";
 import { GlassProvider } from "./glassyui/glass-provider.js";
@@ -120,6 +120,23 @@ const ssr = { mode: "column", duo: true, layout: "narrow", side: "right", width:
 export function useDuet() {
     return useSyncExternalStore(subscribe, read, () => ssr);
 }
+/** Tells the server whether this browser is an iPhone Duo, so it can render the Duo layout from the first byte.
+ *  The server can't tell on its own, so it renders what the `duet-duo` cookie says (`"1"` on a Duo) and passes that
+ *  as `rendered`. When the browser disagrees, this sets the cookie and calls `onChange`, by default a reload, so a
+ *  new device switches layout once and never again. Renders nothing; works outside `<Duet>`. */
+export function DuoCookie({ rendered, onChange = () => location.reload() }) {
+    const { duo } = useDuet();
+    // Before hydration useDuet() answers for the server (a Duo); only the browser's own answer counts.
+    const hydrated = useSyncExternalStore(noop, () => true, () => false);
+    useEffect(() => {
+        if (!hydrated || duo === rendered)
+            return;
+        document.cookie = duo ? "duet-duo=1; path=/; max-age=31536000; samesite=lax" : "duet-duo=; path=/; max-age=0";
+        onChange(duo);
+    }, [hydrated, duo, rendered]); // eslint-disable-line react-hooks/exhaustive-deps -- onChange may be a fresh arrow each render
+    return null;
+}
+const noop = () => () => { };
 function useMinimized(on, scroller) {
     const [min, setMin] = useState(false);
     useEffect(() => {
@@ -153,13 +170,19 @@ function useMinimized(on, scroller) {
 let tapSide = "right";
 /** Without shrink-to-fit=no Safari zooms a split pane out to fit the layer's overflow, which reads as another
  *  window size and flips the mode. It applies even when set late, but must land before the first column paint. */
-function noShrink() {
-    const meta = document.querySelector("meta[name=viewport]");
-    if (meta && !/shrink-to-fit/.test(meta.content))
-        meta.content += ",shrink-to-fit=no";
+function viewport(key, value) {
+    let meta = document.querySelector("meta[name=viewport]");
+    if (!meta) {
+        meta = document.createElement("meta");
+        meta.name = "viewport";
+        meta.content = "width=device-width,initial-scale=1";
+        document.head.appendChild(meta);
+    }
+    if (!meta.content.includes(key))
+        meta.content += `,${key}=${value}`;
 }
 if (typeof document !== "undefined")
-    noShrink();
+    viewport("shrink-to-fit", "no");
 function useColumnLayer(on, split, column) {
     const refs = [useRef(null), useRef(null)];
     useEffect(() => {
@@ -277,7 +300,10 @@ function useSideDrag(side, nav, onStart) {
     }, [side, nav]); // eslint-disable-line react-hooks/exhaustive-deps -- onStart only resets menu and scrub state
 }
 // --- rendering ----------------------------------------------------------------------------------
-export function Duet(p) {
+// useLayoutEffect warns during SSR on React 18.
+const useLayout = typeof window === "undefined" ? useEffect : useLayoutEffect;
+export function Duet(props) {
+    const p = props; // tab ids are only typed at the boundary
     const ctx = useDuet();
     const scroller = useRef(null);
     const minimized = useMinimized(!!p.minimizeOnScroll, scroller);
@@ -348,7 +374,24 @@ export function Duet(p) {
         return () => removeEventListener("pointerdown", close);
     }, [menu, nav, nav2]); // eslint-disable-line react-hooks/exhaustive-deps -- setMenu only reads menu
     useSideDrag(ctx.mode === "inline" ? ctx.side : null, nav, () => { setMenu(null); setScrub(null); });
+    // The safe areas only reach the page with viewport-fit=cover. Set on mount, not on import, so a page that only
+    // imports DuoCookie keeps its own viewport on other phones.
+    useLayout(() => viewport("viewport-fit", "cover"), []);
     const selected = p.tabs?.selected;
+    // Each tab keeps its own scroll position in the inner scroller; the selected tab again scrolls to the top.
+    const scrolls = useRef(new Map());
+    const select = (id) => {
+        const el = scroller.current;
+        if (id === selected)
+            el?.scrollTo({ top: 0, behavior: "smooth" });
+        else {
+            if (el && selected !== undefined)
+                scrolls.current.set(selected, el.scrollTop);
+            p.tabs.onSelect(id);
+        }
+    };
+    useLayout(() => { if (scroller.current && selected !== undefined)
+        scroller.current.scrollTop = scrolls.current.get(selected) ?? 0; }, [selected]);
     const badge = (a) => a.badge !== undefined && a.badge !== "" && _jsx("span", { className: "duet-badge", children: a.badge });
     const tint = (a) => a.tint ? { "--duet-tint": a.tint } : undefined;
     const item = (a) => _jsxs("button", { className: "duet-item", "aria-label": a.label, onClick: a.onPress, children: [a.icon, badge(a)] }, a.id);
@@ -372,7 +415,7 @@ export function Duet(p) {
     const glideTo = (id) => {
         if (id !== selected)
             settle();
-        p.tabs.onSelect(id);
+        select(id);
     };
     // Scrub: holding or dragging on the full pill swells it and shows labels; a lens follows the finger over the
     // tabs and the tab under it lights up; lifting selects it. A quick tap just glides the lens to the tab.
@@ -416,7 +459,7 @@ export function Duet(p) {
                 setScrub(null);
                 settle();
                 if (t)
-                    p.tabs.onSelect(t.id);
+                    select(t.id);
             }
             else if (tapped) {
                 const t = tabItems[tabAt(e.currentTarget, e.clientY)];
@@ -448,7 +491,7 @@ export function Duet(p) {
         const close = kind === "more" && !morph, rolling = menu !== kind;
         return (_jsxs(GlassSurface, { preset: "control", className: "duet-glass duet-menu", role: "menu", "data-style": morph ? "morph" : undefined, style: morph ? morphAt(anchor, items.length) : menuAt(anchor, items.length + (close ? 1 : 0)), "data-closing": rolling || undefined, onAnimationEnd: (e) => { if (rolling && (e.animationName === "duet-roll" || e.animationName === "duet-unmorph"))
                 setClosing(null); }, children: [items.map((a, i) => (_jsxs("button", { role: radio ? "menuitemradio" : "menuitem", "aria-checked": radio ? a.id === selected : undefined, "aria-label": a.label, className: "duet-menu-item", "data-on": (radio && a.id === selected) || undefined, "data-destructive": a.destructive || undefined, "data-sep": (a.destructive && i > 0 && !items[i - 1].destructive) || undefined, "data-tint": a.tint ? "" : undefined, style: { ...tint(a), ...(rolling ? undefined : { animationDelay: `${morph ? 0.12 + 0.04 * i : 0.14 + 0.06 * (items.length - i)}s` }) }, onClick: () => { setMenu(null); if (radio)
-                        p.tabs.onSelect(a.id);
+                        select(a.id);
                     else
                         a.onPress?.(); }, children: [a.icon, morph && _jsx("span", { className: "duet-menu-label", children: a.label }), badge(a)] }, a.id))), close && _jsx("button", { className: "duet-menu-item", "aria-label": "Close", onClick: () => setMenu(null), children: _jsx(X, { size: 20 }) })] }));
     };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { Duet, useDuet, type DuetProps, type DuetItem } from "./chrome.tsx";
+export { Duet, DuoCookie, useDuet, type DuetProps, type DuetItem, type DuetTab } from "./chrome.tsx";
 export { bleed, column } from "./layout.ts";
 export { DuetPanes, DuetPaneBar, usePanes, type DuetPanesProps, type DuetPaneBarProps } from "./duet-panes.tsx";
 export { panes, backFrom, type PaneWindow } from "./panes.ts";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { Duet, useDuet } from "./chrome.js";
+export { Duet, DuoCookie, useDuet } from "./chrome.js";
 export { bleed, column } from "./layout.js";
 export { DuetPanes, DuetPaneBar, usePanes } from "./duet-panes.js";
 export { panes, backFrom } from "./panes.js";

package/package.json

@@ -1,20 +1,32 @@
 {
   "name": "duet-ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Native-feeling controls for React web apps on the foldable iPhone: the side strip, Safari's column, split view and Home Screen apps.",
   "license": "MIT",
   "type": "module",
-  "sideEffects": ["*.css"],
+  "sideEffects": [
+    "*.css"
+  ],
   "exports": {
-    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
-    "./geometry": { "types": "./dist/geometry.d.ts", "default": "./dist/geometry.js" },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./geometry": {
+      "types": "./dist/geometry.d.ts",
+      "default": "./dist/geometry.js"
+    },
     "./styles.css": "./dist/duet.css"
   },
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/copy-css.mjs",
     "prepack": "pnpm build && node scripts/pack-docs.mjs",
-    "test": "node --test test/",
+    "test": "node --test \"test/*.test.mjs\"",
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
@@ -28,8 +40,23 @@
     "react-dom": "19.3.0",
     "typescript": "^5.9.0"
   },
-  "keywords": ["react", "nextjs", "iphone", "foldable", "ios", "safari", "pwa", "liquid-glass", "tab-bar", "navigation"],
-  "repository": { "type": "git", "url": "git+https://github.com/JayFarei/duet.git", "directory": "packages/duet-ui" },
+  "keywords": [
+    "react",
+    "nextjs",
+    "iphone",
+    "foldable",
+    "ios",
+    "safari",
+    "pwa",
+    "liquid-glass",
+    "tab-bar",
+    "navigation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JayFarei/duet.git",
+    "directory": "packages/duet-ui"
+  },
   "homepage": "https://github.com/JayFarei/duet#readme",
   "bugs": "https://github.com/JayFarei/duet/issues",
   "author": "JayFarei"