@parallelworks/ui 0.92.0 → 0.94.0

package/README.md

@@ -8,6 +8,7 @@ so an application ships only what it imports:
 | `.` | theme contract, primitives (buttons, inputs, tables, tooltips, modals, dropdowns, settings layouts, page header), `UIProvider` |
 | `./theme` | theme seeds and presets, `generateTheme`, `applyTheme`, `fitSeed` |
 | `./icons` | the icon barrel |
+| `./app-frame` | inset application frame, resizable navigation, icon rail, and mobile drawer |
 | `./list` | list pages, tables, row menus and list controls |
 | `./form` | `DynamicForm` and its field registry |
 | `./graph` | job dependency graph and tree view, and the visual workflow editor: the graph, the run form as an inputs editor, and their dialogs |
@@ -16,7 +17,7 @@ so an application ships only what it imports:
 | `./file-explorer` | object storage explorer over a host-supplied provider |
 | `./access` | `AccessDrawer`: who has access to a resource, and granting roles to people and groups |
 | `./ai`, `./ai/openai`, `./ai/mock` | chat interface and adapters |
-| `./theme.css`, `./base.css`, `./fonts.css`, `./styles.css`, `./logviewer.css`, `./ai.css` | stylesheets |
+| `./theme.css`, `./base.css`, `./fonts.css`, `./styles.css`, `./logviewer.css`, `./ai.css`, `./app-frame.css` | stylesheets |
 
 Hosts bind strings, navigation, data hooks and the workflow engine through
 `UIProvider`, which also shows the package's toasts:
@@ -227,6 +228,14 @@ A page declares its header in one place, and the shell shows it:
   such as a log's follow and refresh: its buttons are outlined, and `primary`
   fills the one, if any, the panel leads to.
   **`toolbar`** is a row under the bar, such as tabs or a time range.
+- A list's controls may sit in **`actions`**: a `ListToolbar` there, with its
+  filter, display options and search, leaves the list's count under its rows.
+  Where its search field, opened, wouldn't fit beside the trail, as on a phone,
+  the open search takes the whole bar until it closes; the rest of the bar
+  stays as it was underneath, hidden and `inert`, and focus returns to the
+  search button. While a search term narrows the list with the field closed,
+  the button shows a dot and its name says so (`searchActive`). Nothing to set
+  up: the bar measures it.
 - **`hidden`** takes the bar away while the page is mounted, for a page that
   fills the window.
 
@@ -1245,3 +1254,75 @@ colors and sizing can obscure labels or make controls hard to use. Keep trusted
 confirmation summaries, permissions, and security notices outside the authored
 layout. Full stylesheets or mutually untrusted embedded applications require a
 separate isolation design.
