@moldable-ai/ui 0.2.25 → 0.2.29

package/src/components/ui/toolbar-controls.md

@@ -0,0 +1,75 @@
+# Toolbar controls
+
+Precomposed controls for native-window-aware `Toolbar` chrome. They use
+Moldable semantic tokens, density, menus, and accessibility behavior while
+keeping app toolbars visually consistent.
+
+```tsx
+<Toolbar position="top">
+  <ToolbarSidebarToggle
+    expanded={sidebarOpen}
+    onExpandedChange={setSidebarOpen}
+  />
+  <ToolbarBackButton onClick={goBack} />
+  <ToolbarTitleField value={title} onChange={rename} />
+  <ToolbarActions>
+    <ToolbarControlGroup aria-label="History">
+      <ToolbarIconButton label="Undo" onClick={undo}>
+        <Undo2 />
+      </ToolbarIconButton>
+      <ToolbarControlSeparator />
+      <ToolbarIconButton label="Redo" onClick={redo}>
+        <Redo2 />
+      </ToolbarIconButton>
+    </ToolbarControlGroup>
+    <ToolbarOverflowMenu
+      items={[
+        { id: 'history', label: 'Version history' },
+        { id: 'export', label: 'Export' },
+      ]}
+      onSelectItem={handleMoreAction}
+    />
+    <ToolbarButton variant="default">Present</ToolbarButton>
+  </ToolbarActions>
+</Toolbar>
+```
+
+## Components
+
+- `ToolbarButton` — text or mixed-content action. Defaults to 36px native
+  chrome; use `variant="default"` for the one primary action.
+- `ToolbarIconButton` — required accessible label and optional tooltip.
+- `ToolbarBackButton` — single chevron Back affordance for root-to-detail
+  navigation.
+- `ToolbarSidebarToggle` — controlled sidebar visibility button with accurate
+  pressed state and dynamic label.
+- `ToolbarOverflowMenu` — an ellipsis button backed by Moldable's declarative
+  menu API, including the native host menu when available.
+- `ToolbarControlGroup` — a shared surface for closely related actions such as
+  Undo/Redo. Children automatically become compact quiet controls.
+- `ToolbarControlSeparator` — divider within a related action group.
+- `ToolbarTitleField` — an accessible, inline-editable contextual title.
+
+`ToolbarButton` and `ToolbarIconButton` accept `appearance="quiet"` when a
+standalone action should not have raised chrome. The default `chrome`
+appearance uses the `toolbar` Button variant and these semantic tokens:
+
+- `--toolbar-control-background`
+- `--toolbar-control-hover`
+- `--toolbar-control-pressed`
+- `--toolbar-control-border`
+- `--toolbar-control-shadow`
+
+The tokens adapt to light/dark appearance, increased contrast, and reduced
+transparency.
+
+## Composition rules
+
+- Keep the current document or view title leading and the primary action last.
+- Prefer icon-only secondary controls and a text-only primary action.
+- Put only genuinely related commands in `ToolbarControlGroup`.
+- Move low-frequency commands such as history, duplicate, export, and delete
+  into `ToolbarOverflowMenu`.
+- Keep roughly five or six visible actions. Tooltips do not replace accessible
+  labels.
+- Use the shared Back and Sidebar controls instead of hand-building arrows.

package/src/components/ui/toolbar.md

@@ -1,6 +1,9 @@
 # Toolbar
 
