@stealthscale/component-screen 0.0.1 → 0.2.1

package/README.md

@@ -5,7 +5,8 @@ page, the sidebar of destinations, the switcher at the head of a sidebar, the to
 the action bar over a selection, the splitter between panels a person resizes and the floating panel
 a person moves over the page. Every component takes its styles from a recipe, so a theme restyles
 all nine by extending the recipes. The preset under `./theme` registers the recipes with an
-application's compiler.
+application's compiler. The entry under `./shell` adds the switchers of the locale and the theme,
+which render the switcher's recipe.
 
 Every value a theme can change is an axis of a recipe, so a caller sets it as a prop and writes no
 style. A caller changes the element a component renders with `as`.
@@ -16,10 +17,12 @@ style. A caller changes the element a component renders with `as`.
 pnpm add @stealthscale/component-screen
 ```
 
-The package peers on `react`, `@stealthscale/theme`, `@stealthscale/hooks`,
+The package peers on `react`, `react-dom`, `@stealthscale/theme`, `@stealthscale/hooks`,
 `@stealthscale/provider-viewport` and the component packages it renders: `a11y`, `actions`, `data`,
 `disclosure`, `forms`, `layout`, `modals`, `navigation`, `primitives` and `typography`. An
-application lists the preset under `./theme` among the presets its compiler installs.
+application lists the preset under `./theme` among the presets its compiler installs. The `./shell`
+entry also imports `@stealthscale/provider-locale` and `@stealthscale/provider-shell`. Both peers
+are optional, so an application that imports only the main entry installs neither.
 
 ## Folding
 
@@ -29,18 +32,25 @@ open sidebar folds on the width the sidebar leaves it, and a caller does not wri
 media query. Before the element is laid out, and where the browser does not report a size, the
 viewport's width decides, so a phone never lays out wide first.
 
+A toolbar also folds while its controls need more room than its row has. It measures the row while
+no control is folded, and tries the unfolded row again when the row or the window changes width.
+While the folded controls still need more room, the toolbar moves its secondary actions and links
+and its switchers into its menu, the control nearest the row's end first, until the rest fit. The
+row adds up the boxes of its controls, so a touch target larger than its control does not fold it.
+
 `Toolbar.Action`, `Page.Action` and `Section.Action` fold by priority. An action states `priority`,
 or the action's props imply one:
 
-| Props                        | Priority    | On a narrow row                         |
-| ---------------------------- | ----------- | --------------------------------------- |
-| `primary`, no `icon`         | `primary`   | Unchanged                               |
-| `icon`                       | `secondary` | Icon alone, the label hidden visually   |
-| neither `primary` nor `icon` | `tertiary`  | Removed from the row, a row in its menu |
+| Props                        | Priority    | On a narrow row                                          |
+| ---------------------------- | ----------- | -------------------------------------------------------- |
+| `primary`, no `icon`         | `primary`   | Unchanged                                                |
+| `icon`                       | `secondary` | Icon alone. In a toolbar without room, a row in its menu |
+| neither `primary` nor `icon` | `tertiary`  | Removed from the row, a row in its menu                  |
 
 - A secondary action keeps its label for screen readers.
 - A tertiary action leaves the row and the tab order. The row renders a menu with one row per folded
-  action.
+  action. When one of those rows leads with an icon, the menu pads the others to the icon's gutter,
+  so the words of every row start at one line.
 - `more` names the menu's trigger, `More actions` by default. `moreIcon` replaces the trigger's
   words with a mark.
 - A folded link keeps its `href` in its menu row. A menu row calls the action's `onClick`.
@@ -100,7 +110,8 @@ import { ActionBar, Toolbar } from "@stealthscale/component-screen";
   toolbar renders its menu of folded actions as its last control, beside the actions. Give the main
   action `priority="primary"` to keep its words in a narrow window.
 - The bar is as wide as its content, at least `sizes.2xl`, 672px, and at most the window inside the
-  inset. Its toolbar folds in a narrow window and not because of its own content.
+  inset. Its toolbar folds in a narrow window, and while its controls need more room than the window
+  leaves the bar.
 - The positioner is fixed above the safe area at the `banner` layer and takes no pointer events, so
   the page beside the bar remains pressable. `placement` sets the bar at the start, in the middle or
   at the end of the bottom edge, and start and end follow the writing direction.
@@ -125,8 +136,8 @@ The bar does not offer these:
 
 ## AppShell
 
-Lays out an application: bars across the top and the bottom, a body between them with a panel on
-either side of the main region, and a status bar at the foot.
+Lays out an application: bars across the top and the bottom, a body between them with panels on
+either side of the main region or of a pane, and a status bar at the foot.
 
 ```tsx
 import { AppShell, Sidebar } from "@stealthscale/component-screen";