+
+## Application frame
+
+`AppFrame` provides a sidebar and an inset content surface. The sidebar collapses
+to a 64px icon rail, resizes with a pointer or keyboard, and becomes a modal
+navigation drawer below 768px. Its header, scrolling navigation, and footer stay
+separate from the page's scrolling content. Long navigation labels truncate within
+the current sidebar width; badges remain visible. Navigation scrollbar tracks stay
+hidden while wheel and keyboard scrolling keep destinations reachable in short
+containers.
+
+```tsx
+import { AppFrame, AppFrameNavItem, AppFrameToggle } from '@parallelworks/ui/app-frame'
+import '@parallelworks/ui/app-frame.css'
+
+<AppFrame
+  navigationKey={pathname}
+  brand={({ expanded }) => expanded ? <Wordmark /> : <Mark />}
+  navigation={
+    <nav aria-label="Main navigation">
+      <AppFrameNavItem label="Projects" icon={<ProjectsIcon />} href="/projects" selected />
+    </nav>
+  }
+  footer={({ isMobile }) => !isMobile && <AppFrameToggle />}
+  header={<PageTools />}
+>
+  <ProjectList />
+</AppFrame>
+```
+
+`PageTools` can use `useAppFrame().isMobile` to show an `AppFrameToggle` on small
+screens. The drawer supplies its own close button, traps focus, closes on Escape
+or an outside click, and returns focus to its opener. Navigation items close it
+on an ordinary click; modified links keep the current view in place. A changed
+`navigationKey` also dismisses it.
+Reopening mobile navigation restores its scroll position within the current
+section. Closing it unmounts its contents, including any nested popups.
+Use `navigationResetKey` for a section identifier when navigation scroll should
+survive route changes within that section. It defaults to `navigationKey`.
+`sidebarProps` passes host attributes, styling, and events to the desktop sidebar
+and mobile dialog, for example a navigation context menu. The frame retains its
+own layout, dialog semantics, and measured width.
+
+The host owns routing, persistence, identity, permissions, and page tools. Links
+use `UIProvider`'s link slot. Pass `expanded`/`onExpandedChange` and
+`width`/`onWidthChange` to persist preferences, or use the uncontrolled defaults.
+Pointer drags preview their width locally and call `onWidthChange` once when the
+gesture ends, so persistence does not run on every pointer movement.
+`defaultWidth` is 240, bounded by `minWidth` (200) and `maxWidth` (400); compact
+applications can choose smaller bounds. The resize handle supports arrows, Home,
+End, drag-to-collapse, and double-click to restore `defaultWidth`. Logical layout
+and resizing support right-to-left direction. Reduced motion disables resizing
+and drawer transitions. `resizable={false}` removes the handle.
+
+`brand`, `navigation`, and `footer` accept nodes or functions receiving the frame
+state. `header` sits above the main content; `banner` spans both columns.
+`fullBleed` removes the 8px inset and 12px rounded border. The frame fills the
+viewport by default; pass `style={{ height: '100%' }}` for a bounded container.
+The mobile drawer stays inside the frame, below its banner, and uses the chosen
+sidebar width, capped to leave 48px for dismissal. It slides from the navigation
+edge while the backdrop fades; both finish in 200ms and respect reduced motion.
+
+The five `--theme-sidebar-*` tokens produced by `generateTheme` style navigation:
+`bg`, `text`, `hover`, `active-bg`, and `active-text`. Without them the frame uses
+the ordinary surface and accent tokens. Content uses `--theme-app-bg` and
+`--theme-border`. Supply translated `labels` for navigation, skip, open, close,
+expand, collapse, and resize actions. The frame owns the main landmark and skip
+link; put page content inside it without nesting a second `<main>`.
+
+Frame styles use the `pw-ui` cascade layer. Put broad host element defaults
+(such as anchor colors and scrollbar styling) in a lower-priority layer declared
+before the package styles, so they do not replace navigation states.

package/dist/app-frame/app-frame.css

