@softize/opus 12.10.0 → 13.0.0

package/src/ui/components/patterns/content-header.tsx

@@ -1,88 +1,362 @@
-import type { ReactNode } from 'react'
-import { cn } from '../../lib/cn.ts'
+import {
+  Children,
+  Fragment,
+  createContext,
+  isValidElement,
+  useContext,
+  useId,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { cn } from "../../lib/cn.ts";
 
-export type ContentHeaderLevel = 1 | 2 | 3 | 4 | 5 | 6
-export type ContentHeaderVariant = 'page' | 'section'
+export type ContentHeaderLevel = 1 | 2 | 3 | 4 | 5 | 6;
+export type ContentHeaderVariant = "page" | "section";
 
-export interface ContentHeaderProps {
-  title: ReactNode
-  /** Conteúdo complementar exibido ao lado do título, como uma contagem. */
-  meta?: ReactNode
-  description?: ReactNode
-  actions?: ReactNode
+interface ContentContextValue {
+  level: ContentHeaderLevel;
+  titleId: string;
+  variant: ContentHeaderVariant;
+}
+
+const ContentContext = createContext<ContentContextValue | null>(null);
+const ContentHeaderContext = createContext<ContentContextValue | null>(null);
+
+function requiredContext<T>(
+  value: T | null,
+  component: string,
+  parent: string,
+): T {
+  if (value === null)
+    throw new Error(`${component} deve estar dentro de ${parent}.`);
+  return value;
+}
+
+interface ContentBaseProps extends Omit<
+  HTMLAttributes<HTMLElement>,
+  "children" | "title"
+> {
   /** Nível semântico do heading, independente de seu destaque visual. */
-  level?: ContentHeaderLevel
-  /** Hierarquia visual: destaque principal ou cabeçalho interno de seção. */
-  variant?: ContentHeaderVariant
-  className?: string
+  level?: ContentHeaderLevel;
+  /** Hierarquia visual. `page` permanece somente para compatibilidade durante a versão 12. */
+  variant?: ContentHeaderVariant;
 }
 
-interface ContentHeaderSlots {
-  root?: string
-  heading: string
-  actions: string
+interface ContentShorthandProps extends ContentBaseProps {
+  title: ReactNode;
+  /** Conteúdo complementar exibido ao lado do título, como uma contagem. */
+  meta?: ReactNode;
+  description?: ReactNode;
+  actions?: ReactNode;
+  children: ReactNode;
 }
 
-interface ContentHeaderFrameProps extends ContentHeaderProps {
-  slots: ContentHeaderSlots
+interface ContentComposedProps extends ContentBaseProps {
+  title?: never;
+  meta?: never;
+  description?: never;
+  actions?: never;
+  children: ReactNode;
 }
 
-const headingTags = {
-  1: 'h1',
-  2: 'h2',
-  3: 'h3',
-  4: 'h4',
-  5: 'h5',
-  6: 'h6',
-} as const
-
-/** Layout compartilhado com Page; mantém os slots históricos sem expô-los na API pública. */
-export function ContentHeaderFrame({
+export type ContentProps = ContentShorthandProps | ContentComposedProps;
+
+/** Região de conteúdo nomeada. A forma curta e a explícita produzem a mesma anatomia. */
+export function Content({
   title,
   meta,
   description,
   actions,
   level = 2,
-  variant = 'section',
+  variant = "section",
+  children,
   className,
-  slots,
-}: ContentHeaderFrameProps): React.ReactElement {
-  const Heading = headingTags[level]
-  const page = variant === 'page'
+  ...props
+}: ContentProps): ReactElement {
+  const titleId = useId();
+  const context = { level, titleId, variant };
+  const shorthand = title !== undefined;
+  const nodes = Children.toArray(children);
+
+  if (
+    shorthand &&
+    nodes.some((node) => isValidElement(node) && node.type === ContentHeader)
+  ) {
+    throw new Error(
+      "Content não permite misturar propriedades de shorthand com ContentHeader explícito.",
+    );
+  }
+  if (!shorthand) {
+    const headers = nodes.filter(
+      (node) => isValidElement(node) && node.type === ContentHeader,
+    );
+    const bodies = nodes.filter(
+      (node) => isValidElement(node) && node.type === ContentBody,
+    );
+    if (
+      headers.length !== 1 ||
+      bodies.length !== 1 ||
+      headers.length + bodies.length !== nodes.length
+    ) {
+      throw new Error(
+        "Content explícito exige exatamente um ContentHeader e um ContentBody como filhos diretos.",
+      );
+    }
+  }
 
   return (
-    <div
-      {...(slots.root === undefined ? {} : { 'data-slot': slots.root })}
-      className={cn(actions !== undefined && 'flex items-end justify-between gap-4', className)}
-    >
-      <div data-slot={slots.heading} className="min-w-0">
-        <Heading
-          className={cn(
-            'flex items-baseline gap-2 font-semibold',
-            page ? 'text-2xl tracking-tight' : 'text-sm',
-          )}
-        >
-          {title}
-          {meta}
-        </Heading>
+    <ContentContext.Provider value={context}>
+      <section
+        data-slot="content"
+        aria-labelledby={
+          props["aria-label"] === undefined ? titleId : undefined
+        }
+        className={cn("space-y-3", className)}
+        {...props}
+      >
+        {shorthand ? (
+          <>
+            <ContentHeader>
+              <ContentTitle>{title}</ContentTitle>
+              {meta !== undefined && <ContentMeta>{meta}</ContentMeta>}
+              {description !== undefined && (
+                <ContentDescription>{description}</ContentDescription>
+              )}
+              {actions !== undefined && (
+                <ContentActions>{actions}</ContentActions>
+              )}
+            </ContentHeader>
+            <ContentBody>{children}</ContentBody>
+          </>
+        ) : (
+          children
+        )}
+      </section>
+    </ContentContext.Provider>
+  );
+}
+
+interface ContentHeaderShorthandProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "children" | "title"
+> {
+  /** @deprecated Prefira os slots explícitos ou o shorthand de Content. */
+  title: ReactNode;
+  meta?: ReactNode;
+  description?: ReactNode;
+  actions?: ReactNode;
+  /** @deprecated Declare o nível em Content. Compatibilidade da série 12. */
+  level?: ContentHeaderLevel;
+  /** @deprecated Declare a hierarquia visual em Content. Compatibilidade da série 12. */
+  variant?: ContentHeaderVariant;
+  children?: never;
+}
+
+interface ContentHeaderComposedProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "title"
+> {
+  /** @deprecated Declare o nível em Content. Compatibilidade da série 12. */
+  level?: ContentHeaderLevel;
+  /** @deprecated Declare a hierarquia visual em Content. Compatibilidade da série 12. */
+  variant?: ContentHeaderVariant;
+  title?: never;
+  meta?: never;
+  description?: never;
+  actions?: never;
+  children: ReactNode;
+}
+
+export type ContentHeaderProps =
+  ContentHeaderShorthandProps | ContentHeaderComposedProps;
+
+/** Header estrutural de Content; não é uma região autônoma. */
+export function ContentHeader({
+  title,
+  meta,
+  description,
+  actions,
+  level,
+  variant,
+  children,
+  className,
+  ...props
+}: ContentHeaderProps): ReactElement {
+  const parent = useContext(ContentContext);
+  const standaloneTitleId = useId();
+  const shorthand = title !== undefined;
+  if (parent === null && !shorthand) {
+    throw new Error("ContentHeader deve estar dentro de Content.");
+  }
+  const content: ContentContextValue = {
+    level: level ?? parent?.level ?? 2,
+    titleId: parent?.titleId ?? standaloneTitleId,
+    variant: variant ?? parent?.variant ?? "section",
+  };
+  const nodes = Children.toArray(
+    shorthand ? (
+      <>
+        <ContentTitle>{title}</ContentTitle>
+        {meta !== undefined && <ContentMeta>{meta}</ContentMeta>}
         {description !== undefined && (
-          <p className={cn('truncate text-muted-foreground', page ? 'mt-1 text-sm' : 'mt-0.5 text-xs')}>{description}</p>
+          <ContentDescription>{description}</ContentDescription>
         )}
-      </div>
-      {actions !== undefined && (
-        <div data-slot={slots.actions} className={cn('flex shrink-0 items-center', page ? 'gap-4' : 'gap-2')}>
-          {actions}
+        {actions !== undefined && <ContentActions>{actions}</ContentActions>}
+      </>
+    ) : (
+      children
+    ),
+  ).flatMap((node) =>
+    isValidElement(node) && node.type === Fragment
+      ? Children.toArray((node.props as { children?: ReactNode }).children)
+      : [node],
+  );
+  const titles = nodes.filter(
+    (node) => isValidElement(node) && node.type === ContentTitle,
+  );
+  const metas = nodes.filter(
+    (node) => isValidElement(node) && node.type === ContentMeta,
+  );
+  const descriptions = nodes.filter(
+    (node) => isValidElement(node) && node.type === ContentDescription,
+  );
+  const actionSlots = nodes.filter(
+    (node) => isValidElement(node) && node.type === ContentActions,
+  );
+  const recognized =
+    titles.length + metas.length + descriptions.length + actionSlots.length;
+
+  if (
+    titles.length !== 1 ||
+    metas.length > 1 ||
+    descriptions.length > 1 ||
+    actionSlots.length > 1 ||
+    recognized !== nodes.length
+  ) {
+    throw new Error(
+      "ContentHeader exige um ContentTitle e aceita no máximo um ContentDescription, ContentMeta e ContentActions como filhos diretos.",
+    );
+  }
+
+  return (
+    <ContentHeaderContext.Provider value={content}>
+      <div
+        data-slot="content-header"
+        className={cn(
+          actionSlots.length > 0 &&
+            "flex flex-col items-start gap-4 sm:flex-row sm:items-end sm:justify-between",
+          className,
+        )}
+        {...props}
+      >
+        <div data-slot="content-header-heading" className="min-w-0">
+          <div className="flex items-baseline gap-2">
+            {titles}
+            {metas}
+          </div>
+          {descriptions}
         </div>
+        {actionSlots}
+      </div>
+    </ContentHeaderContext.Provider>
+  );
+}
+
+const headingTags = {
+  1: "h1",
+  2: "h2",
+  3: "h3",
+  4: "h4",
+  5: "h5",
+  6: "h6",
+} as const;
+
+export function ContentTitle({
+  className,
+  id,
+  ...props
+}: HTMLAttributes<HTMLHeadingElement>): ReactElement {
+  const context = requiredContext(
+    useContext(ContentHeaderContext),
+    "ContentTitle",
+    "ContentHeader",
+  );
+  const Heading = headingTags[context.level];
+  return (
+    <Heading
+      id={id ?? context.titleId}
+      data-slot="content-title"
+      className={cn(
+        "font-semibold",
+        context.variant === "page" ? "text-2xl tracking-tight" : "text-sm",
+        className,
       )}
-    </div>
-  )
+      {...props}
+    />
+  );
 }
 
-export function ContentHeader(props: ContentHeaderProps): React.ReactElement {
+export function ContentDescription({
+  className,
+  ...props
+}: HTMLAttributes<HTMLParagraphElement>): ReactElement {
+  const context = requiredContext(
+    useContext(ContentHeaderContext),
+    "ContentDescription",
+    "ContentHeader",
+  );
   return (
-    <ContentHeaderFrame
+    <p
+      data-slot="content-description"
+      className={cn(
+        "truncate text-muted-foreground",
+        context.variant === "page" ? "mt-1 text-sm" : "mt-0.5 text-xs",
+        className,
+      )}
       {...props}
-      slots={{ root: 'content-header', heading: 'content-header-heading', actions: 'content-header-actions' }}
     />
-  )
+  );
+}
+
+export function ContentMeta({
+  className,
+  ...props
+}: HTMLAttributes<HTMLSpanElement>): ReactElement {
+  requiredContext(
+    useContext(ContentHeaderContext),
+    "ContentMeta",
+    "ContentHeader",
+  );
+  return <span data-slot="content-meta" className={className} {...props} />;
+}
+
+export function ContentActions({
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>): ReactElement {
+  const context = requiredContext(
+    useContext(ContentHeaderContext),
+    "ContentActions",
+    "ContentHeader",
+  );
+  return (
+    <div
+      data-slot="content-actions"
+      className={cn(
+        "flex w-full shrink-0 items-center sm:w-auto",
+        context.variant === "page" ? "gap-4" : "gap-2",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function ContentBody({
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>): ReactElement {
+  requiredContext(useContext(ContentContext), "ContentBody", "Content");
+  return <div data-slot="content-body" className={className} {...props} />;
 }

package/src/ui/components/patterns/data-state.tsx

@@ -9,6 +9,7 @@
  */
 import * as React from 'react'
 import { cn } from '../../lib/cn.ts'
+import { Alert } from '../primitives/alert.tsx'
 import { Button } from '../primitives/button.tsx'
 import { Spinner } from '../primitives/spinner.tsx'
 
@@ -50,8 +51,9 @@ export function DataState({
 
   // Modo TABELA: o estado vira UMA linha de largura cheia (<td colSpan>), pra caber no <tbody>.
   if (colSpan !== undefined) {
+    const status = error ? 'error' : loading ? 'loading' : 'empty'
     return (
-      <tr>
+      <tr data-slot="data-state" data-status={status}>
         <td
           colSpan={colSpan}
           className={cn('px-4 py-10 text-center text-sm', error ? 'text-destructive' : 'text-muted-foreground/60')}
@@ -78,25 +80,36 @@ export function DataState({
   // Modo BLOCO (default).
   if (error) {
     return (
-      <div className="flex flex-col items-center gap-3 rounded-lg border border-destructive/30 bg-destructive/5 px-4 py-3 text-center text-sm text-destructive">
-        <span>{errorText ?? 'Não foi possível carregar.'}</span>
-        {onRetry !== undefined && (
-          <Button variant="outline" size="sm" onClick={() => void onRetry()}>
-            {retryText}
-          </Button>
-        )}
+      <div data-slot="data-state" data-status="error">
+        <Alert context="danger" description={errorText ?? 'Não foi possível carregar.'}>
+          {onRetry !== undefined && (
+            <Button variant="outline" size="sm" onClick={() => void onRetry()}>
+              {retryText}
+            </Button>
+          )}
+        </Alert>
       </div>
     )
   }
   if (loading) {
     return (
-      <div className="py-10 text-center text-muted-foreground">
+      <div
+        data-slot="data-state"
+        data-status="loading"
+        role="status"
+        aria-live="polite"
+        className="py-10 text-center text-muted-foreground"
+      >
         <Spinner className="mx-auto" />
       </div>
     )
   }
   return (
-    <p className="rounded-lg border border-border py-10 text-center text-sm text-muted-foreground/60">
+    <p
+      data-slot="data-state"
+      data-status="empty"
+      className="rounded-lg border border-border py-10 text-center text-sm text-muted-foreground/60"
+    >
       {emptyText}
     </p>
   )