jsgui3-server 0.0.149 → 0.0.151

package/docs/books/adaptive-control-improvements/01-control-candidate-matrix.md

@@ -0,0 +1,122 @@
+# Chapter 1 — Control Candidate Matrix and Findings
+
+## Purpose
+
+Prioritize the control catalog for adaptive upgrades based on real impact:
+
+- Structural risk on phone/tablet/orientation change
+- Data density and interaction complexity
+- Existing gap between desktop and touch behavior
+- Reuse value as a pattern for other controls
+
+## Evidence Snapshot
+
+Recent source-level review identified these concrete issues in key controls:
+
+- `master_detail.js`: fixed two-column grid (`minmax(180px, 240px) 1fr`) with no layout-mode branch.
+- `tabbed-panel.js`: horizontal tab strip is vulnerable to overflow in narrow widths.
+- `split_pane.js`: pointer-oriented resize interaction with no touch-first fallback.
+- `data_table.js`: large data surface with no responsive column-priority/card transformation strategy.
+- `sidebar_nav.js`: manual collapse exists, but no environment-driven auto-collapse/morph.
+- `Toolbar.js`: no overflow strategy for narrow widths.
+- `modal.js`: static size variants only; no automatic phone full-screen mode.
+- `form_container.js`: no adaptive multi-column to single-column strategy.
+- `status_dashboard.js`: strongest baseline due to grid auto-fit, but no explicit density/layout-mode policy.
+
+## Tiering Criteria
+
+### Impact score (1-5)
+
+- 5: Breaks or heavily degrades on common phone/tablet layouts
+- 4: Usable but substantially reduced usability on touch/narrow layouts
+- 3: Mostly usable; quality or accessibility debt
+- 2: Minor adaptive polish only
+- 1: Already adaptive enough through existing composition/tokens
+
+### Effort score (1-5)
+
+- 5: Significant API and behavior changes across composition + interaction + tests
+- 4: Medium-high code and test work
+- 3: Moderate scoped update
+- 2: Small targeted update
+- 1: Minimal changes
+
+## Candidate Matrix
+
+| Control | Impact | Effort | Priority | Why now |
+|---|---:|---:|---|---|
+| Master_Detail | 5 | 3 | Tier 1 | Canonical two-pane pattern; immediate phone pain; good first pattern anchor |
+| Tabbed_Panel | 5 | 4 | Tier 1 | High usage + overflow + keyboard/touch adaptation needs |
+| Split_Pane | 5 | 4 | Tier 1 | Pointer-first behavior conflicts with touch/mobile |
+| Data_Table | 5 | 5 | Tier 1 | Highest value for admin UIs; biggest adaptation gap |
+| Sidebar_Nav | 4 | 3 | Tier 2 | Shell-level navigation needs auto morphing |
+| Form_Container | 4 | 3 | Tier 2 | Forms must adapt cleanly across orientation and width |
+| Modal | 4 | 2 | Tier 2 | Quick high-value upgrade for phone usability |
+| Toolbar | 4 | 3 | Tier 2 | Navigation/action density requires overflow strategy |
+| Window / Window_Manager | 3 | 4 | Tier 3 | Desktop metaphor must degrade predictably on touch |
+| Wizard | 3 | 2 | Tier 3 | Stepper strip and nav controls need mobile pattern |
+| Status_Dashboard | 2 | 2 | Tier 4 | Mostly good; needs explicit density/mode tuning |
+| Drawer | 2 | 2 | Tier 4 | Good baseline; mostly environment integration and polish |
+
+## Top Discoveries
+
+### Discovery A — the highest-value pattern is the two-pane morph
+
+`Master_Detail`, `Split_Pane`, and many app-level shells all need the same adaptive morph:
+
+- Desktop: dual pane
+- Tablet portrait: primary + secondary as revealable overlay
+- Phone: stacked flow or drawer/sheet secondary
+
+This should be implemented once as a reusable adaptive region pattern and reused.
+
+### Discovery B — navigation controls need shared overflow/morph infrastructure
+
+`Tabbed_Panel`, `Sidebar_Nav`, and `Toolbar` all face narrow-width overflow and touch navigation constraints.
+
+Without shared helpers, each control will reinvent:
+
+- overflow detection
+- “more” bucket behavior
+- focus order and ARIA preservation across morphs
+
+### Discovery C — Data_Table is both a control and a mode family
+
+Treat `Data_Table` as a multi-mode control family:
+
+- Desktop mode: full grid
+- Tablet mode: reduced columns + optional detail pane
+- Phone mode: list/card mode with row expansion
+
+Trying to keep a single static grid shape across all modes will keep mobile quality low.
+
+## Layer Analysis (A/B/C/D)
+
+Applying the four-layer model:
+
+- Layer A (Domain): mostly unaffected; business data stays stable.
+- Layer B (View Composition): major work in Tier 1 and Tier 2 controls.
+- Layer C (Adaptive Resolution): requires consistent environment service usage.
+- Layer D (Concrete Render): token/mode-attribute CSS work across most controls.
+
+## Model Placement Rules for This Program
+
+For all upgrades in this book:
+
+- `data.model`: business entities, user-intent preferences that are device-agnostic.
+- `view.data.model`: resolved adaptive state (layout_mode, visible_columns, region presentation state).
+- `view.model`: transient interaction state (open/closed, active tab index, temporary scroll/focus state).
+
+Never persist runtime viewport-derived values as domain data.
+
+## Success Criteria for Candidate Selection
+
+A control is ready for implementation when:
+
+1. Target mode behavior is specified for phone, tablet, desktop.
+2. State placement is mapped to model layers.
+3. CSS mode-attribute strategy is identified.
+4. P0/P1/P2 viewport assertions are defined.
+5. Regression impact on existing desktop behavior is bounded.
+
+Next: Tier 1 playbooks with concrete upgrade recipes.