@@ -0,0 +1,281 @@
+@layer pw-ui {
+  /* The frame uses the same sidebar tokens as the theme generator. */
+  .pw-app-frame {
+    display: flex;
+    flex-direction: column;
+    height: 100dvh;
+    min-height: 0;
+    isolation: isolate;
+    background: var(--theme-sidebar-bg, var(--theme-muted-panel-bg));
+    color: var(--theme-app);
+  }
+  .pw-frame-body {
+    display: flex;
+    flex: 1;
+    min-height: 0;
+    position: relative;
+    overflow: hidden;
+  }
+  .pw-frame-sidebar,
+  .pw-frame-drawer {
+    display: flex;
+    flex-direction: column;
+    flex-shrink: 0;
+    min-height: 0;
+    background: var(--theme-sidebar-bg, var(--theme-muted-panel-bg));
+    color: var(--theme-sidebar-text, var(--theme-app));
+  }
+  .pw-frame-sidebar {
+    position: relative;
+    transition: width 200ms cubic-bezier(0.25, 0.1, 0.25, 1);
+  }
+  .pw-frame-sidebar[data-resizing] {
+    transition: none;
+    user-select: none;
+  }
+  .pw-frame-brand {
+    padding: 12px 12px 4px;
+    flex-shrink: 0;
+    min-width: 0;
+    overflow: hidden;
+  }
+  .pw-frame-links {
+    flex: 1;
+    overflow-x: hidden;
+    overflow-y: auto;
+    padding: 12px;
+    min-width: 0;
+    min-height: 0;
+    scrollbar-width: none;
+  }
+  .pw-frame-links::-webkit-scrollbar {
+    display: none;
+  }
+  .pw-frame-links nav {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: 4px;
+  }
+  .pw-frame-footer {
+    flex-shrink: 0;
+    padding: 8px 12px;
+  }
+  .pw-frame-nav-item {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    min-height: 36px;
+    min-width: 0;
+    width: 100%;
+    border: 0;
+    border-radius: 8px;
+    padding: 8px;
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    font-size: 14px;
+    font-weight: 500;
+    line-height: 20px;
+    cursor: pointer;
+    text-decoration: none;
+    text-align: start;
+    transition: background-color 150ms ease-out;
+  }
+  .pw-frame-nav-item:hover,
+  .pw-frame-toggle:hover {
+    background: var(--theme-sidebar-hover, var(--theme-hover));
+  }
+  .pw-frame-nav-item[aria-current] {
+    background: var(--theme-sidebar-active-bg, var(--theme-accent-subtle));
+    color: var(--theme-sidebar-active-text, var(--theme-accent));
+  }
+  .pw-frame-nav-item:is(:disabled, [aria-disabled]) {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+  .pw-frame-nav-icon {
+    display: flex;
+    flex: 0 0 18px;
+    align-items: center;
+    justify-content: center;
+  }
+  .pw-frame-nav-icon svg {
+    width: 18px;
+    height: 18px;
+  }
+  .pw-frame-nav-label {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .pw-frame-nav-badge {
+    flex-shrink: 0;
+    font-size: 12px;
+    font-variant-numeric: tabular-nums;
+  }
+  [data-sidebar-mode="rail"] .pw-frame-nav-item {
+    padding-inline: 0;
+    justify-content: center;
+    height: 40px;
+  }
+  .pw-frame-toggle {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 36px;
+    height: 36px;
+    border: 0;
+    border-radius: 8px;
+    padding: 0;
+    color: inherit;
+    background: transparent;
+    cursor: pointer;
+    flex-shrink: 0;
+  }
+  .pw-frame-toggle svg {
+    width: 18px;
+    height: 18px;
+  }
+  .pw-frame-sidebar :focus-visible,
+  .pw-frame-drawer :focus-visible {
+    outline: 2px solid currentColor;
+    outline-offset: 2px;
+  }
+  .pw-frame-resize {
+    position: absolute;
+    z-index: 1;
+    inset-block: 0;
+    inset-inline-end: -4px;
+    width: 8px;
+    cursor: col-resize;
+    touch-action: none;
+  }
+  .pw-frame-resize::after {
+    content: "";
+    position: absolute;
+    inset-block: 8px;
+    inset-inline-start: 3px;
+    width: 2px;
+    border-radius: 2px;
+  }
+  .pw-frame-resize:hover::after,
+  .pw-frame-resize:focus-visible::after {
+    background: var(--theme-sidebar-text, var(--theme-accent));
+    opacity: 0.5;
+  }
+  .pw-frame-surface-wrap {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    min-height: 0;
+    padding: 8px;
+    padding-inline-start: 0;
+  }
+  .pw-frame-surface {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    min-height: 0;
+    overflow: hidden;
+    isolation: isolate;
+    border: 1px solid var(--theme-border);
+    border-radius: 12px;
+    background: var(--theme-app-bg);
+    background-clip: padding-box;
+  }
+  .pw-frame-header,
+  .pw-frame-banner {
+    flex-shrink: 0;
+  }
+  .pw-frame-main {
+    flex: 1;
+    min-width: 0;
+    min-height: 0;
+    overflow: auto;
+  }
+  .pw-app-frame[data-full-bleed] .pw-frame-surface-wrap {
+    padding: 0;
+  }
+  .pw-app-frame[data-full-bleed] .pw-frame-surface {
+    border: 0;
+    border-radius: 0;
+  }
+  .pw-app-frame[data-mobile] .pw-frame-surface-wrap {
+    padding: 8px;
+  }
+  .pw-app-frame[data-mobile][data-full-bleed] .pw-frame-surface-wrap {
+    padding: 0;
+  }
+  .pw-frame-backdrop {
+    position: absolute;
+    inset: 0;
+    z-index: var(--layer-drawer, 1100);
+    background: var(--theme-backdrop, rgb(0 0 0 / 0.35));
+    transition: opacity 200ms cubic-bezier(0.25, 0.1, 0.25, 1);
+  }
+  .pw-frame-backdrop[data-starting-style],
+  .pw-frame-backdrop[data-ending-style] {
+    opacity: 0;
+  }
+  .pw-frame-drawer {
+    position: absolute;
+    inset-block: 8px;
+    inset-inline-start: 8px;
+    max-width: calc(100% - 48px);
+    z-index: var(--layer-drawer, 1100);
+    border-radius: 12px;
+    box-shadow: 0 12px 32px rgb(0 0 0 / 0.2);
+    outline: none;
+    transform: translateX(0);
+    transition: transform 200ms cubic-bezier(0.25, 0.1, 0.25, 1);
+  }
+  .pw-frame-drawer[data-starting-style],
+  .pw-frame-drawer[data-ending-style] {
+    transform: translateX(calc(-100% - 16px));
+  }
+  .pw-frame-drawer:dir(rtl)[data-starting-style],
+  .pw-frame-drawer:dir(rtl)[data-ending-style] {
+    transform: translateX(calc(100% + 16px));
+  }
+  .pw-frame-mobile-close {
+    display: flex;
+    justify-content: flex-end;
+    padding: 4px 4px 0;
+  }
+  .pw-frame-drawer .pw-frame-brand {
+    padding-top: 0;
+  }
+  .pw-frame-drawer .pw-frame-nav-item,
+  .pw-app-frame[data-mobile] .pw-frame-toggle {
+    min-height: 44px;
+  }
+  .pw-app-frame[data-mobile] .pw-frame-toggle {
+    width: 44px;
+    height: 44px;
+  }
+  .pw-frame-skip {
+    position: fixed;
+    inset-block-start: -100px;
+    inset-inline-start: 8px;
+    padding: 8px 16px;
+    border-radius: 6px;
+    background: var(--theme-panel-bg);
+    color: var(--theme-app);
+    z-index: var(--layer-popover, 1400);
+  }
+  .pw-frame-skip:focus {
+    inset-block-start: 8px;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .pw-frame-sidebar,
+    .pw-frame-backdrop,
+    .pw-frame-drawer,
+    .pw-frame-nav-item {
+      transition: none;
+    }
+  }
+}

package/dist/app-frame/index.d.ts

@@ -0,0 +1,73 @@
+import { type HTMLAttributes, type MouseEvent, type ReactNode } from 'react';
+import { type LinkTarget } from '../components/AppLink.js';
+export interface AppFrameLabels {
+    navigation: string;
+    skipToContent: string;
+    openNavigation: string;
+    closeNavigation: string;
+    expandSidebar: string;
+    collapseSidebar: string;
+    resizeSidebar: string;
+}
+export interface AppFrameState {
+    /** Labels stay visible in the mobile drawer even when the desktop rail is collapsed. */
+    expanded: boolean;
+    isMobile: boolean;
+    mobileOpen: boolean;
+    toggle: () => void;
+    closeNavigation: () => void;
+}
+export declare function useAppFrame(): AppFrameState;
+type Slot = ReactNode | ((state: AppFrameState) => ReactNode);
+export interface AppFrameProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    children: ReactNode;
+    /** Identity at the top of navigation. Render a compact mark when expanded is false. */
+    brand?: Slot;
+    navigation: Slot;
+    footer?: Slot;
+    /** Page tools above the independently scrolling main content. */
+    header?: ReactNode;
+    /** Optional notice above both navigation and content. */
+    banner?: ReactNode;
+    expanded?: boolean;
+    defaultExpanded?: boolean;
+    onExpandedChange?: (expanded: boolean) => void;
+    width?: number;
+    defaultWidth?: number;
+    /** Commits once when a drag ends, and on each keyboard or reset action. */
+    onWidthChange?: (width: number) => void;
+    minWidth?: number;
+    maxWidth?: number;
+    railWidth?: number;
+    resizable?: boolean;
+    /** Viewport width below which navigation becomes a modal drawer. */
+    mobileBreakpoint?: number;
+    /** A changed route key closes mobile navigation. */
+    navigationKey?: string;
+    /** Reset navigation scroll only when this section changes; defaults to navigationKey. */
+    navigationResetKey?: string;
+    /** Attributes shared by desktop navigation and the mobile dialog. */
+    sidebarProps?: HTMLAttributes<HTMLElement>;
+    /** Removes the inset and border around content. */
+    fullBleed?: boolean;
+    labels?: Partial<AppFrameLabels>;
+    mainId?: string;
+    mainClassName?: string;
+}
+/** An inset application surface beside a resizable icon rail or navigation column.
+ * Router, identity, persistence and permissions belong to the host. Import app-frame.css. */
+export declare function AppFrame({ children, brand, navigation, footer, header, banner, expanded: controlledExpanded, defaultExpanded, onExpandedChange, width: controlledWidth, defaultWidth, onWidthChange, minWidth, maxWidth, railWidth, resizable, mobileBreakpoint, navigationKey, navigationResetKey, sidebarProps, fullBleed, labels: labelOverrides, mainId: suppliedMainId, mainClassName, className, style, ...props }: AppFrameProps): import("react").JSX.Element;
+/** Put in the page header on mobile, and the sidebar footer on desktop. */
+export declare function AppFrameToggle({ className, ...props }: Omit<HTMLAttributes<HTMLButtonElement>, 'children'>): import("react").JSX.Element;
+export interface AppFrameNavItemProps extends LinkTarget {
+    label: string;
+    icon: ReactNode;
+    selected?: boolean;
+    badge?: ReactNode;
+    disabled?: boolean;
+    onClick?: (event: MouseEvent<HTMLElement>) => void;
+    className?: string;
+}
+/** Router-aware navigation that keeps icon-only rail items named and discoverable. */
+export declare function AppFrameNavItem({ label, icon, selected, badge, disabled, onClick, className, ...target }: AppFrameNavItemProps): import("react").JSX.Element;
+export {};