@@ -154,10 +165,13 @@ import { AppShell, Sidebar } from "@stealthscale/component-screen";
 
 | Axis      | Values                       | Default |
 | --------- | ---------------------------- | ------- |
+| `content` | `fluid`, `constrained`       | `fluid` |
 | `divided` | `true`, `false`              | `true`  |
 | `scroll`  | `page`, `window`             | `page`  |
 | `variant` | `floating`, `inset`, `plain` | `plain` |
 
+- `content="constrained"` caps the page in the main region at the theme's wide page measure,
+  `sizes.page.wide`, and centres it. `fluid` gives the page the whole region.
 - `divided` renders a hairline on the inner edge of each bar and each panel. A sidebar inside a
   panel sets its ground and no line.
 - `scroll="page"` sets the shell to the window's height and scrolls the main region. While a panel
@@ -183,19 +197,20 @@ The shell has no `palette` and no `effect` axis, because its parts are container
 
 ### Parts
 
-| Part               | Element  | Landmark        |
-| ------------------ | -------- | --------------- |
-| `AppShell.Root`    | `div`    | none            |
-| `AppShell.Header`  | `header` | `banner`        |
-| `AppShell.Body`    | `div`    | none            |
-| `AppShell.Navbar`  | `div`    | none            |
-| `AppShell.Rail`    | `button` | none            |
-| `AppShell.Main`    | `main`   | `main`          |
-| `AppShell.Aside`   | `aside`  | `complementary` |
-| `AppShell.Section` | `div`    | none            |
-| `AppShell.Footer`  | `footer` | `contentinfo`   |
-| `AppShell.Status`  | `div`    | none            |
-| `AppShell.Trigger` | `button` | none            |
+| Part               | Element                                                               | Landmark        |
+| ------------------ | --------------------------------------------------------------------- | --------------- |
+| `AppShell.Root`    | `div`                                                                 | none            |
+| `AppShell.Header`  | `header`                                                              | `banner`        |
+| `AppShell.Body`    | `div`                                                                 | none            |
+| `AppShell.Navbar`  | `div`                                                                 | none            |
+| `AppShell.Rail`    | `button`, or a `div` in the `separator` role beside a resizable panel | none            |
+| `AppShell.Pane`    | `div`                                                                 | none            |
+| `AppShell.Main`    | `main`                                                                | `main`          |
+| `AppShell.Aside`   | `aside`                                                               | `complementary` |
+| `AppShell.Section` | `div`                                                                 | none            |
+| `AppShell.Footer`  | `footer`                                                              | `contentinfo`   |
+| `AppShell.Status`  | `section`                                                             | `region`        |
+| `AppShell.Trigger` | `button`                                                              | none            |
 
 `AppShell.Navbar` has no landmark, because a sidebar inside it renders its own navigation landmarks.
 Name `AppShell.Aside` with `aria-label` when an application renders more than one.
@@ -203,8 +218,10 @@ Name `AppShell.Aside` with `aria-label` when an application renders more than on
 Render `AppShell.Status` after the footer, for the state of the application: the connection, a sync,
 work that runs in the background. It lays its entries out in a row that wraps, padded by
 `spacing.gap.xs` above and below and `spacing.gap.md` at the sides, with a hairline above it under
-`divided`. It is not a live region, so an entry that reports a change renders its own `output`.
-Under `scroll="window"` the bar is at the end of the document.
+`divided`. The bar is a region named by `label`, `Status` by default, so its entries are inside a
+landmark. It is not a live region, so an entry that reports a change renders its own `output`. Under
+`scroll="window"` the bar is at the end of the document. The bar takes no room while every entry in
+it renders nothing.
 
 `AppShell.Section` is a padded band in a panel or in the main region. `grows` gives it the room its
 siblings leave, and `scrolls` makes it a scroll area, so the bands around it remain in place. A band
