Merge remote-tracking branch 'origin/master' into xtr/sidebar-workspace-controls

packages/client/ui-settings-general/src/client/SettingsRoot.module.css

@@ -0,0 +1,226 @@
+/* Settings shell (figma 501:29904 mask context / 501:29947 panel): sidebar
+   foot trigger row + centered 1080x700 modal panel. The trigger uses the
+   sidebar's 34px compact row / 36px rail circle rhythm; the
+   panel is a two-column layout — 188px nav rail + content column with a
+   54px header and the 24px-padded options area. */
+
+/* Trigger row: match the other wide sidebar controls' compact vertical rhythm. */
+.trigger {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: calc(100% + 8px);
+  height: 34px;
+  margin: 4px -4px 4px;
+  padding: 6px 2px 6px 10px;
+  box-sizing: border-box;
+  border: none;
+  border-radius: 12px;
+  background: transparent;
+  cursor: pointer;
+  overflow: hidden;
+  color: var(--dsw-alias-label-primary);
+  font-family: inherit;
+  font-size: 14px;
+  line-height: 22px;
+}
+
+.trigger:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+/* Rail trigger: the same 36x36 circle box as the other rail controls. */
+.trigger.rail {
+  width: 36px;
+  height: 36px;
+  margin: 8px 0 10px;
+  justify-content: center;
+  gap: 0;
+  padding: 0;
+  border-radius: 50%;
+}
+
+.triggerLabel {
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+/* Full-viewport layer (figma Mask 501:29946 #000@24%): mask tokens match the
+   Modal primitive (--dsw-alias-bg-mask-1 + --dsw-mask-blur). */
+.overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.mask {
+  position: absolute;
+  inset: 0;
+  background: var(--dsw-alias-bg-mask-1);
+  backdrop-filter: var(--dsw-mask-blur);
+}
+
+/* Panel (figma Settings 501:29947): r24, white, lv3 shadow (figma effects
+   match --dsw-shadow-lv3 exactly); figma's 1080x700 is shrunk to 800 wide.
+   One height for every section, taken from the viewport rather than the
+   content: sections differ by hundreds of pixels (a settings list against the
+   composition editor), and a content-sized panel would resize under the
+   pointer on every nav click. Whatever does not fit scrolls in `.options`. */
+.panel {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  width: 800px;
+  height: min(800px, calc(100vh - 48px));
+  max-width: calc(100vw - 48px);
+  border-radius: 24px;
+  overflow: hidden;
+  background: var(--dsw-alias-bg-layer-2);
+  box-shadow: var(--dsw-shadow-lv3);
+  /* Elevated surface: the scrollbar thumb takes the l2 elevation tokens.
+     Declared on the panel rather than the scrolling `.options` child so the
+     elevation choice sits with the surface; the custom properties inherit
+     down to whichever descendant scrolls (see ui-theme
+     styles/scrollbar.css for the rebinding contract). */
+  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
+  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
+}
+
+/* Nav rail (figma .Setting-nav 501:29958): 188 wide, pad (12,22,12,0),
+   gap 18, no own fill — the panel white shows through. */
+.nav {
+  flex: none;
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+  width: 188px;
+  padding: 22px 12px 0;
+  box-sizing: border-box;
+}
+
+/* Title row (figma 501:29959): 16/500 lh24, 12px side padding. */
+.navTitle {
+  padding: 0 12px;
+  font-size: 16px;
+  line-height: 24px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-primary);
+}
+
+/* Cell stack (figma 501:29961): gap 4. */
+.navList {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+/* Nav cell (figma .Setting-nav-cell 501:29962): 164x40, r12, pad
+   (12,9,16,9), gap 8; label 14/400 lh22; selected fill #EBEEF2. */
+.navCell {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 40px;
+  padding: 9px 16px 9px 12px;
+  box-sizing: border-box;
+  border: none;
+  border-radius: 12px;
+  background: transparent;
+  cursor: pointer;
+  font-family: inherit;
+  font-size: 14px;
+  line-height: 22px;
+  font-weight: 400;
+  color: var(--dsw-alias-label-primary);
+  text-align: left;
+}
+
+.navCell:hover {
+  background: var(--dsw-specific-sidebar-nav-item-hover);
+}
+
+.navCell.active {
+  background: var(--dsw-specific-sidebar-nav-item-active);
+}
+
+.navIcon {
+  flex: none;
+}
+
+.navLabel {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+/* Content column (figma Content 501:29980): header + options. */
+.content {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+/* Header (figma .Header 501:29981): h54, pad (10,20,14,8), close right. */
+.header {
+  flex: none;
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 8px;
+  height: 54px;
+  padding: 20px 14px 8px 10px;
+  box-sizing: border-box;
+}
+
+.actions {
+  min-width: 0;
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 8px;
+  margin-left: auto;
+}
+
+/* Close button (figma .Icon_container 501:29982): 28x28, r28, 14px glyph. */
+.close {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  border: none;
+  border-radius: 28px;
+  background: transparent;
+  cursor: pointer;
+  color: var(--dsw-alias-label-primary);
+}
+
+.close:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+/* Options area (figma Options 501:29983): pad (24,0,24,24), scrolls. */
+.options {
+  flex: 1;
+  min-height: 0;
+  padding: 0 24px 24px;
+  overflow-y: auto;
+}
+
+/* Visually-hidden text seat (close button accessible name from slot content). */
+.hiddenLabel {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}

packages/client/ui-settings-general/src/client/SettingsRoot.tsx

@@ -0,0 +1,172 @@
+/**
+ * Settings shell root: the sidebar-foot trigger row plus the centered modal
+ * panel (figma 501:29947, 1080x700) with the section nav rail. The shell is
+ * a pure composition face — every piece of text (trigger label, panel title,
+ * close label, sections) arrives from registrants through slots; accessible
+ * names resolve to that content (trigger: its own text; dialog:
+ * aria-labelledby the title node; close: visually-hidden slot text). Modal
+ * open state and the active section id are component-local viewing state;
+ * the onboarding coordinator mounts exactly one ordered registrant while the
+ * sessions-derived empty-Hero fact is active — the takeover chrome
+ * (OnboardingSurface) belongs to the step, so a mounted-but-deciding step
+ * paints nothing here.
+ */
+import { useCallback, useEffect, useId, useRef, useState } from 'react'
+import clsx from 'clsx'
+import {
+  IconAgentPresetOutline16, IconCloseOutline16, IconDataOutline16, IconSettingsOutline16,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import type { SettingsRootComponentProps, SettingsSectionRow } from './shell-contract.ts'
+import css from './SettingsRoot.module.css'
+
+/** Nav glyph by section id; unknown ids fall back to the settings gear. */
+function navIcon(id: string) {
+  if (id === 'models') return <IconDataOutline16 className={css.navIcon} size={16} />
+  if (id === 'agent-presets') return <IconAgentPresetOutline16 className={css.navIcon} size={16} />
+  return <IconSettingsOutline16 className={css.navIcon} size={16} />
+}
+
+type PanelProps = {
+  rows: readonly SettingsSectionRow[]
+  renderSlot: SettingsRootComponentProps['renderSlot']
+  activeId: string | undefined
+  onSelect: (id: string) => void
+  onClose: () => void
+}
+
+/**
+ * The modal layer: full-viewport mask + centered panel. Close paths: the
+ * header button, a mask click, and document-level Escape (mounted only while
+ * open, so the listener lifetime is the panel's).
+ */
+function SettingsPanel({ rows, renderSlot, activeId, onSelect, onClose }: PanelProps) {
+  // Entries can unmount underneath the requested id, so the render-time
+  // projection falls back to the first row when the id is gone.
+  const active = rows.find(r => r.id === activeId)?.id ?? rows[0]?.id
+  const titleId = useId()
+
+  useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    document.addEventListener('keydown', onKeyDown)
+    return () => { document.removeEventListener('keydown', onKeyDown) }
+  }, [onClose])
+
+  // Baseline focus management: entering the dialog lands on the close button.
+  const closeButton = useRef<HTMLButtonElement | null>(null)
+  useEffect(() => { closeButton.current?.focus() }, [])
+
+  return (
+    <div className={css.overlay} role="presentation">
+      <div className={css.mask} aria-hidden="true" onClick={onClose} />
+      <div className={css.panel} role="dialog" aria-modal="true" aria-labelledby={titleId}>
+        <nav className={css.nav}>
+          <div className={css.navTitle} id={titleId}>{renderSlot('settings.header', {})}</div>
+          <div className={css.navList}>
+            {rows.map(row => (
+              <button
+                key={row.id}
+                type="button"
+                className={clsx(css.navCell, row.id === active && css.active)}
+                aria-current={row.id === active ? 'true' : undefined}
+                onClick={() => { onSelect(row.id) }}
+              >
+                {navIcon(row.id)}
+                <span className={css.navLabel}>{row.label}</span>
+              </button>
+            ))}
+          </div>
+        </nav>
+        <div className={css.content}>
+          <div className={css.header}>
+            <div className={css.actions}>{renderSlot('settings.action', {})}</div>
+            <button ref={closeButton} type="button" className={css.close} onClick={onClose}>
+              <IconCloseOutline16 size={14} />
+              <span className={css.hiddenLabel}>{renderSlot('settings.close', {})}</span>
+            </button>
+          </div>
+          <div className={css.options}>
+            {active !== undefined && renderSlot('settings.section', { close: onClose }, { only: active })}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Render the settings trigger and panel.
+ * @param props - composed slot props (contract/slots.ts).
+ * @returns the settings shell element tree.
+ */
+export function SettingsRoot(props: SettingsRootComponentProps) {
+  const { wide, useSections, useOnboardingSteps, useSessions, renderSlot } = props
+  const [open, setOpen] = useState(false)
+  const [activeId, setActiveId] = useState<string | undefined>(undefined)
+  const [completedOnboarding, setCompletedOnboarding] = useState<ReadonlySet<string>>(() => new Set())
+  const close = useCallback(() => {
+    setOpen(false)
+    setActiveId(undefined)
+  }, [])
+  const openSection = useCallback((id: string) => {
+    setActiveId(id)
+    setOpen(true)
+  }, [])
+
+  // The ledger tick keeps the nav rows fresh: registrants re-register with
+  // freshly localized text on locale change, and the trigger/header/close
+  // seats re-render through their own outlets' subscriptions.
+  const rows = useSections(s => s)
+  const onboardingSteps = useOnboardingSteps(s => s)
+  const onboardingActive = useSessions(state =>
+    state.phase === 'ready'
+    && (state.current === undefined || state.byId[state.current]?.blank === true))
+  const onboardingStep = onboardingActive
+    ? onboardingSteps.find(step => !completedOnboarding.has(step.id))
+    : undefined
+
+  useEffect(() => {
+    if (onboardingActive) return
+    setCompletedOnboarding(new Set())
+  }, [onboardingActive])
+
+  const completeOnboardingStep = useCallback((id: string) => {
+    setCompletedOnboarding((previous) => {
+      if (previous.has(id)) return previous
+      return new Set([...previous, id])
+    })
+  }, [])
+
+  return (
+    <>
+      <button
+        type="button"
+        className={clsx(css.trigger, !wide && css.rail)}
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        onClick={() => { setOpen(true) }}
+      >
+        {renderSlot('settings.trigger', { wide })}
+      </button>
+      {open && (
+        <SettingsPanel
+          rows={rows}
+          renderSlot={renderSlot}
+          activeId={activeId}
+          onSelect={setActiveId}
+          onClose={close}
+        />
+      )}
+      {/* The takeover chrome (OnboardingSurface: mask, opaque stage, `#root`
+          inert) lives inside the step component, wrapped around its visible
+          content — a step still deciding (private facts loading) renders
+          null, so nothing paints or blocks while it decides. */}
+      {onboardingStep !== undefined && renderSlot('settings.onboarding', {
+        stepId: onboardingStep.id,
+        complete: () => { completeOnboardingStep(onboardingStep.id) },
+        openSection,
+      }, { only: onboardingStep.id })}
+    </>
+  )
+}

packages/client/ui-settings-general/src/client/index.ts

@@ -1,17 +1,29 @@
 /**
- * Settings ownerless-copy plugin, browser half: registers everything on the
- * Settings surface that belongs to no single feature — the trigger/header
- * chrome content, local-document action, General section, and `settings`
- * dictionaries. Feature-owned rows and sections stay with their features.
+ * Settings shell and ownerless-copy plugin, browser half: renders the
+ * `sidebar.settings` occupant — panel chrome, section navigation, and the
+ * onboarding stage — and registers everything on the Settings pages that
+ * belongs to no single feature: the trigger/header chrome content,
+ * local-document action, General section, and `settings` dictionaries.
+ * Feature-owned rows and sections stay with their features.
  * Export discipline: packages/client/AGENTS.md.
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
+import { resolveSlotLabel } from '@deepseek-ai/dsh-client-ui-slots'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
-// Type-only: pulls the shell's SlotMap merges (trigger/header/section/item).
+// Type-only: the settings slot declarations plus the ctx.settingsScope Context
+// merge. Cross-plugin collaboration goes through the service, never a value
+// import (client bundle purity gate).
 import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
-// Type-only: pulls ctx.locale and the 'settings.general.item' SlotMap merge.
+// Type-only: pulls ctx.locale into this program.
 import type {} from '@deepseek-ai/dsh-client-locale/client'
+// Type-only: pulls the ctx.remote merge and the forwarded-event key face
+// (the settings invalidation rides the allowlist) into this program.
+import type {} from '@deepseek-ai/dsh-api-remotes/client'
+import type {
+  SettingsOnboardingStep, SettingsRootInjected, SettingsSectionRow,
+} from './shell-contract.ts'
+import { SettingsRoot } from './SettingsRoot.tsx'
 import { CloseLabel, HeaderContent, TriggerContent } from './chrome.tsx'
 import { GeneralSection } from './GeneralSection.tsx'
 import { SettingsDocumentAction } from './SettingsDocumentAction.tsx'
@@ -51,7 +63,7 @@ const NS = 'settings'
  * ui-settings' apply, whose activation order relative to this one is NOT
  * constrained; registrations depend on their slots through `slots.inject()`.
  */
-export const inject = ['slots', 'locale', 'connection']
+export const inject = ['slots', 'locale', 'connection', 'remote']
 
 /**
  * Register the `settings` dictionaries, the chrome content, and the General
@@ -83,12 +95,12 @@ export function apply(ctx: ClientContext): void {
   })
 
   ctx.effect(() => {
-    const refresh = (ns?: string): void => {
-      if (ns !== undefined && ns !== WELCOME_NOTICE_SETTINGS_NAMESPACE) return
-      refreshWelcomeIfLoaded(welcomeController)
-    }
+    const refresh = (): void => { refreshWelcomeIfLoaded(welcomeController) }
     const disposers = [
-      ctx.on('settings/changed', refresh),
+      ctx.remote.$on('settings/document-updated', (ns) => {
+        if (ns !== WELCOME_NOTICE_SETTINGS_NAMESPACE) return
+        refresh()
+      }),
       ctx.on('connection/reset', () => {
         refresh()
         refreshDocumentIfLoaded(documentController)
@@ -96,6 +108,77 @@ export function apply(ctx: ClientContext): void {
     ]
     return () => { for (const dispose of disposers) dispose() }
   }, 'ui-settings-general: metadata invalidations')
+  // The settings shell: this package occupies the sidebar-owned hole and
+  // declares the settings slots. Ledger → nav-row projection as an observable
+  // source (uSES contract: getSnapshot returns the cached rows until the
+  // ledger version moves). Labels may be locale-following thunks, so the cache
+  // key includes the locale revision and subscribers ride both sources.
+  let rowsVersion = -1
+  let rowsRevision = -1
+  let rows: readonly SettingsSectionRow[] = []
+  let onboardingVersion = -1
+  let onboardingSteps: readonly SettingsOnboardingStep[] = []
+  const shellInjected = (): SettingsRootInjected => ({
+    hooks: {
+      sections: {
+        getSnapshot: () => {
+          const version = ctx.slots.getVersion('settings.section')
+          const revision = ctx.locale.getSnapshot().revision
+          if (version !== rowsVersion || revision !== rowsRevision) {
+            rowsVersion = version
+            rowsRevision = revision
+            rows = ctx.slots.entries('settings.section')
+              .map(e => ({
+                /* v8 ignore next -- list-slot registration requires id (SlotCore rejects an entry without one) */
+                id: e.options.id ?? '',
+                order: e.options.order ?? 0,
+                label: resolveSlotLabel(e.options.label) ?? '',
+              }))
+              .sort((a, b) => a.order - b.order)
+          }
+          return rows
+        },
+        subscribe: (listener) => {
+          const offLedger = ctx.slots.subscribe('settings.section', listener)
+          const offLocale = ctx.locale.subscribe(listener)
+          return () => {
+            offLedger()
+            offLocale()
+          }
+        },
+      },
+      onboardingSteps: {
+        getSnapshot: () => {
+          const version = ctx.slots.getVersion('settings.onboarding')
+          if (version !== onboardingVersion) {
+            onboardingVersion = version
+            onboardingSteps = ctx.slots.entries('settings.onboarding')
+              .map(e => ({
+                /* v8 ignore next -- list-slot registration requires id */
+                id: e.options.id ?? '',
+                order: e.options.order ?? 0,
+              }))
+              .sort((a, b) => a.order - b.order)
+          }
+          return onboardingSteps
+        },
+        subscribe: listener => ctx.slots.subscribe('settings.onboarding', listener),
+      },
+    },
+  })
+  ctx.slots.inject('sidebar.settings', () => ctx.slots.register({
+    name: 'sidebar.settings',
+    children: {
+      'settings.trigger': { kind: 'single', scope: 'root' },
+      'settings.header': { kind: 'single', scope: 'root' },
+      'settings.action': { kind: 'list', scope: 'root' },
+      'settings.close': { kind: 'single', scope: 'root' },
+      'settings.section': { kind: 'list', scope: 'root' },
+      'settings.onboarding': { kind: 'list', scope: 'root' },
+    },
+    inject: shellInjected,
+  }, SettingsRoot))
+
   ctx.slots.inject('settings.trigger', () =>
     ctx.slots.register({ name: 'settings.trigger', locale: NS }, TriggerContent))
   ctx.slots.inject('settings.header', () =>

packages/client/ui-settings-general/src/client/shell-contract.ts

@@ -0,0 +1,59 @@
+/**
+ * Settings shell contract — the types of the `sidebar.settings` occupant this
+ * package renders. They live here rather than in ui-settings because they
+ * reference the sidebar's own slot type: ui-settings is the settings domain's
+ * base layer and must not depend on any `ui-*` presentation package, or the
+ * reference graph closes a cycle through ui-sidebar → ui-layout → ui-theme.
+ * The settings SLOT types (what registrants contribute) stay in ui-settings.
+ */
+import type { HostObservable, InjectFace, PropsRenderSlots, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+// Type-only: pulls ui-sidebar's SlotMap merge (the 'sidebar.settings' entry)
+// into every program that sees this contract.
+import type {} from '@deepseek-ai/dsh-client-ui-sidebar/client'
+// Type-only: pulls the settings slot declarations the shell renders into.
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
+
+/** One nav row projected from a settings.section registration's options. */
+export interface SettingsSectionRow {
+  id: string
+  order: number
+  label: string
+}
+
+/** One ordered onboarding step projected from a slot registration. */
+export interface SettingsOnboardingStep {
+  id: string
+  order: number
+}
+
+/**
+ * Registrant-private injected share of the settings shell (assembled in
+ * apply): the ledger's nav-row projection as a hooks-compartment source —
+ * the shell reads no locale state and subscribes through the bound hook.
+ */
+export type SettingsRootInjected = {
+  hooks: {
+    /** settings.section ledger projected into ordered nav rows. */
+    sections: HostObservable<readonly SettingsSectionRow[]>
+    /** settings.onboarding ledger projected into coordinator order. */
+    onboardingSteps: HostObservable<readonly SettingsOnboardingStep[]>
+  }
+}
+
+/**
+ * Full component props of the settings shell root: the sidebar owner share
+ * (wide/rail state) plus the declared render shares and the injected face
+ * (hooks compartment bound to useSections). No store is registered — modal
+ * open state and active section id are component-local viewing state.
+ */
+export type SettingsRootComponentProps =
+  PropsRuntime<'sidebar.settings'>
+  & PropsRenderSlots<
+    | 'settings.trigger'
+    | 'settings.header'
+    | 'settings.action'
+    | 'settings.close'
+    | 'settings.section'
+    | 'settings.onboarding'
+  >
+  & InjectFace<SettingsRootInjected>