@zohodesk/library-platform 1.2.0-exp.45 → 1.2.2-exp.1

package/es/library/dot/components/part-wrapper/POC_DOCUMENT.md

@@ -1,648 +0,0 @@
-# POC Document: PartWrapper — Styling Boundaries for ACA Layouts
-
-**Reference:** ADR UI-STYLE-003  
-**Date:** February 2026  
-**Status:** POC Complete
-
----
-
-## 1. Agenda
-
-### What is the problem?
-
-In our ACA (Adaptive Component Architecture), layout components use inner components like `TextBox`, `Button`, `Text`, etc. These inner components are **legacy** — they were built before ACA.
-
-Developers need to **style around** these inner components (add padding, hover effects, borders) **without modifying** the inner components themselves.
-
-**Example problem:**
-
-```
-┌─ Form Layout ────────────────────────────┐
-│                                          │
-│  ┌─ TextBox (legacy) ─────────────────┐  │
-│  │  How do I add hover background     │  │  ← Can't modify TextBox
-│  │  around this field?                │  │
-│  └────────────────────────────────────┘  │
-│                                          │
-│  ┌─ Email (legacy) ───────────────────┐  │
-│  │  How do I add bottom border        │  │  ← Can't modify Email
-│  │  below this field?                 │  │
-│  └────────────────────────────────────┘  │
-│                                          │
-└──────────────────────────────────────────┘
-```
-
-### What does this POC prove?
-
-We can wrap any inner component with a **PartWrapper** that adds `part` / `data-part` attributes as CSS hooks — **without changing any existing component code**.
-
-```
-┌─ Form Layout ────────────────────────────┐
-│                                          │
-│  ┌─ PartWrapper [data-part="field"] ──┐  │  ← CSS target!
-│  │  ┌─ TextBox (untouched) ────────┐  │  │
-│  │  │  ...                         │  │  │
-│  │  └──────────────────────────────┘  │  │
-│  └────────────────────────────────────┘  │
-│                                          │
-└──────────────────────────────────────────┘
-
-CSS:  [data-part="field"]:hover { background: #f8f9fa; }
-```
-
----
-
-## 2. Master Plan
-
-### High-Level Flow
-
-```
-┌──────────────────────────────────────────────────────────────────────┐
-│                        ACA LAYOUT VIEW                               │
-│                                                                      │
-│   Layout CSS (.module.css)                                           │
-│   ┌────────────────────────────────────────────────────────────────┐ │
-│   │  [data-part="field-container"] { padding: 12px; }             │ │
-│   │  [data-part="field-container"]:hover { background: #f8f9fa; } │ │
-│   │  [data-part="action-bar"] { display: flex; gap: 8px; }       │ │
-│   └───────────────────────────┬────────────────────────────────────┘ │
-│                               │ targets                              │
-│                               ▼                                      │
-│   Layout JSX (View.tsx)                                              │
-│   ┌────────────────────────────────────────────────────────────────┐ │
-│   │                                                                │ │
-│   │  <PartWrapper part="field-container" content={                 │ │
-│   │      <TextBox ... />  ← legacy, untouched                     │ │
-│   │  } />                                                          │ │
-│   │                                                                │ │
-│   │  <PartWrapper part="field-container" content={                 │ │
-│   │      <Email ... />    ← legacy, untouched                     │ │
-│   │  } />                                                          │ │
-│   │                                                                │ │
-│   └────────────────────────────────────────────────────────────────┘ │
-└──────────────────────────────────────────────────────────────────────┘
-```
-
-### Rendered DOM Output
-
-```
-<div data-part="form-layout">            ← Layout root
-
-  <div part="field-container"            ← PartWrapper (display: contents)
-       data-part="field-container">
-    <div class="fieldItem">              ← TextBox renders here (untouched)
-      <label>Name</label>
-      <input type="text" />
-    </div>
-  </div>
-
-  <div part="field-container"            ← PartWrapper (display: contents)
-       data-part="field-container">
-    <div class="fieldItem">              ← Email renders here (untouched)
-      <label>Email</label>
-      <input type="email" />
-    </div>
-  </div>
-
-</div>
-```
-
-### Component Architecture (ACA Layers)
-
-```
-PartWrapper follows the SmartActionBand ACA pattern:
-
-┌─────────────────────────────────────────────────────────┐
-│  DOMAIN LAYER                                           │
-│  domain/entities/interfaces/Properties.ts               │
-│  ┌───────────────────────────────────────────────────┐  │
-│  │  part: string        ← required, CSS hook name    │  │
-│  │  tagName: string     ← default 'div'              │  │
-│  │  className: string   ← extra CSS classes           │  │
-│  │  content: ReactNode  ← inner component(s)         │  │
-│  └───────────────────────────────────────────────────┘  │
-├─────────────────────────────────────────────────────────┤
-│  APPLICATION LAYER                                      │
-│  applications/interfaces/State.ts                       │
-│  ┌───────────────────────────────────────────────────┐  │
-│  │  { properties: PartWrapperProperties }            │  │
-│  └───────────────────────────────────────────────────┘  │
-├─────────────────────────────────────────────────────────┤
-│  FRAMEWORK LAYER                                        │
-│  frameworks/ui/                                         │
-│  ┌───────────────────────────────────────────────────┐  │
-│  │  PartWrapper.tsx          ← entry point           │  │
-│  │       │                                           │  │
-│  │       ▼                                           │  │
-│  │  PartWrapperFactory.ts    ← createCustomComponent │  │
-│  │       │                                           │  │
-│  │       ▼                                           │  │
-│  │  PartWrapperView.tsx      ← renders <div part=..> │  │
-│  │       │                                           │  │
-│  │       ▼                                           │  │
-│  │  css/PartWrapper.module.css ← display: contents   │  │
-│  └───────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────┘
-```
-
-### Data Flow Through `createCustomComponent`
-
-```
-Developer writes:
-  <PartWrapper part="field" content={<TextBox />} />
-
-        │
-        ▼
-┌─ createCustomComponent ────────────────────────────────┐
-│                                                        │
-│  props = { part: "field", content: <TextBox /> }       │
-│        │                                               │
-│        ▼                                               │
-│  discardChildren(props)                                │
-│     → looks for props.children → NOT FOUND (no-op)     │
-│     → content is untouched ✅                          │
-│        │                                               │
-│        ▼                                               │
-│  controller.updateProperties({ part, content, ... })   │
-│        │                                               │
-│        ▼                                               │
-│  state.properties = { part: "field",                   │
-│                       content: <TextBox /> }           │
-│        │                                               │
-│        ▼                                               │
-│  <PartWrapperView state={state} />                     │
-│        │                                               │
-│        ▼                                               │
-│  Renders:                                              │
-│  <div part="field" data-part="field"                   │
-│       class="partWrapper">                             │
-│    <TextBox />                                         │
-│  </div>                                                │
-│                                                        │
-└────────────────────────────────────────────────────────┘
-```
-
-### Component Categories Handled
-
-```
-80+ View files analysed across the codebase:
-
-Category A — HTML Root (~8 components)
-┌──────────────────────────────────────────┐
-│  Component       │  Root Element         │
-│──────────────────┼───────────────────────│
-│  TableListView   │  <div>                │
-│  BreadcrumbView  │  <div>                │
-│  ErrorStateView  │  <div>                │
-│  DateView        │  <div>                │
-│  EmptyStateView  │  <span>               │
-└──────────────────────────────────────────┘
-
-Category B — Custom Component Root (~72+ components)
-┌──────────────────────────────────────────┐
-│  Component       │  Root Element         │
-│──────────────────┼───────────────────────│
-│  ButtonView      │  <Button>             │
-│  TextView        │  <Typography>         │
-│  SectionView     │  <Section>            │
-│  CheckboxView    │  <FieldItem>          │
-│  SwitchView      │  <Switch>             │
-│  TagsView        │  <TagList>            │
-│  LinkView        │  <TableLink>          │
-└──────────────────────────────────────────┘
-
-PartWrapper wraps BOTH categories identically:
-  <PartWrapper part="x" content={<AnyCategoryComponent />} />
-```
-
-### CSS Targeting Strategy
-
-```
-TODAY (Light DOM):
-
-  Layout CSS                    DOM
-  ─────────────                 ───
-  [data-part="field"] {    →    <div data-part="field">
-    padding: 12px;                <TextBox />
-  }                             </div>
-
-
-FUTURE (Shadow DOM):
-
-  Layout CSS                    Shadow DOM
-  ─────────────                 ──────────
-  my-form::part(field) {   →    #shadow-root
-    padding: 12px;                <div part="field">
-  }                                 <TextBox />
-                                  </div>
-
-  Switch CSS selectors only — zero component code changes.
-```
-
----
-
-## 3. Approaches
-
-### Approach 1: Modify Legacy Components Directly
-
-Add a `part` prop to each legacy component so it renders `part="..."` on its root element.
-
-```tsx
-// ❌ Would need to change ButtonView.tsx, TextView.tsx, etc.
-function ButtonView({ state }, ref) {
-  return <Button part={state.properties.part} ... />;
-}
-```
-
-**Usage:**
-```tsx
-<Button part="action-button" text="Save" />
-```
-
-**Why rejected:**
-- Violates ADR UI-STYLE-003 — must NOT modify legacy components
-- Every legacy component (80+) needs changes
-- High risk — legacy components are reused across the entire app
-
----
-
-### Approach 2: Higher-Order Component (HOC)
-
-Create a function that wraps a component at **definition time**.
-
-```tsx
-// Create a wrapped version of Button
-const WrappedButton = withPartWrapper(Button, 'action-button');
-
-function withPartWrapper(Component, partName) {
-  return function Wrapper(props) {
-    return (
-      <div part={partName} data-part={partName}>
-        <Component {...props} />
-      </div>
-    );
-  };
-}
-```
-
-**Usage:**
-```tsx
-const WrappedButton = withPartWrapper(Button, 'action-button');
-const WrappedText = withPartWrapper(Text, 'label');
-
-// In layout:
-<WrappedButton text="Save" />
-<WrappedText text="Hello" />
-```
-
-**Why rejected:**
-- Does not follow ACA folder structure (domain/applications/frameworks)
-- Part name is fixed at definition time — not flexible in layout Views
-- Need to create a wrapped version for every component you use
-
----
-
-### Approach 3: Simple `forwardRef` Component
-
-Create a lightweight React component using `forwardRef` (same pattern as existing `FieldItem` component).
-
-```tsx
-import React, { forwardRef } from 'react';
-
-const PartWrapper = forwardRef(({ part, tagName = 'div', className, children }, ref) => {
-  const Element = tagName;
-  return (
-    <Element ref={ref} part={part} data-part={part} className={className}>
-      {children}
-    </Element>
-  );
-});
-```
-
-**Usage:**
-```tsx
-<PartWrapper part="field-container">
-  <TextBox id="name" label="Name" />
-</PartWrapper>
-
-<PartWrapper part="action-button">
-  <Button text="Save" />
-</PartWrapper>
-```
-
-**Pros:**
-- Simple and easy to understand
-- Uses natural React `children` pattern (`<Wrapper>...</Wrapper>`)
-- Zero changes to existing components
-
-**Why rejected:**
-- Does NOT use `createCustomComponent`
-- Bypasses the ACA lifecycle (no controller, presenter, state management)
-- Not strictly ACA-compliant
-
----
-
-### Approach 4: `createCustomComponent` + `content` Property — ✅ Selected
-
-Create a proper ACA component using `createCustomComponent` with the Factory pattern (same pattern as `SmartActionBand`). Inner components are passed via a **`content` property** instead of React `children`.
-
-```tsx
-// Entry point — PartWrapper.tsx
-import PartWrapperFactory from './PartWrapperFactory';
-const PartWrapper = PartWrapperFactory.create({ name: 'PartWrapper' });
-export default PartWrapper;
-```
-
-```tsx
-// Factory — PartWrapperFactory.ts
-import { createCustomComponent } from '@library/custom-component';
-import PartWrapperPropertiesSchema from '../../domain/entities/interfaces/Properties';
-import PartWrapperView from './PartWrapperView';
-
-export default class PartWrapperFactory {
-  static create({ name = 'PartWrapper', View = PartWrapperView } = {}) {
-    return createCustomComponent({
-      name,
-      View,
-      properties: PartWrapperPropertiesSchema,
-      eventHandlers: {}
-    });
-  }
-}
-```
-
-```tsx
-// View — PartWrapperView.tsx
-import React from 'react';
-import style from './css/PartWrapper.module.css';
-
-function PartWrapperView({ state }: any, ref: any) {
-  const { part, tagName = 'div', className, content } = state.properties;
-  const Element = tagName;
-  const combinedClassName = className
-    ? `${style.partWrapper} ${className}`
-    : style.partWrapper;
-
-  return (
-    <Element ref={ref} part={part} data-part={part} className={combinedClassName}>
-      {content}
-    </Element>
-  );
-}
-export default PartWrapperView;
-```
-
-```css
-/* PartWrapper.module.css */
-.partWrapper {
-  display: contents;  /* Makes the wrapper invisible to layout */
-}
-```
-
-**Usage:**
-```tsx
-{/* Wrap a form field */}
-<PartWrapper part="field-container" content={<TextBox id="name" label="Name" />} />
-
-{/* Wrap a button */}
-<PartWrapper part="primary-action" content={<Button text="Save" />} />
-
-{/* Nesting wrappers */}
-<PartWrapper part="action-bar" content={
-  <div className={style.actions}>
-    <PartWrapper part="primary-action" content={<Button text="Save" />} />
-    <PartWrapper part="secondary-action" content={<Button text="Cancel" />} />
-  </div>
-} />
-
-{/* Custom HTML element for the wrapper */}
-<PartWrapper part="page-footer" tagName="footer" content={<Text text="Footer" />} />
-```
-
-**CSS targeting:**
-```css
-[data-part="field-container"] {
-  padding: 12px 16px;
-  border-bottom: 1px solid #f0f0f0;
-}
-[data-part="field-container"]:hover {
-  background-color: #f8f9fa;
-}
-[data-part="field-container"]:focus-within {
-  outline: 2px solid #4a90d9;
-}
-```
-
----
-
-## 4. Why `content` Prop Instead of `children`?
-
-This is the most important technical detail to understand.
-
-**The problem:** `createCustomComponent` internally calls a function called `discardChildren()`:
-
-```typescript
-// Inside CreateCustomComponent.tsx
-function discardChildren(props) {
-  const newObject = { ...props };
-  delete newObject.children;    // ← removes children!
-  return newObject;
-}
-```
-
-If we write `<PartWrapper>children here</PartWrapper>`, React puts `children here` into `props.children`. But `discardChildren()` **deletes** it before it reaches the View.
-
-The deleted children are sent to a **slot system** which requires each child to have `slotName` and `displayName` properties — which legacy components (TextBox, Button, etc.) don't have.
-
-**The solution:** Use a property called `content` instead. Since it's not named `children`, `discardChildren()` leaves it alone:
-
-```
-<PartWrapper content={<TextBox />} />
-
-props = { part: "field", content: <TextBox /> }
-              ↓
-discardChildren(props)   → deletes props.children (doesn't exist, no-op)
-              ↓
-state.properties = { part: "field", content: <TextBox /> }   ← content survives!
-              ↓
-View receives state.properties.content   ← renders correctly!
-```
-
----
-
-## 5. Approach Comparison Table
-
-| Criteria | Approach 1 (Modify Legacy) | Approach 2 (HOC) | Approach 3 (forwardRef) | Approach 4 (createCustomComponent) ✅ |
-|---|---|---|---|---|
-| Modifies existing code | ❌ Yes | ✅ No | ✅ No | ✅ No |
-| ACA structure | N/A | ❌ No | ⚠️ Partial | ✅ Full |
-| Uses `createCustomComponent` | N/A | ❌ No | ❌ No | ✅ Yes |
-| Dynamic part names | ✅ Yes | ❌ Fixed at definition | ✅ Yes | ✅ Yes |
-| Natural API | ✅ Built-in prop | ⚠️ Pre-wrapped | ✅ Children | ⚠️ `content` prop |
-| Shadow DOM ready | ⚠️ Partial | ✅ Yes | ✅ Yes | ✅ Yes |
-| Risk level | 🔴 High | 🟡 Medium | 🟢 Low | 🟢 Low |
-
----
-
-## 6. POC Examples
-
-### Example 1: Form Layout (Category B components)
-
-Wraps form field components that have custom component roots (`FieldItem`).
-
-```tsx
-// POCFormLayout.tsx
-<div className={style.formLayout}>
-  <PartWrapper
-    part="field-container"
-    content={<TextBox id="name" label="Name" value="" placeholder="Enter name" />}
-  />
-  <PartWrapper
-    part="field-container"
-    content={<Email id="email" label="Email Address" value="" />}
-  />
-  <PartWrapper
-    part="field-container"
-    content={<PickList id="status" label="Status" value="" options={[]} />}
-  />
-</div>
-```
-
-```css
-/* poc-form-layout.module.css */
-.formLayout [data-part="field-container"] {
-  padding: 12px 16px;
-  border-bottom: 1px solid #f0f0f0;
-}
-.formLayout [data-part="field-container"]:hover {
-  background-color: #f8f9fa;
-}
-.formLayout [data-part="field-container"]:focus-within {
-  outline: 2px solid #4a90d9;
-}
-```
-
-### Example 2: Table Cells (Category B components)
-
-Wraps different cell types with unique part names for granular styling.
-
-```tsx
-// POCTableCellLayout.tsx
-<div className={style.tableRow}>
-  <PartWrapper part="cell-text"   content={<Text text="Sample" />} />
-  <PartWrapper part="cell-tags"   content={<Tags tags={[{ id: '1', label: 'Tag A' }]} />} />
-  <PartWrapper part="cell-switch" content={<Switch checked={false} />} />
-  <PartWrapper part="cell-link"   content={<Link text="View" href="#" />} />
-  <PartWrapper part="cell-email"  content={<Email email="user@example.com" />} />
-</div>
-```
-
-```css
-/* poc-table-cell-layout.module.css */
-.tableRow [data-part^="cell-"]       { padding: 8px 12px; flex: 1; }
-.tableRow [data-part="cell-text"]    { text-align: left; flex: 2; }
-.tableRow [data-part="cell-tags"]    { max-width: 220px; overflow: hidden; }
-.tableRow [data-part="cell-switch"]  { display: flex; justify-content: center; flex: 0 0 80px; }
-```
-
-### Example 3: Mixed Layout (Category A + B components)
-
-Wraps both HTML-root (Category A) and custom-root (Category B) components — proving the wrapper is agnostic to inner component type.
-
-```tsx
-// POCMixedLayout.tsx
-<div className={style.pageLayout}>
-
-  {/* Category B: Text component (custom root) */}
-  <PartWrapper part="page-header" content={
-    <div className={style.headerContent}>
-      <PartWrapper part="page-title" content={<Text text="Page Title" size="24" />} />
-      <PartWrapper part="page-description" content={<Text text="Description" size="14" />} />
-    </div>
-  } />
-
-  {/* Category B: Button + ActionIcon (custom roots) */}
-  <PartWrapper part="action-bar" content={
-    <div className={style.actionBarContent}>
-      <PartWrapper part="primary-action" content={<Button text="Create" />} />
-      <PartWrapper part="secondary-action" content={<Button text="Export" />} />
-      <PartWrapper part="icon-action" content={<ActionIcon name="filter" />} />
-    </div>
-  } />
-
-  {/* Content area */}
-  <PartWrapper part="content-area" content={<Text text="Content area" />} />
-
-  {/* Category A: raw HTML (tagName="footer") */}
-  <PartWrapper part="page-footer" tagName="footer" content={
-    <div><Text text="Footer content" size="12" /></div>
-  } />
-
-</div>
-```
-
-```css
-/* poc-mixed-layout.module.css */
-.pageLayout [data-part="page-header"]  { padding: 24px 32px; background: #fff; }
-.pageLayout [data-part="action-bar"]   { padding: 12px 32px; }
-.pageLayout [data-part="content-area"] { flex: 1; padding: 24px 32px; }
-.pageLayout [data-part="page-footer"]  { padding: 12px 32px; border-top: 1px solid #e5e5e5; }
-.pageLayout [data-part="icon-action"]  { margin-left: auto; }
-```
-
----
-
-## 7. What `display: contents` Does
-
-The PartWrapper uses `display: contents` so it doesn't break existing layouts.
-
-**Without `display: contents`:**
-```
-Parent (display: flex)
-  └─ PartWrapper <div>        ← This div breaks the flex layout!
-       └─ TextBox
-```
-
-**With `display: contents`:**
-```
-Parent (display: flex)
-  └─ PartWrapper <div>        ← Invisible to layout — like it's not there
-       └─ TextBox              ← Behaves as direct child of Parent
-```
-
-The wrapper DOM element still exists (so `data-part` works for CSS targeting), but it has **no box** in the layout — children render as if the wrapper isn't there.
-
----
-
-## 8. Dual Attribute Strategy (Future-Proofing)
-
-Both `part` and `data-part` are set on the wrapper element:
-
-```html
-<div part="field-container" data-part="field-container">
-  <TextBox ... />
-</div>
-```
-
-| Attribute | CSS Selector | When to use |
-|---|---|---|
-| `data-part` | `[data-part="field-container"] { }` | **Now** — works in Light DOM |
-| `part` | `::part(field-container) { }` | **Future** — when we adopt Shadow DOM |
-
-When we migrate to Shadow DOM, we switch CSS selectors from `[data-part="x"]` to `::part(x)` — no component code changes needed.
-
----
-
-## 9. Known Limitations
-
-| Limitation | Why it exists | Workaround |
-|---|---|---|
-| Uses `content` prop instead of `children` | `createCustomComponent` deletes `children` internally | This is the only way with `createCustomComponent` — document clearly |
-| `display: contents` may affect screen readers | Some assistive tech skips elements with `display: contents` | Add `role="presentation"` if needed; requires a11y testing |
-| Can't style inner sub-elements of wrapped components | ADR UI-STYLE-003 says: boundary styling only | By design — keeps wrapper simple and safe |
-| Each wrapper creates an ACA lifecycle instance | Part of using `createCustomComponent` | Overhead is minimal — no behaviours, SDK, or event handlers |
-| Extra DOM node per wrapper | A `<div>` (or custom `tagName`) is added | `display: contents` makes it layout-transparent |
-
----
-
-

package/es/library/dot/components/part-wrapper/applications/interfaces/State.js

@@ -1 +0,0 @@
-export {};