package/docs/books/adaptive-control-improvements/02-tier-1-layout-playbooks.md

@@ -0,0 +1,207 @@
+# Chapter 2 — Tier 1 Layout Control Playbooks
+
+Tier 1 controls are the highest-impact adaptive targets and should be implemented first.
+
+Patterns applied:
+
+- Chapter 2 pattern: Four-layer composition split
+- Chapter 3 pattern: adaptive state in view models
+- Chapter 6 pattern: `compose_adaptive()` and environment contract
+
+---
+
+## 2.1 Master_Detail
+
+### Current issue
+
+Current CSS uses a fixed two-column grid and lacks mode-aware composition.
+
+### Target behavior by mode
+
+- Phone:
+  - Single-column list-first flow
+  - Selecting an item opens detail in a sheet or full panel (configurable)
+- Tablet:
+  - Portrait: list + toggleable detail overlay
+  - Landscape: dual-pane with narrower master width
+- Desktop:
+  - Dual-pane default with stable side-by-side behavior
+
+### Composition strategy
+
+Use discrete JS composition + mode-attribute CSS polish:
+
+- JS for pane structure/morphing
+- CSS for spacing, typography, transitions per mode
+
+### State placement
+
+- `data.model`: items, selected_id
+- `view.data.model`: layout_mode, detail_presentation (`inline` | `overlay` | `sheet`)
+- `view.model`: detail_open, last_focus_item_id
+
+### Implementation steps
+
+1. Add `compose_phone_layout`, `compose_tablet_layout`, `compose_desktop_layout`.
+2. Route through `compose_adaptive`.
+3. Keep selected-item domain logic unchanged.
+4. Add detail open/close mechanics only in view state.
+5. Apply `[data-layout-mode]` CSS selectors for spacing and target sizes.
+
+### Test essentials
+
+- P0: no horizontal overflow in all six viewports.
+- P1: selecting master item updates detail in all modes.
+- P1: overlay/sheet opens and closes with keyboard + click/touch.
+- P2: touch hit targets are at least 44px in touch profiles.
+
+---
+
+## 2.2 Tabbed_Panel
+
+### Current issue
+
+Tab strip is horizontal-first and can overflow on narrow screens.
+
+### Target behavior by mode
+
+- Phone:
+  - Scrollable tab strip or compact segment mode
+  - Optional icon-first labels with hidden text fallback for a11y
+- Tablet:
+  - Horizontal strip with controlled overflow handling
+- Desktop:
+  - Existing behavior preserved with richer indicators
+
+### Composition strategy
+
+Hybrid:
+
+- JS: overflow bucket strategy and optional tab-list mode switching
+- CSS: mode/density token scaling for tabs and indicators
+
+### State placement
+
+- `data.model`: tab definitions/content
+- `view.data.model`: tab_layout (`scroll`, `fit`, `overflow_menu`)
+- `view.model`: active_tab_index, overflow_open
+
+### Implementation steps
+
+1. Add tab measurement logic in activation with SSR-safe guards.
+2. Resolve `tab_layout` from available width (container-aware where possible).
+3. Preserve keyboard navigation semantics and ARIA roles across modes.
+4. Ensure active indicator style uses tokens, not hardcoded colors.
+
+### Test essentials
+
+- P0: active tab always visible and selectable across matrix.
+- P1: keyboard navigation (arrows/home/end) remains correct in overflow mode.
+- P1: ARIA (`aria-selected`, `aria-controls`) remains accurate after mode switches.
+- P2: indicator and tab touch targets remain legible and accessible.
+
+---
+
+## 2.3 Split_Pane
+
+### Current issue
+
+Resize interaction is pointer-centric; phone behavior should not rely on tiny drag handles.
+
+### Target behavior by mode
+
+- Phone:
+  - Replace draggable split with stacked sections and toggle affordance
+- Tablet:
+  - Optional split in landscape, stacked in portrait by default
+- Desktop:
+  - Existing resizable split retained
+
+### Composition strategy
+
+Discrete JS composition with interaction-mode rules:
+
+- `touch` and narrow mode disable drag-resize
+- `pointer` mode allows drag-resize with guardrails
+
+### State placement
+
+- `data.model`: pane content/config (device-agnostic)
+- `view.data.model`: split_enabled, orientation_mode, pane_ratio_policy
+- `view.model`: current_ratio (session-level), active_pane
+
+### Implementation steps
+
+1. Introduce `split_enabled` resolver from layout and interaction mode.
+2. Add adaptive orientation defaults.
+3. Replace drag handle with mode-aware toggle controls on phone.
+4. Persist only user intent preferences (if any), not live viewport-derived ratio.
+
+### Test essentials
+
+- P0: no unusable drag affordance in phone mode.
+- P1: desktop drag-resize still works and obeys min/max boundaries.
+- P1: orientation transitions preserve pane content and focus order.
+- P2: touch mode controls meet target-size requirements.
+
+---
+
+## 2.4 Data_Table
+
+### Current issue
+
+Data-dense behavior is desktop-oriented; lacks formal mode family for phone/tablet.
+
+### Target behavior by mode
+
+- Phone:
+  - Card/list row presentation
+  - Primary fields shown inline; secondary fields in row detail expansion
+- Tablet:
+  - Priority-column strategy + optional side detail panel
+- Desktop:
+  - Full grid with advanced interactions (resize/frozen columns/etc.)
+
+### Composition strategy
+
+Discrete JS mode family + CSS density scaling.
+
+### State placement
+
+- `data.model`: rows, filters, sort state, selected ids
+- `view.data.model`: table_mode (`grid` | `compact_grid` | `card_list`), visible_columns
+- `view.model`: expanded_row_ids, hover/focus transient state
+
+### Implementation steps
+
+1. Introduce explicit render modes tied to layout mode.
+2. Add column priority metadata and `visible_columns` resolver.
+3. Implement phone card-list renderer behind mode switch.
+4. Gate pointer-only features (column drag resize) to pointer-capable contexts.
+5. Keep selection/filter/sort semantics identical across modes.
+
+### Test essentials
+
+- P0: core CRUD-adjacent row interactions survive all modes.
+- P1: selected row consistency across mode transition (phone ⇄ desktop).
+- P1: keyboard nav remains valid where grid mode is active.
+- P2: card/list readability and token-driven spacing in compact/comfortable density.
+
+---
+
+## 2.5 Tier 1 Implementation Order
+
+Recommended order:
+
+1. Master_Detail
+2. Split_Pane
+3. Tabbed_Panel
+4. Data_Table
+
+Rationale:
+
+- Master_Detail and Split_Pane establish the reusable two-pane morph pattern.
+- Tabbed_Panel establishes shared overflow and keyboard guarantees.
+- Data_Table then reuses both pattern families in the highest-complexity control.
+
+Next: Tier 2 controls (navigation, forms, overlays) that depend on the Tier 1 patterns.

