@softize/opus 12.0.0 → 12.0.1

package/CHANGELOG.md

@@ -7,6 +7,18 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 12.0.1 — 2026-08-22
+
+`Split` volta a atender layouts que precisam preservar uma medida física e a preferência da
+pessoa entre visitas. `Pane.initialSize`, `minSize` e `maxSize` agora aceitam `%`, `rem`, `em`,
+`vh`, `vw` e `px`, enquanto valores numéricos continuam representando porcentagens por
+compatibilidade. `Split` também expõe `id`, `defaultLayout` e `onLayoutChanged`, e cada `Pane`
+pode declarar um `id` estável. Assim, a aplicação pode restaurar e persistir o layout em
+`localStorage`, `sessionStorage` ou outra camada sem voltar aos primitives removidos na 11.0.0.
+
+A mudança é aditiva. Separadores continuam acessíveis por teclado, e consumidores que usam
+apenas tamanhos percentuais não precisam alterar o código.
+
 ## 12.0.0 — 2026-08-21
 
 **Copy declarativa passa a ter inventário semântico e gate reproduzível.** `opus copy`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "12.0.0",
+  "version": "12.0.1",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/ui/components/patterns/split.tsx

@@ -2,13 +2,21 @@ import { Children, isValidElement, type CSSProperties, type ReactElement, type R
 import { cn } from '../../lib/cn.ts'
 import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '../primitives/resizable.tsx'
 
+export type PaneSize = number | `${number}%` | `${number}rem` | `${number}em` | `${number}vh` | `${number}vw` | `${number}px`
+export type SplitLayout = Record<string, number>
+export interface SplitLayoutChange {
+  isUserInteraction: boolean
+}
+
 export interface PaneProps {
-  /** Fração inicial do split, em %. O pane que cresce recebe o restante. */
-  initialSize?: number
-  /** Fração mínima, em %, quando o split é redimensionável. */
-  minSize?: number
-  /** Fração máxima, em %, quando o split é redimensionável. */
-  maxSize?: number
+  /** Identidade estável usada pelo layout redimensionável e por layouts persistidos. */
+  id?: string
+  /** Tamanho inicial. Números representam porcentagens; strings aceitam %, rem, em, vh, vw e px. */
+  initialSize?: PaneSize
+  /** Tamanho mínimo quando o split é redimensionável. */
+  minSize?: PaneSize
+  /** Tamanho máximo quando o split é redimensionável. */
+  maxSize?: PaneSize
   /** Ocupa o espaço remanescente no layout simples. */
   grow?: boolean
   /** Respiro interno padrão. Use `none` para chrome, navegação ou conteúdo com inset próprio. */
@@ -18,21 +26,27 @@ export interface PaneProps {
 }
 
 /** Um conteúdo encaixável. Sua posição é dada pela ordem dentro de <Split>. */
-export function Pane({ initialSize, grow = false, inset = 'md', className, children }: PaneProps): React.ReactElement {
-  const style: CSSProperties | undefined = initialSize === undefined ? undefined : { flexBasis: `${initialSize}%` }
+export function Pane({ id, initialSize, grow = false, inset = 'md', className, children }: PaneProps): React.ReactElement {
+  const style: CSSProperties | undefined = initialSize === undefined ? undefined : { flexBasis: sizeToCss(initialSize) }
   const insets = { none: '', sm: 'p-2', md: 'p-4', lg: 'p-6' } as const
   return (
-    <div data-slot="pane" data-inset={inset} className={cn('min-h-0 min-w-0 shrink-0', grow && 'flex-1', insets[inset], className)} style={style}>
+    <div id={id === undefined ? undefined : String(id)} data-slot="pane" data-inset={inset} className={cn('min-h-0 min-w-0 shrink-0', grow && 'flex-1', insets[inset], className)} style={style}>
       {children}
     </div>
   )
 }
 
 export interface SplitProps {
+  /** Identidade estável do grupo redimensionável. */
+  id?: string
   direction?: 'horizontal' | 'vertical'
-  /** Quando ligado, cada fronteira ganha um handle e os tamanhos passam a ser percentuais. */
+  /** Quando ligado, cada fronteira ganha um separador acessível e arrastável. */
   resizable?: boolean
   handle?: boolean
+  /** Layout percentual restaurado, indexado pelos ids dos panes. */
+  defaultLayout?: SplitLayout
+  /** Chamado ao concluir uma mudança de layout; pode persistir o resultado em localStorage. */
+  onLayoutChanged?: (layout: SplitLayout, meta: SplitLayoutChange) => void
   className?: string
   children: ReactNode
 }
@@ -43,11 +57,20 @@ function panesOf(children: ReactNode): ReactElement<PaneProps>[] {
   )
 }
 
-// react-resizable-panels v4 interpreta `number` como pixels. O contrato de Split/Pane
-// é percentual (e o layout flex simples abaixo também usa `%`), então a unidade precisa
-// ser explícita na fronteira com o primitive.
-function percent(value: number | undefined): string | undefined {
-  return value === undefined ? undefined : `${value}%`
+// Números continuam percentuais por compatibilidade com Split/Pane. Strings preservam
+// a unidade explícita para layouts que precisam de um limite físico, como `28rem`.
+function sizeToCss(value: PaneSize): string {
+  return typeof value === 'number' ? `${value}%` : value
+}
+
+function resizableSize(value: PaneSize | undefined): string | undefined {
+  return value === undefined ? undefined : sizeToCss(value)
+}
+
+function percentage(value: PaneSize | undefined): number | undefined {
+  if (typeof value === 'number') return value
+  if (value?.endsWith('%')) return Number.parseFloat(value)
+  return undefined
 }
 
 /**
@@ -55,35 +78,54 @@ function percent(value: number | undefined): string | undefined {
  * quando fixa e o primitive Resizable quando `resizable`; quem consome não troca de
  * modelo de layout para ganhar arraste.
  */
-export function Split({ direction = 'horizontal', resizable = false, handle = false, className, children }: SplitProps): React.ReactElement {
+export function Split({
+  id,
+  direction = 'horizontal',
+  resizable = false,
+  handle = false,
+  defaultLayout,
+  onLayoutChanged,
+  className,
+  children,
+}: SplitProps): React.ReactElement {
   const panes = panesOf(children)
   const vertical = direction === 'vertical'
 
   if (!resizable) {
     return (
-      <div data-slot="split" data-direction={direction} className={cn('flex min-h-0 min-w-0 flex-1', vertical && 'flex-col', className)}>
+      <div id={id === undefined ? undefined : String(id)} data-slot="split" data-direction={direction} className={cn('flex min-h-0 min-w-0 flex-1', vertical && 'flex-col', className)}>
         {panes}
       </div>
     )
   }
 
-  const fixed = panes.reduce((sum, pane) => sum + (pane.props.initialSize ?? 0), 0)
+  const fixed = panes.reduce((sum, pane) => sum + (percentage(pane.props.initialSize) ?? 0), 0)
+  const hasAbsoluteSize = panes.some((pane) => typeof pane.props.initialSize === 'string' && !pane.props.initialSize.endsWith('%'))
   const growing = panes.filter((pane) => pane.props.grow)
   const rest = Math.max(0, 100 - fixed)
   const fallback = panes.length === 0 ? 100 : 100 / panes.length
 
   return (
-    <ResizablePanelGroup orientation={direction} data-slot="split" className={cn('min-h-0 min-w-0 flex-1', className)}>
+    <ResizablePanelGroup
+      id={id}
+      orientation={direction}
+      defaultLayout={defaultLayout}
+      onLayoutChanged={onLayoutChanged}
+      data-slot="split"
+      className={cn('min-h-0 min-w-0 flex-1', className)}
+    >
       {panes.flatMap((pane, index) => {
-        const size = pane.props.initialSize ?? (pane.props.grow ? rest / Math.max(1, growing.length) : fallback)
+        const size = pane.props.initialSize
+          ?? (hasAbsoluteSize ? undefined : pane.props.grow ? rest / Math.max(1, growing.length) : fallback)
         const panel = (
           <ResizablePanel
             key={pane.key ?? index}
-            defaultSize={percent(size)}
-            minSize={percent(pane.props.minSize)}
-            maxSize={percent(pane.props.maxSize)}
+            id={pane.props.id}
+            defaultSize={resizableSize(size)}
+            minSize={resizableSize(pane.props.minSize)}
+            maxSize={resizableSize(pane.props.maxSize)}
           >
-            <Pane {...pane.props} className={cn('h-full w-full', pane.props.className)} />
+            <Pane {...pane.props} id={undefined} className={cn('h-full w-full', pane.props.className)} />
           </ResizablePanel>
         )
         return index === 0 ? [panel] : [<ResizableHandle key={`handle-${pane.key ?? index}`} withHandle={handle} />, panel]

package/src/ui/docs/content/split.md

@@ -1,6 +1,6 @@
 ## Split & Pane
 
-`Split` é o primitive espacial da UI. A ordem dos `Pane` define esquerda→direita (ou cima→baixo); o pane não sabe onde está. Sem `resizable`, é flex simples. Com ele, a fronteira vira arrastável sem trocar o modelo do componente.
+`Split` organiza áreas lado a lado ou uma sobre a outra. A ordem dos `Pane` define a posição de cada área. Sem `resizable`, o layout usa flex; com essa opção, a pessoa também pode ajustar as divisórias com ponteiro ou teclado.
 
 ```tsx preview
 render(
@@ -23,11 +23,51 @@ O `Pane` traz `inset="md"` por default. Use `none` para chrome, navegação e co
 
 ## Rail
 
-Um rail não é uma prop especial: é só o último pane.
+Quando uma área precisa continuar legível em telas largas, use uma unidade absoluta para o tamanho inicial ou mínimo. Números continuam representando porcentagens; strings aceitam `%`, `rem`, `em`, `vh`, `vw` e `px`. Prefira `rem` para acompanhar a escala tipográfica configurada pela aplicação.
 
 ```tsx
 <Split resizable>
   <Pane grow inset="none"><Main /></Pane>
-  <Pane initialSize={28} minSize={20} inset="none"><Inspector /></Pane>
+  <Pane initialSize="28rem" minSize="20rem" inset="none"><Inspector /></Pane>
 </Split>
 ```
+
+## Persistência
+
+Um layout pode ser restaurado sem acoplar `Split` a um mecanismo específico de armazenamento. Dê um `id` estável a cada `Pane`, leia o valor salvo para formar `defaultLayout` e persista apenas mudanças concluídas pela pessoa.
+
+```tsx
+function readLayout(key: string): SplitLayout | undefined {
+  if (typeof window === 'undefined') return undefined
+
+  try {
+    const parsed: unknown = JSON.parse(localStorage.getItem(key) ?? 'null')
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined
+    const entries = Object.entries(parsed)
+    const valid = entries.every(([id, size]) =>
+      id !== '' && typeof size === 'number' && Number.isFinite(size) && size >= 0 && size <= 100,
+    )
+    return valid ? Object.fromEntries(entries) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const defaultLayout = readLayout('workspace-layout')
+
+<Split
+  id="workspace"
+  resizable
+  defaultLayout={defaultLayout}
+  onLayoutChanged={(layout, meta) => {
+    if (meta.isUserInteraction) {
+      localStorage.setItem('workspace-layout', JSON.stringify(layout))
+    }
+  }}
+>
+  <Pane id="navigation" initialSize="28rem" minSize="28rem"><Navigation /></Pane>
+  <Pane id="content" grow><Content /></Pane>
+</Split>
+```
+
+Em aplicações renderizadas no servidor, leia o armazenamento somente no cliente. `onLayoutChanged` também permite usar `sessionStorage` ou uma camada própria quando o layout precisa acompanhar outro escopo.

package/src/ui/react.tsx

@@ -207,7 +207,7 @@ export type { PageProps } from './components/patterns/page.tsx'
 
 // Layout composicional: Split decide a relação espacial; Pane carrega conteúdo com inset.
 export { Split, Pane } from './components/patterns/split.tsx'
-export type { SplitProps, PaneProps } from './components/patterns/split.tsx'
+export type { SplitProps, PaneProps, PaneSize, SplitLayout, SplitLayoutChange } from './components/patterns/split.tsx'
 
 // Barra lateral composicional: header/conteúdo/footer e navegação, sem possuir o layout.
 export { PaneHeader, PaneContent, PaneFooter, Sidebar, SidebarItem, SidebarNav } from './components/patterns/sidebar.tsx'