-Compact pane chrome for context and actions.
+Native-window-aware toolbar chrome for context and actions. A top toolbar is
+draggable and automatically clears the host-advertised traffic-light lane when
+the app owns its titlebar. The same component remains compact pane chrome in an
+embedded view.
 
 ```tsx
 <Toolbar position="top">
@@ -20,7 +23,23 @@ Use one toolbar per pane. Put the current context before actions and keep one
 clear primary action. Toolbars are not marketing headers. Icon-only actions
 need labels and tooltips.
 
+`ToolbarTitle` names the current view or document, not the app itself. Omit it
+when there is no useful view context; the remaining toolbar still provides a
+drag surface and a safe home for right-aligned actions.
+
+The `inset` prop defaults to `auto`. Use `none` for a top toolbar that is not
+window chrome, `windowControls` to force the standard control lane, or
+`windowControlsAndButton` when another leading control sits beside the native
+traffic lights. Set `draggable={false}` only for top toolbars that are nested
+inside app content.
+
 The default toolbar uses `material="regular"`. The `plain` and `panel` variants
 default to `material="none"`; pass a material explicitly only when the toolbar
 actually floats over content. Reserve `material="clear"` for compact controls
 over media or a richly colored canvas.
+
+Use the precomposed controls in
+[`toolbar-controls.md`](./toolbar-controls.md) for native-sized Back, Sidebar,
+Overflow, grouped-action, and editable-title behavior. Keep only closely
+related actions in a shared group; a single capsule containing every command
+does not communicate command hierarchy.

package/src/styles/index.css

@@ -268,6 +268,10 @@
   --color-control-disabled: var(--control-disabled);
   --color-control-focus: var(--control-focus);
   --color-control-invalid: var(--control-invalid);
+  --color-toolbar-control: var(--toolbar-control-background);
+  --color-toolbar-control-hover: var(--toolbar-control-hover);
+  --color-toolbar-control-pressed: var(--toolbar-control-pressed);
+  --color-toolbar-control-border: var(--toolbar-control-border);
   --color-window-chrome: var(--window-chrome-background);
   --color-window-chrome-foreground: var(--window-chrome-foreground);
   --color-window-chrome-muted: var(--window-chrome-muted-foreground);
@@ -851,6 +855,29 @@
   );
   --control-focus: var(--ring);
   --control-invalid: var(--destructive);
+  --toolbar-control-background: color-mix(
+    in oklch,
+    var(--background) 74%,
+    transparent
+  );
+  --toolbar-control-hover: color-mix(
+    in oklch,
+    var(--background) 84%,
+    var(--foreground) 8%
+  );
+  --toolbar-control-pressed: color-mix(
+    in oklch,
+    var(--background) 74%,
+    var(--foreground) 14%
+  );
+  --toolbar-control-border: color-mix(
+    in oklch,
+    var(--foreground) 11%,
+    transparent
+  );
+  --toolbar-control-shadow:
+    inset 0 1px 0 color-mix(in oklch, white 42%, transparent),
+    0 1px 2px oklch(0.15 0.005 285 / 8%);
 
   --material-blur-toolbar: 16px;
   --material-blur-overlay: 20px;
@@ -946,6 +973,32 @@
   --chat-safe-padding: 0px;
 }
 
+/*
+ * A top Toolbar becomes unified native window chrome only when the host gives
+ * the app ownership of the titlebar. Embedded views and ordinary pane
+ * toolbars retain their density-specific compact sizing.
+ */
+:root[data-moldable-display-mode='window'][data-moldable-window-titlebar='app']
+  [data-slot='toolbar'][data-position='top']:not([data-window-inset='none']) {
+  min-height: max(3.25rem, var(--window-titlebar-height, 0px));
+  padding-inline-start: max(
+    var(--density-control-padding-inline, 0.625rem),
+    var(--window-control-inset-inline-start, 0px)
+  );
+  padding-inline-end: max(
+    var(--density-control-padding-inline, 0.625rem),
+    var(--window-control-inset-inline-end, 0px)
+  );
+}
+
+:root[data-moldable-display-mode='window'][data-moldable-window-titlebar='app']
+  [data-slot='toolbar'][data-position='top'][data-window-inset='windowControlsAndButton'] {
+  padding-inline-start: max(
+    var(--density-control-padding-inline, 0.625rem),
+    calc(var(--window-control-inset-inline-start, 0px) + 2.75rem)
+  );
+}
+
 :where([data-density='compact']) {
   --density-control-height-xs: 1.375rem;
   --density-control-height-sm: 1.75rem;
@@ -1176,6 +1229,11 @@
     --control-disabled: transparent;
     --control-focus: Highlight;
     --control-invalid: Mark;
+    --toolbar-control-background: Canvas;
+    --toolbar-control-hover: Canvas;
+    --toolbar-control-pressed: Canvas;
+    --toolbar-control-border: ButtonBorder;
+    --toolbar-control-shadow: none;
     --material-regular-fill: Canvas;
     --material-regular-fallback: Canvas;
     --material-regular-border: ButtonBorder;
@@ -1201,6 +1259,10 @@
 :where([data-transparency='reduced']) {
   --surface-toolbar: var(--background);
   --surface-overlay: var(--popover);
+  --toolbar-control-background: var(--background);
+  --toolbar-control-hover: var(--accent);
+  --toolbar-control-pressed: var(--control-pressed);
+  --toolbar-control-shadow: inset 0 0 0 1px var(--separator);
   --material-regular-fill: var(--material-regular-fallback);
   --material-regular-blur: 0px;
   --material-regular-saturation: 1;
@@ -1216,6 +1278,10 @@
   :root {
     --surface-toolbar: var(--background);
     --surface-overlay: var(--popover);
+    --toolbar-control-background: var(--background);
+    --toolbar-control-hover: var(--accent);
+    --toolbar-control-pressed: var(--control-pressed);
+    --toolbar-control-shadow: inset 0 0 0 1px var(--separator);
     --material-regular-fill: var(--material-regular-fallback);
     --material-regular-blur: 0px;
     --material-regular-saturation: 1;