package/docs/books/adaptive-control-improvements/03-tier-2-navigation-form-overlay.md

@@ -0,0 +1,140 @@
+# Chapter 3 — Tier 2 Playbooks: Navigation, Forms, and Overlays
+
+Tier 2 focuses on controls that shape shell usability and input workflows.
+
+---
+
+## 3.1 Sidebar_Nav
+
+### Current issue
+
+Sidebar supports collapse behavior, but not environment-driven automatic morphing.
+
+### Target behavior by mode
+
+- Phone: drawer/overlay nav with explicit open/close controls
+- Tablet: collapsed-icon rail by default; expandable overlay section groups
+- Desktop: full inline sidebar
+
+### Composition approach
+
+- Discrete JS morphing to drawer/rail/full variants
+- CSS mode attributes for spacing and typography
+
+### State placement
+
+- `data.model`: nav schema (sections/items), permissions
+- `view.data.model`: nav_presentation (`drawer` | `rail` | `inline`)
+- `view.model`: nav_open, expanded_section_ids
+
+### Key implementation notes
+
+- Ensure focus trap only when in overlay drawer mode.
+- Preserve section expansion state when moving between rail and inline where practical.
+- Use existing Drawer behavior as foundational primitive where possible.
+
+---
+
+## 3.2 Toolbar
+
+### Current issue
+
+No formal overflow policy for narrow layouts.
+
+### Target behavior by mode
+
+- Phone: icon-first primary actions + overflow menu for secondary actions
+- Tablet: mixed icon+label with medium overflow threshold
+- Desktop: full action set inline
+
+### Composition approach
+
+- Hybrid:
+  - JS for overflow resolution and action bucketing
+  - CSS for density and label visibility rules
+
+### State placement
+
+- `data.model`: action registry and semantics
+- `view.data.model`: visible_action_ids, overflow_action_ids
+- `view.model`: overflow_open, focused_action_id
+
+### Key implementation notes
+
+- Keep action semantics stable regardless of location (inline vs overflow).
+- Preserve keyboard order and shortcut mappings.
+- Avoid duplicate action handlers by sharing command layer.
+
+---
+
+## 3.3 Modal
+
+### Current issue
+
+Size variants exist but no automatic phone-first adaptation.
+
+### Target behavior by mode
+
+- Phone: full-screen modal (or sheet variant for low-criticality flows)
+- Tablet: large centered modal with safe margins
+- Desktop: existing size variants
+
+### Composition approach
+
+- Mostly CSS/token policy with a small JS default resolver
+
+### State placement
+
+- `data.model`: modal content model / business state
+- `view.data.model`: resolved_modal_size, modal_presentation
+- `view.model`: is_open, active_focus_scope
+
+### Key implementation notes
+
+- Ensure ESC/backdrop behavior remains consistent.
+- Focus return target should survive mode changes.
+- Use motion tokens for transitions and respect reduced-motion.
+
+---
+
+## 3.4 Form_Container
+
+### Current issue
+
+No explicit adaptive field grid strategy for orientation and width changes.
+
+### Target behavior by mode
+
+- Phone: single-column form flow
+- Tablet portrait: mostly single-column, selective two-column groups
+- Tablet landscape/Desktop: two or more columns where appropriate
+
+### Composition approach
+
+- Primarily CSS mode selectors for grid columns
+- JS only for field-group structural changes where required
+
+### State placement
+
+- `data.model`: form values and validation outcomes
+- `view.data.model`: form_layout_mode, visible_field_groups
+- `view.model`: active_field_id, section_expanded_state
+
+### Key implementation notes
+
+- Keep validation state and messages independent of presentation layout.
+- Avoid moving domain values during layout transitions.
+- Ensure tab/focus order remains logical in both column and stacked modes.
+
+---
+
+## 3.5 Tier 2 Test Priorities
+
+Required assertions for each upgraded Tier 2 control:
+
+- P0: no horizontal overflow and all primary actions reachable.
+- P1: keyboard and ARIA behavior preserved after adaptive morph.
+- P1: orientation changes do not lose active/expanded/open state unexpectedly.
+- P2: touch target and spacing quality in compact/cozy/comfortable densities.
+
+Next: cross-cutting platform functionality needed so these upgrades do not duplicate logic.