@@ -218,46 +235,101 @@ height exactly and scrolls its own list.
 
 `AppShell.Navbar` and `AppShell.Aside` are the same panel on the two sides.
 
-| Prop           | Values                | Default                                        |
-| -------------- | --------------------- | ---------------------------------------------- |
-| `collapse`     | `hide`, `icons`       | `hide`                                         |
-| `folds`        | `over`, `under`       | `over`                                         |
-| `foldsBelow`   | a breakpoint, `never` | `md` on the start side, `lg` on the end side   |
-| `width`        | a CSS length          | `sizes.sidebar` or `sizes.aside`               |
-| `railWidth`    | a CSS length          | `sizes.rail`                                   |
-| `defaultOpen`  | `true`, `false`       | `true`                                         |
-| `open`         | `true`, `false`       | uncontrolled                                   |
-| `onOpenChange` | a function            | none                                           |
-| `name`         | a string              | `navbar` on the start side, `aside` on the end |
-| `shortcut`     | a key                 | none                                           |
+| Prop           | Values                  | Default                                        |
+| -------------- | ----------------------- | ---------------------------------------------- |
+| `collapse`     | `hide`, `icons`         | `hide`                                         |
+| `folds`        | `over`, `under`, `hide` | `over`                                         |
+| `foldsBelow`   | a breakpoint, `never`   | `md` on the start side, `lg` on the end side   |
+| `width`        | a CSS length            | `sizes.sidebar` or `sizes.aside`               |
+| `railWidth`    | a CSS length            | `sizes.rail`                                   |
+| `defaultOpen`  | `true`, `false`         | `true`                                         |
+| `open`         | `true`, `false`         | uncontrolled                                   |
+| `onOpenChange` | a function              | none                                           |
+| `name`         | a string                | `navbar` on the start side, `aside` on the end |
+| `shortcut`     | a key                   | none                                           |
+| `resizable`    | `true`, `false`         | `false`                                        |
+| `defaultSize`  | pixels                  | `width`                                        |
+| `size`         | pixels                  | uncontrolled                                   |
+| `onSizeChange` | a function              | none                                           |
+| `minSize`      | pixels                  | 192                                            |
+| `maxSize`      | pixels                  | half the window                                |
 
 - `collapse` sets what closing the panel beside the page leaves: `hide` hides it, and `icons` leaves
   a rail of `railWidth`. A sidebar inside the panel renders as a rail on its own.
 - `folds` sets where the panel goes when the shell is narrower than `foldsBelow`: `over` lays it
-  over the page behind a backdrop, and `under` drops it under the main region as a block that is
-  always shown. `foldsBelow="never"` keeps the panel in the body at every width.
+  over the page behind a backdrop, `under` drops it under the main region as a block that is always
+  shown, and `hide` takes it out of the shell until the shell is wide enough again, such as a rail
+  of apps whose destinations a bar at the foot of the shell lists on a phone. A panel out of the
+  shell is hidden and inert. Its trigger and its rail do not render, and its shortcut does not
+  toggle it. `foldsBelow="never"` keeps the panel in the body at every width.
 - `shortcut` toggles the panel with Control or Command held: `shortcut="b"` for ⌘B and Ctrl+B.
+- `resizable` lets a person drag the panel's rail, or focus it and press the arrow keys, to set the
+  panel's width. The width a person sets replaces `width`. The panel is at most half the window wide
+  unless `maxSize` states another limit, so a width kept from a wide screen fits a narrow one.
+  `size` and `onSizeChange` control the width, for an application that keeps it. While a drag runs,
+  the root has `data-resizing`: the panels stop their transitions, and the resize cursor shows over
+  the whole shell.
 - A panel over the page starts closed, and closes again every time the shell narrows. It is a raised
   surface, `bg.panel` with the `lg` shadow, and keeps its width while it slides closed. An
