GroupFrame

Examples #

'use client';

import { Capsule, GroupFrame } from '@coreux/ui';

export default function Default() {
  return (
    <figure style={{ margin: 0, width: 340, boxSizing: 'border-box', background: '#F4F1E9', color: '#0B1221', padding: 32 }}>
      <GroupFrame heading="Strategy">
        <div style={{ display: 'flex', gap: 8 }}>
          <Capsule primary="Align" />
          <Capsule primary="Design" />
        </div>
      </GroupFrame>
      <figcaption style={{ marginTop: 16, fontSize: 14, lineHeight: 1.5 }}>Illustrative strategy activities. The shared boundary groups related work; it does not prescribe a sequence.</figcaption>
    </figure>
  );
}

Choosing a presentation #

Use GroupFrame when a shared boundary helps readers recognize related content. Supply a short concept label, then meaningful content inside it. It provides neither a filled card surface nor an automatic layout for its children. Choose PanelCard for a focused title or metric with named slots, and FramedContent for one small framed marker.

• Solid strategy group keeps the Strategy seed’s Align and Design Capsules, 340 px wrapper and 32 px padding.
• Dashed automation group keeps the seed’s Automation heading, dashed accent boundary and Operate and improve Capsule. It changes the group and Capsule to dark field mode with a navy wrapper because the original accent/light heading is ivory on ivory.
• One nested group shows a Delivery plan containing a Strategy group with a semantic list. The outer solid and inner dashed boundaries clarify this specific composition; they have no built-in meaning.

Related items may be parallel activities rather than ordered steps. Use an actual list when order or grouping should be conveyed semantically, and add an appropriate heading element when the group needs an entry in the document outline. Every example includes its required imports and content; no external assets are needed.

Heading & nesting limits #

• children is required. A React.Children.count of zero throws; this check does not guarantee that a conditional child or fragment renders visible content. Multiple ordinary children are allowed.
• heading is optional. When supplied, it must be a non-empty string on one explicit line and no more than 32 characters by JavaScript string length, including surrounding whitespace. Whitespace-only strings, explicit newlines and longer strings throw.
• The displayed heading is uppercase, single-line and ellipsized to fit the available width. Staying within 32 characters does not guarantee a complete visual label. Choose a short name and verify it at the intended width.
• An outer group has nesting level 0; an inner group has level 1. A third GroupFrame in that ancestor chain throws. The internal React context tracks this even through intervening wrapper elements. Ordinary sibling groups do not add depth to each other.
• boundary, fieldMode and tone must match their supported values. No className, style, width, height or ARIA-forwarding props are exposed.

Nesting depth is the only shared context here. An inner group or Capsule does not inherit the outer component’s fieldMode, tone or progress prop. Pass its own appearance props as needed. No consumer provider is required.

Geometry & appearance #

The section uses width: 100%, height: 100%, border-box sizing, zero minimum width/height, a 2 px border and a 16 px radius. With a heading, padding is 24 px at the top and 16 px on the other sides; without a heading, padding is 16 px throughout. The examples leave parent height unconstrained so content determines the group height. A fixed-height parent makes the group fill that height and may let oversized children overflow; there is no automatic scrolling or clipping for the whole group.

The heading sits 9 px above the top boundary, 16 px from the left, with 8 px horizontal padding and a maximum width of the group minus 32 px. Its type is Switzer at 13 px, weight 600, line height 1.2 and 1.5 px letter spacing. Leave room above the boundary and between nested groups so these labels do not collide with nearby content.

fieldMode sets the body text and the heading’s opaque background patch. The section itself has no background fill. Supply the matching ivory or navy field behind it, or the patch will look disconnected from the surrounding surface. tone changes the border and heading accent; it does not apply a colored surface or change body text. These are video-family rules, described in Color and Spacing & shape.

Accent on light renders the heading in ivory over an ivory patch, so that combination hides the label. The adapted dashed seed uses accent on dark: ivory heading text over navy, with a cornflower boundary. Neutral light and neutral dark are readable alternatives. Positive, warning and error are accepted tones, but their colored 13 px headings do not all meet small-text contrast on every field; check the actual pair before choosing a status tone, and express status in words.

revealProgress defaults to 1 and must be finite. Values clamp to 0–1, setting overall opacity and scale from 0.99 to 1. There is no internal animation or propagation of a progress value to children. Consumer-supplied animation should respect reduced-motion preferences.

Props #

Types and optional flags are extracted from the installed declarations. Authored defaults are verified against the implementation; the heading and nesting checks above are additional runtime constraints.

Accessibility & layout #

The component renders a section labeled by heading, or “Conceptual group” when heading is omitted. The boundary label is a div, not an h2 or h3. Its full string remains the section’s accessible name even if the visible label ellipsizes. Prefer distinct descriptive names, keep them visually readable, and use real heading/list elements inside your composition when they communicate structure.

Boundary style is visual only. It adds no keyboard handling, interaction or ordered relationship between items. Preserve the semantics of supplied content and avoid excessive groups that create a noisy set of named regions. The nested example’s two activities remain list items. Reducing revealProgress changes presentation only; it does not remove content from the accessibility tree or disable focusable children.

GroupFrame fills its containing box; it has no breakpoint logic and does not arrange or resize its children. The seed wrappers retain their 340 px width, while the nested example provides 400 px for two boundaries and comfortable text. At smaller widths use a deliberate responsive wrapper or contained scrolling, and check heading truncation and child overflow. Fit to canvas scales the whole documentation composition; Actual size keeps its dimensions in a focusable scrolling area.

Consumer setup #

Browsing, previews, and copying are public. Installing the private @coreux/ui package requires repository read access and permission to use the bundled CoreUX brand fonts.

Follow the one-time installation guide for the pinned Git dependency, Tailwind v4 stylesheet setup, fonts, and troubleshooting. Keep the 'use client' directive in each example; no provider is required.

The quick start walks through a copied StatBlock in a minimal app.

Source & revision #

This reference targets @coreux/ui version 0.1.0 at 06f42fd. Types come from its installed declarations; explanations and defaults are checked against this implementation.

Revision and upgrade notes · Contribution and coverage guide