package/docs/books/adaptive-control-improvements/04-cross-cutting-platform-functionality.md

@@ -0,0 +1,141 @@
+# Chapter 4 — Cross-Cutting Platform Functionality
+
+Control-specific improvements will be expensive and inconsistent unless shared adaptive infrastructure is added first.
+
+This chapter defines those shared capabilities.
+
+## 4.1 View Environment Service (Required)
+
+### Responsibility
+
+Resolve and publish:
+
+- viewport dimensions + orientation
+- layout_mode
+- density_mode
+- interaction_mode
+- motion_mode
+
+### Why first
+
+Without this, controls will continue ad-hoc viewport checks and duplicated breakpoint logic.
+
+### Output contract
+
+```js
+context.view_environment = {
+    viewport: { width, height, orientation },
+    layout_mode: 'phone' | 'tablet' | 'desktop',
+    density_mode: 'compact' | 'cozy' | 'comfortable',
+    interaction_mode: 'touch' | 'pointer' | 'hybrid',
+    motion_mode: 'normal' | 'reduced'
+};
+```
+
+### CSS bridge
+
+Set root attributes:
+
+- `data-layout-mode`
+- `data-density-mode`
+- `data-interaction-mode`
+- `data-motion-mode`
+
+## 4.2 Adaptive Composition Helper (Required)
+
+### Responsibility
+
+Single utility to switch composition branches by layout mode and recompose on mode change.
+
+### Why first
+
+Prevents control-specific conditional composition boilerplate and inconsistent fallback behavior.
+
+### Baseline usage
+
+```js
+compose_adaptive(this, {
+    phone: () => this.compose_phone(),
+    tablet: () => this.compose_tablet(),
+    desktop: () => this.compose_desktop()
+});
+```
+
+## 4.3 Responsive Parameter Resolution (Required)
+
+### Responsibility
+
+Allow mode-branching in control params resolved through a single path.
+
+### Why first
+
+Many controls need per-mode variants (columns, row height, visible labels, etc.) without custom code per control.
+
+### Existing alignment
+
+`control_mixins/theme_params.js` already centralizes param schemas and hook derivation, making it the right extension point.
+
+## 4.4 Container-Aware Mode Utility (Recommended)
+
+### Responsibility
+
+Resolve local mode from control container width for embedded widgets.
+
+### Why
+
+Viewport mode alone is insufficient for controls rendered in narrow side panels on desktop.
+
+### Priority
+
+P2 relative to first shipping pass, but strongly recommended for table/tab/toolbar quality.
+
+## 4.5 Shared Overflow Policy Utility (Recommended)
+
+### Responsibility
+
+Provide a reusable strategy for:
+
+- action overflow bucketing
+- tab overflow handling
+- consistent keyboard/focus behavior in overflow menus
+
+### Why
+
+`Tabbed_Panel`, `Toolbar`, and potentially `Horizontal_Menu` need similar overflow logic.
+
+## 4.6 Adaptive Region Morph Utility (Recommended)
+
+### Responsibility
+
+Declare region morphs (inline sidebar ↔ rail ↔ drawer; panel ↔ sheet) in one consistent abstraction.
+
+### Why
+
+Reduces repeated custom morph logic in shell controls.
+
+## 4.7 Other Functional Improvements
+
+Beyond control-level updates, these functional additions materially improve adaptive behavior quality:
+
+1. Preference persistence boundary:
+   - persist theme + density preference
+   - do not persist runtime layout mode
+2. Focus restoration helpers for mode transitions:
+   - return focus to sensible targets when overlays close or mode morphs
+3. Motion policy adapter:
+   - enforce reduced-motion behavior for adaptive transitions
+4. Touch-target audit utility:
+   - runtime test utility for minimum target sizes on touch mode
+
+## 4.8 Dependency Order
+
+Implement shared platform functionality in this order:
+
+1. View Environment Service
+2. Adaptive Composition Helper
+3. Responsive Parameter Resolution
+4. Shared Overflow Policy
+5. Adaptive Region Morph Utility
+6. Container-Aware Mode Utility
+
+This order unlocks rapid control upgrades with minimal rework.