-  application that passes `open` controls the panel at every width.
+  application's `open` and `onOpenChange` apply while the panel is beside the page, so a stored
+  choice never opens a sheet over a phone's page.
 - While a panel is over the page, the bars, the main region and the other panels are inert, focus
   moves into the panel, and Escape or a press on the backdrop closes it and returns focus to the
   control that opened it. The panel has no dialog role, because the inert page and the returned
   focus give a reader the same behaviour.
 
+### Panes
+
+`AppShell.Pane` is a column in the body for bars that span the page alone. Render the header, the
+main region and the footer inside it, after the panels at the start and before those at the end, and
+the panels run the full height of the body beside the bars.
+
+```tsx
+<AppShell.Root variant="inset">
+  <AppShell.Body>
+    <AppShell.Navbar folds="hide" name="apps" width="4rem">
+      …
+    </AppShell.Navbar>
+    <AppShell.Navbar name="sections" resizable>
+      …
+    </AppShell.Navbar>
+    <AppShell.Rail panel="sections" resizeLabel="Resize the settings" />
+    <AppShell.Pane>
+      <AppShell.Header>…</AppShell.Header>
+      <AppShell.Main>…</AppShell.Main>
+      <AppShell.Footer when="narrow">…</AppShell.Footer>
+    </AppShell.Pane>
+  </AppShell.Body>
+</AppShell.Root>
+```
+
+- A header in a pane is outside the main region, so it is the `banner` landmark, and the main
+  region's scroll bar starts under it.
+- Under `scroll="window"` a pinned bar in a pane sticks under the root's pinned bars, and the panels
+  stick under the root's bars alone. A page's sticky bands stick under both.
+- `variant="inset"` gives the pane the main region's card, so the bars in the pane are on the card.
+
 ### Triggers, the rail and hooks
 
 `AppShell.Trigger` renders the library's button, a neutral ghost unless the caller states another
 look. It finds its panel by the name passed as `panel`, `navbar` by default, and sets
 `aria-controls`, `aria-expanded` and `data-state` from it, with no pressed fill. It does not render
-while its panel is under the page, because that panel is always shown. Name the trigger for the
-panel, such as `Navigation`, so a screen reader announces "Navigation, collapsed, button".
+while its panel is under the page or out of the shell, because nothing it does can show or hide that
+panel. Name the trigger for the panel, such as `Navigation`, so a screen reader announces
+"Navigation, collapsed, button".
 
 `AppShell.Rail` is a 24px strip on the edge between a panel and the page, with a 2px line under the
-pointer and on focus. Render it after the navbar or before an aside, and name it with `openLabel`
-and `closeLabel`. It is not in the tab order, because the trigger and the shortcut open and close
-the same panel. It does not render while its panel is over or under the page, and the recipe hides
-it under a coarse pointer.
+pointer and on focus. Render it after the navbar or before an aside. It does not render while its
+panel is over or under the page or out of the shell, and the recipe hides it under a coarse pointer.
+
+- Beside a panel that is not resizable the rail is a button named by `openLabel` and `closeLabel`.
+  It is not in the tab order, because the trigger and the shortcut open and close the same panel.
+- Beside a resizable panel the rail is the panel's `separator`, named by `resizeLabel`, `Resize` by
+  default, with a tab stop, as the WAI-ARIA window splitter pattern requires. Its value is the
+  panel's width in pixels. The arrows move it by 10px and by 50px with Shift, Home and End move it
+  to `minSize` and `maxSize`, and Enter and a press close and open the panel. A drag starts once the
+  pointer has moved 3px, and Escape during a drag returns the width the drag started at. Resizing a
+  closed panel opens it at the new width.
 
 `useAppShellPanel(name)` reads a panel from an application's own code, for example to close the
 navigation when a destination is pressed:
@@ -328,6 +400,8 @@ The recipe has no axes.
   distance from the pointer to the panel's edge, and `allowOverflow={false}` keeps it inside.
 - A controlled panel remains open until `open` turns false. The trigger, the close trigger and
   Escape call `onOpenChange` with `{ open: false }`.
+- A closing panel plays its exit motion where it is. Each open starts from the position and the size
+  of the first open, unless `persistRect` keeps those the panel closed at.
 - The positioner is fixed to the window at the `banner` layer plus the panel's place among the open
   panels: above the page's sticky bands, and under a backdrop, a dialog, a popover, a toast and a
   tooltip. Render it in a portal. A press or focus inside a panel brings it in front, and Escape
