duet-ui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JayFarei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+# Duet
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Native-feeling controls for React web apps on the foldable iPhone. Your page and its control strip, playing together.
+
+```sh
+npm i duet-ui
+```
+
+| Strip | Column | Inline |
+| --- | --- | --- |
+| ![Strip: a Home Screen app with the island menu](https://raw.githubusercontent.com/JayFarei/duet/main/docs/media/strip.webp) | ![Column: Safari's empty column holds the controls, morph menu](https://raw.githubusercontent.com/JayFarei/duet/main/docs/media/column.webp) | ![Inline: unfolded, the strip drags to either side](https://raw.githubusercontent.com/JayFarei/duet/main/docs/media/inline-drag.webp) |
+
+Recorded on the iPhone Duo simulator, framed by [`tools/media`](https://github.com/JayFarei/duet/tree/main/tools/media).
+
+## Why
+
+On the closed Duo, Safari keeps a narrow column beside the page for its own buttons, and a Home Screen app owns the whole display. iOS puts navigation in a vertical strip at the screen's edge, not a bottom tab bar. A web page that ignores this ends up with its own bar fighting Safari's, or its buttons under the camera. Duet works out where the page is running and draws back, actions and tabs where a native app would.
+
+## Usage
+
+```tsx
+import { Duet } from "duet-ui";
+import "duet-ui/styles.css";
+
+export function App() {
+  const [tab, setTab] = useState("home");
+  return (
+    <Duet
+      tabs={{ items: TABS, selected: tab, onSelect: setTab }}
+      actions={[{ id: "share", label: "Share", icon: <Share />, onPress: share }]}
+      minimizeOnScroll
+    >
+      <Page tab={tab} />
+    </Duet>
+  );
+}
+```
+
+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.
+
+## Modes
+
+Duet picks a mode from the window size, safe areas and display mode. `useDuet()` returns it.
+
+| Mode | When | Controls |
+| --- | --- | --- |
+| `strip` | Home Screen app, closed | In the slim strip beside the page, like a native app |
+| `column` | Safari tab, closed or a split-view pane | Painted into the column Safari leaves empty, so the page keeps its full width. In split view both columns get the controls, since a pane can't tell which side it is on, and each shows only its own |
+| `inline` | Unfolded, landscape, in-app preview | An 84pt strip inside the page. Drag it to either side; the choice is remembered |
+
+### Claimable space
+
+Each mode has a band the controls may use, and Duet keeps every control inside it, so you never position anything yourself:
+
+- **Above:** the status bar and Dynamic Island, and in Safari its own back and bookmarks buttons at the top of the column (in a split-view pane, wherever that pane puts them). Live Activities grow the island down the strip and push Safari's buttons with it, and a page can't tell, so the band always assumes the worst case, two activities. The space they would take stays empty even when none are running. A split-view pane on the right sits under the same status column, so it gets the same small band as a closed tab, while the left pane uses the full column.
+- **Below:** Safari's +/tabs pill, or the home indicator.
+- **What does not fit folds into "…"**, in this order: actions, then `leading`, then back. Tabs shrink to the selected one first. "…" always gets a slot: where the band holds only two buttons (a closed Safari tab), `primary` folds too, as the menu's first item.
+
+`useDuet()` gives the mode; the band follows from it. The menus ("island" or "morph") open over the page and close back into their button.
+
+### 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.
+
+### In-app preview
+
+Links opened from social and mail apps land in the in-app Safari preview (`SFSafariViewController`). On the closed Duo its window is a fixed 375x667 at 3x, a size no iPhone has natively, and its own close and share buttons sit where the column would. Duet detects it, switches to `inline` on the left, and sets `useDuet().preview`.
+
+## Props
+
+| Prop | What it does |
+| --- | --- |
+| `back` | Back button at the top of the strip: `{ label?, onPress }` |
+| `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 |
+| `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) |
+| `minimizeOnScroll` | Scrolling down shrinks the tabs to one button, like `.tabBarMinimizeBehavior(.onScrollDown)` |
+| `menuStyle` | How "…" and the minimized tab open: `"island"` or `"morph"` (below) |
+| `dark` | Force a theme. Default: follow the system |
+| `children` | Page content, in an inner scroller so the chrome stays still during momentum scroll |
+
+Each `DuetItem` is `{ id, label, icon, onPress?, badge?, tint?, destructive? }`.
+
+### Menu styles
+
+- `"island"` (default): the button stretches sideways into a pill of icons, like the Dynamic Island. Best when the icons speak for themselves.
+- `"morph"`: the button grows into a labelled list, like a context menu. Best when items need their names.
+
+Both are live on the [site](https://github.com/JayFarei/duet/tree/main/apps/site): scroll until the tabs shrink, tap the button, and switch styles in the Menus card.
+
+### Laying out content
+
+The page spans the whole window and the controls float over it, so backgrounds run on under them and the layout is asymmetric, like a native app. Only text and buttons keep clear.
+
+- `column(maxWidth, pad)`: a centred reading column. It centres on the whole window and moves aside from the controls only as far as it must. The `duet-column` class does the same in CSS (`--duet-max`, `--duet-pad`).
+- `bleed(pad)`: a full-width band (hero, sticky bar, list row). The band runs under the controls, its content is padded back beside them. `bleed(false)` runs content itself edge to edge (a map, an image).
+
+The insets are exposed as `--duet-inset-left`, `--duet-inset-right` and `--duet-inset-top` (the strip's top blur in Home Screen apps). Inside `<DuetPanes>` each pane gets its own: only the pane next to the controls is inset.
+
+## Panes
+
+Apps with a path of screens (mailboxes, inbox, message) follow the fold with `<DuetPanes>`: closed or in split view one pane shows, unfolded two adjacent panes show side by side. Going deeper slides the pair along the path instead of opening a modal. Unfolding slides the neighbouring pane in, and folding plays the same motion backwards. Every pane stays mounted, so drafts and scroll positions survive the fold.
+
+```tsx
+import { Duet, DuetPanes, usePanes } from "duet-ui";
+
+const PATH = ["mailboxes", "inbox", "message"];
+
+export function Mail() {
+  const nav = usePanes(PATH);
+  return (
+    <Duet back={nav.back}>
+      <DuetPanes path={PATH} at={nav.at} panes={{
+        mailboxes: <Mailboxes onOpen={() => nav.go("inbox")} />,
+        inbox: <InboxList onOpen={() => nav.go("message")} />,
+        message: <Message />,
+      }} />
+    </Duet>
+  );
+}
+```
+
+`<DuetPaneBar>` is the pane's header pill: close, a full-screen toggle (wide only) and "…" with the pane's own actions, destructive ones last. `nav.toggle` gives the focused pane the whole window (`expanded`); back leaves full screen before it steps along the path.
+
+`minimizeOnScroll` follows whichever pane scrolls. `useDuet().layout` is `"wide"` when the page has room for two panes (600pt beside the controls: the open Duo at full width) and `"narrow"` otherwise, from the page width rather than the posture. `nav.back` steps back along the path and is `false` when that would change nothing on screen, so the back button only shows when it does something. Try it on the [site](https://github.com/JayFarei/duet/tree/main/apps/site) at `/panes`.
+
+## Examples
+
+| App | Shows | Run |
+| --- | --- | --- |
+| [Almanac](https://github.com/JayFarei/duet/tree/main/examples/almanac) | Reading app on `<DuetPanes>`: the list beside the story unfolded, a pane bar, tabs with search, morph menus, sticky title with `bleed` | `pnpm --filter @duet/example-almanac dev`, port 3101 |
+| [Encore](https://github.com/JayFarei/duet/tree/main/examples/encore) | Music player: badges, mini player `accessory`, island menus, carousels with `bleed` | `pnpm --filter @duet/example-encore dev`, port 3103 |
+| [Meridian](https://github.com/JayFarei/duet/tree/main/examples/meridian) | Transit map on Vite: `leading`, a full-screen map with `bleed(false)` | `pnpm --filter @duet/example-meridian dev`, port 3102 |
+
+`pnpm dev` from the root builds the library and starts the site and every example.
+
+## Repo
+
+| Path | What |
+| --- | --- |
+| [`packages/duet-ui`](https://github.com/JayFarei/duet/tree/main/packages/duet-ui) | The library |
+| [`apps/site`](https://github.com/JayFarei/duet/tree/main/apps/site) | Docs site. On a desktop it runs itself inside a web Duo you can fold, rotate and scrub through the fold (with ¼ speed) |
+| [`examples`](https://github.com/JayFarei/duet/tree/main/examples) | Example apps |
+| [`tools/simulator`](https://github.com/JayFarei/duet/tree/main/tools/simulator) | Driving the iPhone Duo simulator |
+| [`tools/media`](https://github.com/JayFarei/duet/tree/main/tools/media) | Framing simulator recordings for docs |
+| [`e2e`](https://github.com/JayFarei/duet/tree/main/e2e) | Playwright tests |
+
+```sh
+pnpm install
+pnpm typecheck && pnpm test && pnpm build
+pnpm test:e2e
+```
+
+## License
+
+MIT. Not affiliated with Apple.

package/dist/chrome.d.ts

@@ -0,0 +1,59 @@
+import { type ReactNode } from "react";
+import { type Context } from "./geometry.ts";
+import "./duet.css";
+export interface DuetItem {
+    id: string;
+    label: string;
+    icon: ReactNode;
+    onPress?: () => void;
+    /** Count or short text in a red badge on the icon's page-side corner, like a native tab item's badge. */
+    badge?: number | string;
+    /** Colour of the icon and selection when this tab is selected. Default: the system blue. */
+    tint?: string;
+    /** Deletes or discards: lives only in "…", last, in red, after a separator (blueprint). */
+    destructive?: boolean;
+}
+export interface DuetProps {
+    /** Back button, top of the strip. */
+    back?: false | {
+        label?: string;
+        onPress: () => void;
+    };
+    /** SwiftUI `.topBarLeading`: its own group under back. */
+    leading?: DuetItem[];
+    /** SwiftUI `.primaryAction`: collapses into "…" when it would hit the tab pill. Destructive items always
+     *  go in "…". */
+    actions?: DuetItem[];
+    /** 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. */
+    tabs?: {
+        items: DuetItem[];
+        selected: string;
+        onSelect: (id: string) => void;
+        search?: DuetItem;
+    };
+    /** Searchable without tabs: a round search button at the bottom of the strip. */
+    searchButton?: () => void;
+    /** A sheet or card is open: the strip holds only a close button, where back goes, like an iOS sheet. Every
+     *  other control steps aside until it is cleared. */
+    close?: false | {
+        label?: string;
+        onPress: () => void;
+    };
+    /** `.tabViewBottomAccessory`, e.g. a mini player. */
+    accessory?: ReactNode;
+    /** `.tabBarMinimizeBehavior(.onScrollDown)`. */
+    minimizeOnScroll?: boolean;
+    /** Force a theme. Default: follow the system light/dark setting. */
+    dark?: boolean;
+    /** How "…" and the minimized tab open their menu. "island" (default): the button stretches sideways into a
+     *  pill of icons, like the Dynamic Island. "morph": the button grows into a labelled list, like a context menu. */
+    menuStyle?: "island" | "morph";
+    /** Page content. When given, it scrolls in an inner scroller and the document itself never moves, so
+     *  the chrome (and in Safari the column layer) stays still during momentum scroll and rubber-banding. */
+    children?: ReactNode;
+}
+export declare function useDuet(): Context;
+export declare function Duet(p: DuetProps): import("react").JSX.Element;