jsgui3-server 0.0.148 → 0.0.150

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.

package/docs/books/adaptive-control-improvements/05-styling-theming-density-upgrades.md

@@ -0,0 +1,114 @@
+# Chapter 5 — Styling, Theming, and Density Upgrades
+
+This chapter converts adaptive composition into reliable visual behavior by extending existing token and theme practices.
+
+## 5.1 Current Baseline
+
+`css/jsgui-tokens.css` already provides:
+
+- strong base spacing and typography scales
+- light/dark token bridges
+- admin control token bridge (`--admin-*`)
+- reduced-motion token durations
+
+This is a strong foundation; the required improvements are additive.
+
+## 5.2 Mode-Attribute Styling Policy
+
+Use mode attributes as the primary adaptive selector strategy:
+
+- `[data-layout-mode="phone"]`
+- `[data-layout-mode="tablet"]`
+- `[data-layout-mode="desktop"]`
+- `[data-density-mode="compact|cozy|comfortable"]`
+- `[data-interaction-mode="touch|pointer|hybrid"]`
+
+Avoid distributing raw `@media` breakpoints through control CSS except where absolutely necessary.
+
+## 5.3 Density Override Profiles
+
+Define explicit density token overlays:
+
+- Compact:
+  - tighter spacing and row heights for high-density desktop/power users
+- Cozy (default):
+  - current baseline behavior
+- Comfortable:
+  - larger spacing and text rhythm for readability/accessibility
+
+Token categories to override:
+
+- `--j-space-*`
+- `--admin-font-size`
+- `--admin-row-height`
+- `--admin-cell-padding`
+- selected control-specific paddings where needed
+
+## 5.4 Touch Interaction Floor
+
+When `data-interaction-mode="touch"` is active:
+
+- enforce minimum target height/width of 44px for actionable elements
+- ensure spacing prevents accidental tap overlap
+- prefer sheet/drawer transitions that preserve direct manipulation expectations
+
+This should be implemented via token and selector policy, not one-off control hacks.
+
+## 5.5 Control-Specific Styling Upgrades
+
+### Master_Detail
+
+- move hardcoded color/border values to admin tokens
+- adjust master list item padding per density mode
+- enforce phone-friendly detail panel spacing in sheet/overlay mode
+
+### Tabbed_Panel
+
+- tokenized active indicator thickness and spacing
+- compact mode icon-first treatment while preserving ARIA labels
+- touch mode minimum tab target sizing
+
+### Split_Pane
+
+- hide/de-emphasize drag handle in phone mode
+- expose pointer-focused affordance only when interaction mode allows
+
+### Data_Table
+
+- mode-specific row density token sets
+- readable card mode typography and spacing
+- tokenized header/background contrasts for high-density modes
+
+### Sidebar_Nav / Toolbar
+
+- icon rail paddings and hit area tuning
+- overflow menu spacing and typography consistency across density modes
+
+### Modal / Form_Container
+
+- sheet/full-screen presentation spacing in phone mode
+- form section spacing scales tied to density
+
+## 5.6 Theme Profile Extension
+
+Theme persistence object should include:
+
+- selected theme
+- preferred density
+- optional token overrides
+
+It should exclude:
+
+- runtime layout mode
+- runtime viewport dimensions
+
+## 5.7 Styling Quality Gates
+
+A control styling upgrade is complete when:
+
+1. All hardcoded adaptive-relevant spacing/sizing values are tokenized.
+2. Mode-attribute selectors exist for behavior differences.
+3. Touch target minimums pass in touch profiles.
+4. Compact and comfortable density modes remain readable and usable.
+
+Next: testing gates that verify composition and styling behavior across the viewport matrix.

package/docs/books/adaptive-control-improvements/06-testing-quality-gates.md

@@ -0,0 +1,97 @@
+# Chapter 6 — Testing and Quality Gates for Adaptive Upgrades
+
+Responsive behavior is a quality gate, not an optional enhancement.
+
+This chapter defines mandatory test coverage for the improvements in this book.
+
+## 6.1 Viewport Matrix
+
+Minimum matrix for all Tier 1 and Tier 2 controls:
+
+1. Phone portrait: 390×844
+2. Phone landscape: 844×390
+3. Tablet portrait: 768×1024
+4. Tablet landscape: 1024×768
+5. Desktop narrow: 1280×720
+6. Desktop wide: 1920×1080
+
+## 6.2 Assertion Classes
+
+### P0 — Structural integrity
+
+- no horizontal overflow
+- control renders with non-zero functional area
+- primary action path remains available
+
+### P1 — Adaptive behavior integrity
+
+- mode-specific composition appears as specified
+- state transitions preserve user context where intended
+- keyboard and ARIA semantics remain correct after morphs
+
+### P2 — Visual and ergonomic integrity
+
+- density mode variants maintain readability
+- touch target sizing and spacing pass thresholds
+- reduced-motion users receive non-disorienting transitions
+
+## 6.3 Tier-Specific Test Scope
+
+### Tier 1
+
+- full P0 + P1 + P2 matrix required before merge
+
+### Tier 2
+
+- full P0 + P1 required
+- P2 mandatory for touch-heavy controls (`Toolbar`, `Sidebar_Nav`, `Modal`)
+
+### Tier 3/4
+
+- P0 mandatory
+- selective P1/P2 where risk justifies coverage
+
+## 6.4 Test Harness Pattern
+
+Use self-contained E2E files per control:
+
+- build SSR test page
+- activate client behavior
+- run matrix assertions
+- capture screenshots per viewport
+- tear down server/browser
+
+This follows project testing guidance and avoids cross-test coupling.
+
+## 6.5 Required Regression Scenarios
+
+Every upgraded control must include:
+
+1. Mode transition scenario (phone → desktop and desktop → phone)
+2. Orientation transition scenario (portrait ↔ landscape)
+3. Keyboard-only navigation scenario
+4. Touch interaction scenario (for touch-relevant controls)
+5. Reduced-motion behavior scenario where animations exist
+
+## 6.6 Exit Criteria Per Control
+
+A control upgrade is complete when:
+
+1. Functional tests pass on all required viewport profiles.
+2. No new console errors are introduced by mode transitions.
+3. Screenshot set is captured for review and retained in expected location.
+4. Existing desktop behavior remains backward compatible unless explicitly changed.
+
+## 6.7 Program-Level Quality Dashboard
+
+Track adaptive rollout readiness with a simple control checklist:
+
+- composition complete
+- state placement audited
+- token/mode styling complete
+- P0/P1/P2 tests green
+- docs updated
+
+This should be maintained alongside roadmap execution to prevent partially adaptive shipping.
+
+Next: delivery sequencing, ownership model, and milestone plan.