@@ -389,13 +463,13 @@ The panel does not offer these:
   the panel remains inside a boundary that does not scroll with the page, such as an app shell's
   main region, and leaves one that does.
 
-A menu, a select or a combobox opened inside the panel stacks at the `dropdown` layer, under the
-panel.
+A menu, a select, a combobox or a date picker opened inside the panel stacks at the `popover` layer,
+over the panel.
 
 ## Page
 
 Lays out a page as a column of bands: a banner, a header, a navigation, a toolbar, a body with an
-optional aside, and a footer.
+optional sidebar and aside, and a footer.
 
 ```tsx
 import { Page } from "@stealthscale/component-screen";
@@ -483,6 +557,43 @@ nearest item replaces the trail, with `backIcon` before its words.
   the query matches no tab.
 - `Page.Picker` and `Page.Palette` are that button and its panel, for a caller that composes its own
   picker: `<Menu.Trigger as={Page.Picker}>`, and the menu's content rendered as `Page.Palette`.
+- `Page.Tabs` is the slot for the disclosure package's `Tabs.List`, rendered with `as`, where the
+  caller's tabs root also contains the panels. In `Page.Nav` its strip starts at the gutter and its
+  tabs take the sizes of `Page.TabList`'s, and the band's hairline replaces the strip's own.
+
+### Sidebar
+
+`Page.Sidebar` renders the page's own destinations at the start of the body, a level below the
+shell's sidebar: the child pages of a route, or the sections of a settings page. Render a `nav`
+named by `aria-label` with a navigation list in it.
+
+```tsx
+<Page.Sidebar
+  current="Members"
+  label="Settings sections"
+  pickerIcon={<ChevronDownIcon />}
+  resizable
+>
+  <nav aria-label="Settings sections">
+    <NavList.Root>…</NavList.Root>
+  </nav>
+</Page.Sidebar>
+```
+
+- From the `md` breakpoint of the page's own width the sidebar is a column beside the body, as wide
+  as `sizes.sidebar`. The column starts at the gutter, so the fills of its rows start where the
+  title starts.
+- On a narrower page a `Page.Picker` above the body replaces the column, with `current` as its
+  words, `label` where `current` is left out, and `pickerIcon` at its end. It opens the column's
+  content in a `Page.Palette` named by `label`, and a press on a link in the panel closes it.
+- `sticky` keeps the column in view under the shell's pinned bars and the page's sticky bands, at
+  most as tall as the room they leave, and renders its content in the primitives package's scroll
+  area.
+- `resizable` renders a `separator` on the column's end edge, named by `resizeLabel`, `Resize` by
+  default, with the keys and the drag of a resizable shell panel. `size`, `defaultSize`,
+  `onSizeChange`, `minSize` and `maxSize` take pixels, as a panel's do.
+- A page with a sidebar and an aside lays the three out in one row from the `lg` breakpoint, and
+  stacks the aside under the body below it.
 
 ## Section
 
@@ -605,6 +716,8 @@ before the query.
   while a query is active. Put it in the scope the search filters, and name what was searched:
   `No pages match`.
 - With children, `Sidebar.Search` contains the caller's field, and the caller filters the rows.
+- The search is a landmark in the `search` role, named like its field, so a search in the sidebar's
+  header is inside a landmark. Give each search on a page its own `aria-label`.
 
 ### In an app shell
 
@@ -729,7 +842,11 @@ import { Switcher } from "@stealthscale/component-screen";
   closed to icons it is its mark alone, a 32px square at `md`, with its name in a tooltip, and its
   menu opens beside the rail.
 - Alone and in a toolbar the switcher is one line as wide as its words, at least as tall as a button
-  of its size. In a narrow toolbar a switcher with a mark hides its name.
+  of its size. In a narrow toolbar a switcher with a mark is its mark alone, a square as tall as a
+  button of its size.
+- A narrow toolbar without room for a switcher with `items` moves it into the toolbar's menu. Its
+  row there shows `label` with the current name under it, and `indicator`, and it opens the choices
+  in a submenu. A switcher composed from parts keeps its place.
 - The looks and the palettes are the button's. The outline look has the button's light edge.
 - Render the menu's positioner in a `Portal` when the switcher is inside an element that clips, such
   as an app shell panel, so the menu renders over the page.
@@ -753,6 +870,37 @@ the menu's own:
 </Switcher.Root>
 ```
 
+## LocaleSwitcher and ThemeSwitcher
+
+`@stealthscale/component-screen/shell` exports the switchers of what an application's shell
+provides. Each renders `Switcher.Root` with a row per choice on offer, so the switcher's axes and
+the menu's keys apply to it.
+
+```tsx
+import { LocaleSwitcher, ThemeSwitcher } from "@stealthscale/component-screen/shell";
+
+<Toolbar.End>
+  <LocaleSwitcher checkIcon={<CheckIcon />} indicator={<ChevronsUpDownIcon />} />
+  <ThemeSwitcher checkIcon={<CheckIcon />} indicator={<ChevronsUpDownIcon />} />
+</Toolbar.End>;
+```
+
+- `LocaleSwitcher` reads `useLocale` from `@stealthscale/provider-locale`. Each row shows its
+  language's name in that language, `Nederlands` for `nl`, with the language subtag in capitals as
+  its mark. A pick sets the locale, so the page is translated, and a language written right to left
+  mirrors the page. The control is named `Language` unless `label` names it otherwise.
+- `ThemeSwitcher` reads `useThemeChoice` from `@stealthscale/provider-shell`. Each row shows the
+  theme's name with a swatch of its primary colour, which the swatch resolves in its own theme
+  through `data-theme`. A pick sets the shell's theme, and the shell keeps the choice under the
+  application's name. The control is named `Theme` unless `label` names it otherwise.
+- Each takes every prop of `Switcher.Root` except the choices and the value: `checkIcon`,
+  `indicator`, `variant`, `palette`, `size`, `placement`, `positioning`, and `Switcher.Action` rows
+  as children.
+- Each renders only where the application offers two choices or more.
+- `useLocale` throws outside a `LocaleProvider`, and outside a `Shell` the theme choice offers no
+  theme.
+- The locale switcher does not mark a change in progress, which `useLocale().isPending` reports.
+
 ## Toolbar
 
 Renders a row of controls over a table or a list: a band at each end, a band in the middle, and a
@@ -763,6 +911,7 @@ import { Toolbar } from "@stealthscale/component-screen";
 
 <Toolbar.Root aria-label="Invoices" more="More actions" moreIcon={<EllipsisIcon />}>
   <Toolbar.Start>
+    <Toolbar.Title>Invoices</Toolbar.Title>
     <Toolbar.Link current href="/invoices/drafts">
       Drafts
     </Toolbar.Link>
@@ -789,8 +938,16 @@ import { Toolbar } from "@stealthscale/component-screen";
 
 - The row has `role="toolbar"`, and the arrow keys move focus between its controls, so the row is
   one tab stop. Name it with `aria-label`.
-- The row measures its own width and writes `data-narrow` below `sm`. Its gap is the gap token of
-  its size, and every library button in it renders at its size.
+- The row folds its controls and writes `data-narrow` below `sm` of its own width, and while its
+  controls need more room than it has. Its gap is the gap token of its size, and every library
+  button in it renders at its size.
+- A folded row that still has no room moves a secondary `Toolbar.Action`, a secondary `Toolbar.Link`
+  and a switcher into its menu, the one nearest its end first. `Toolbar.Item` and `Toolbar.Search`
+  keep their place, because they have no row in a menu.
+- `Toolbar.Title` renders the row's title, a name or a brand, in semibold with twice the row's gap
+  after it, so the control after it reads as the row's first control and not as part of the title. A
+  narrow row keeps it with the row's gap alone, because the row folds the controls the wider gap
+  sets apart. A link inside it renders as a `Toolbar.Item`, one of the row's controls.
 - `Toolbar.Action` renders the library's button, `ghost`, or `solid` with `primary`, and folds by
   its priority.
 - `Toolbar.Link` renders an `a` in the same look with `href`, `current` and `icon`. `current` sets