@ng-brutalism/ui 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -7,11 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-06-02
+
+`v0.2.0` introduces a stronger composition system for building brutalist Angular UIs. The new layout grammar — Surface, Section, Stack, Cluster, and Split — lets you compose full card layouts, multi-column pages, and recipe UIs entirely from library primitives with consistent token-driven spacing, border, shadow, and typography.
+
+### Added
+
+**Composition system**
+
+- `NbSurface` — base brutalist panel directive. Token-driven tone, radius, border, shadow, padding, size, layout, edge, clip, and typography inputs.
+- `NbSection` — inner region primitive for Surface. Owns padding, divider side, divider style, layout (default / center / between), align, and flush.
+- `NbStack` — vertical rhythm primitive. Gap, align, justify, and separator inputs.
+- `NbCluster` — horizontal/wrapping rhythm primitive. Gap, padding, align, justify, wrap, and separator inputs.
+- `NbSplit` — two-column main-and-aside primitive. Ratio, gap, padding, collapse (responsive breakpoint), align, and separator inputs.
+- `NbMediaFrame` — framed media primitive with aspect ratio locking. Ratios: `auto`, `1/1`, `3/4`, `4/3`, `3/2`, `16/9`, `21/9`.
+- `NbText` — inline and block text primitive.
+- `NbDisplay` — large headline primitive.
+- `NbTitle`, `NbTypography` — typography composition primitives.
+- `NbStat` — statistic display primitive.
+- `NbRating` — star rating primitive.
+- `NbProgress` — progress bar primitive.
+- `NbStatusDot` — status indicator primitive with size and radius inputs.
+- `NbCallout` — inline callout/emphasis primitive.
+- `NbMediaItem` — icon + label pair primitive.
+- `NbAvatar`, `NbAvatarGroup` — avatar and avatar stack primitives.
+- `NbChip`, `NbChipGroup` — tag/badge primitive with tone, padding, and group layout.
+- `NbIconButton` — icon-only button primitive.
+- `NbSticker` — decorative burst/shape primitive.
+- `NbHalftone` — decorative halftone pattern primitive.
+- `NbSeparator` — divider line primitive.
+
+**Recipes**
+
+- Travel Card — media, sticker, display, split, cluster composition recipe.
+- Podcast Card — audio episode card composition recipe.
+- Open to Work Card — professional profile card composition recipe.
+
+**Shared token vocabulary**
+
+- Unified `NbBorderStrength`, `NbShadow`, `NbRadius`, `NbSpacing`, `NbPadding`, `NbToneToken` across all composition primitives.
+- `NbTypographyFont` — font role contract used by `NbTypography` and `NbSurface`.
+- `NbMediaFrameRatio` — now includes `'3/4'` portrait ratio.
+
 ### Breaking Changes (pre-publish, still 0.x)
 
 - **Class names**: `Component`/`Directive` suffix dropped. `NbCardComponent` → `NbCard`, `NbButtonDirective` → `NbButton`, `NbSelectComponent` → `NbSelect`, `NbAccordionComponent` → `NbAccordion`, etc.
 - **`defaultValue` removed from `<nb-accordion>`**: use `[value]="..."` for one-way initial value or `[(value)]` for two-way binding.
 - **`defaultValue` and `defaultOpen` removed from `<nb-select>`**: use `[value]` / `[(value)]` and `[open]` / `[(open)]` respectively.
+- **`NbSection` `border` input renamed to `divider`**: `border="bottom"` → `divider="bottom"`. Separates the region-border concept from the outline-strength `border` input used everywhere else.
 
 ### Internal
 
@@ -43,6 +86,7 @@ Initial public release.
 ### Added
 
 **Form controls**
+
 - `NbButton`
 - `NbCheckbox`
 - `NbInput`
@@ -53,6 +97,7 @@ Initial public release.
 - `NbTextarea`
 
 **Layout & content**
+
 - `NbAccordion`
 - `NbAvatar`
 - `NbBadge`
@@ -62,9 +107,11 @@ Initial public release.
 - `NbTitle`
 
 **Overlays**
+
 - `NbDialog`
 
 **Foundation**
+
 - MIT license, Angular 21 + Tailwind v4 peer dependencies
 - `styles.css` single-import entrypoint (default theme)
 - `theme.css` token-only entrypoint for advanced theming
@@ -72,4 +119,5 @@ Initial public release.
 - CSS custom properties as the primary theming surface
 
 **Notes**
+
 - Pre-1.0: minor versions may include breaking changes while APIs settle.

package/README.md

@@ -1,10 +1,11 @@
-# ng-brutalism — Neo-brutalist Angular UI Component Library
+# ng-brutalism — Neo-brutalist Angular UI Primitive Library
 
 Build loud. Stay sharp.
 
-ng-brutalism is a neo-brutalist Angular UI component library — token-driven,
-signals-first, zoneless, with directive APIs, keyboard-ready interactions, and
-Tailwind v4 ergonomics from the first import.
+ng-brutalism is a neo-brutalist Angular UI primitive library and composition
+system for building loud, token-driven Angular interfaces with directive-first
+APIs, signals, zoneless-friendly patterns, Tailwind CSS v4, chunky borders,
+offset shadows, and punchy colors.
 
 If you like shadcn/ui or daisyUI, but for Angular and built around brutalism.
 
@@ -17,7 +18,15 @@ If you like shadcn/ui or daisyUI, but for Angular and built around brutalism.
 [npm](https://www.npmjs.com/package/@ng-brutalism/ui) ·
 [GitHub](https://github.com/khangtrannn/ng-brutalism)
 
-![ng-brutalism Angular component library demo — buttons, cards, dialogs in neo-brutalist style](https://raw.githubusercontent.com/khangtrannn/ng-brutalism/main/docs/assets/introduction.gif)
+![ng-brutalism v0.2.0 — composable brutalist primitives for bold Angular interfaces](https://raw.githubusercontent.com/khangtrannn/ng-brutalism/main/docs/assets/compositions/v0.2.0.png)
+
+## What's new in v0.2.0
+
+v0.2.0 ships a full composition system. The new layout grammar — **Surface, Section, Stack, Cluster, and Split** — lets you compose complete card layouts, multi-column pages, and recipe UIs entirely from library primitives with consistent token-driven spacing, border, shadow, and typography.
+
+New primitives: `NbSurface`, `NbSection`, `NbStack`, `NbCluster`, `NbSplit`, `NbMediaFrame`, `NbText`, `NbDisplay`, `NbStat`, `NbRating`, `NbProgress`, `NbStatusDot`, `NbCallout`, `NbMediaItem`, `NbAvatarGroup`, `NbChip`, `NbChipGroup`, `NbIconButton`, `NbSticker`, `NbHalftone`, `NbSeparator` — plus three ready-made composition recipes.
+
+See the [full changelog](https://github.com/khangtrannn/ng-brutalism/blob/main/CHANGELOG.md) for details and migration notes.
 
 ## Install
 
@@ -92,29 +101,38 @@ bootstrapApplication(App, {
 });
 ```
 
-## Components
-
-| Component | Description | Docs |
-| --- | --- | --- |
-| Accordion | Vertically stacked, collapsible content panels with single or multi-expand modes. | [Docs](https://ngbrutalism.khangtran.dev/components/accordion) |
-| Avatar | Compact avatar with image and fallback support. | [Docs](https://ngbrutalism.khangtran.dev/components/avatar) |
-| Badge | Inline status pill with multiple variants. | [Docs](https://ngbrutalism.khangtran.dev/components/badge) |
-| Button | Directive-driven button with size, variant, and shadow controls. | [Docs](https://ngbrutalism.khangtran.dev/components/button) |
-| Card | Container with header, title, description, content, actions, and footer slots. | [Docs](https://ngbrutalism.khangtran.dev/components/card) |
-| Checkbox | Form checkbox with size variants and signal-friendly bindings. | [Docs](https://ngbrutalism.khangtran.dev/components/checkbox) |
-| Dialog | Modal dialog with title, description, content, actions, and close slots. | [Docs](https://ngbrutalism.khangtran.dev/components/dialog) |
-| Image Card | Image-led card with caption overlay for portfolios and galleries. | [Docs](https://ngbrutalism.khangtran.dev/components/image-card) |
-| Input | Single-line text input with size variants. | [Docs](https://ngbrutalism.khangtran.dev/components/input) |
-| Input Group | Input wrapper with prefix and suffix slots for icons, addons, or units. | [Docs](https://ngbrutalism.khangtran.dev/components/input-group) |
-| Label | Accessible label tied to form controls. | [Docs](https://ngbrutalism.khangtran.dev/components/label) |
-| Marquee | Looping horizontal scroller for logos, tags, or announcements. | [Docs](https://ngbrutalism.khangtran.dev/components/marquee) |
-| Select | Native or custom dropdown select with option templating. | [Docs](https://ngbrutalism.khangtran.dev/components/select) |
-| Textarea | Multi-line text input with size variants. | [Docs](https://ngbrutalism.khangtran.dev/components/textarea) |
-| Title | Typographic heading primitive with brutalist defaults. | [Docs](https://ngbrutalism.khangtran.dev/components/title) |
-
-## What it looks like
-
-![ng-brutalism component showcase — accordion, badge, button, card, checkbox, dialog, input, select rendered in brutalist design](https://raw.githubusercontent.com/khangtrannn/ng-brutalism/main/docs/assets/showcase-portfolio.png)
+## Primitive System
+
+ng-brutalism is a composition system, not just a component list. Use primitives
+like `nbSurface`, `nbSection`, `nbSplit`, `nbStack`, and `nbCluster` as the
+layout grammar. Add emphasis with `nbChip`, `nbCallout`, `nbSticker`, and
+`nbStatusDot`. Finish with typography, media, forms, and action primitives.
+
+Inputs are for common design decisions. CSS variables are for local art
+direction. Classes are for layout escape hatches.
+
+| Group | Primitives |
+| --- | --- |
+| Foundation | Tokens, theme provider, CSS variables, `nbClass` |
+| Layout | Stack, Cluster, Split, Section, Separator |
+| Surfaces | Surface, Card, Image Card, Media Frame |
+| Typography | Text, Display, Title |
+| Emphasis | Badge, Chip, Callout, Sticker, Status Dot, Rating, Progress, Halftone |
+| Actions | Button, Icon Button, Button Trailing Icon |
+| Media | Avatar, Avatar Group, Icon, Media Item, Stat |
+| Forms | Input, Input Group, Textarea, Checkbox, Select, Label |
+| Overlays / Interaction | Accordion, Dialog, Marquee |
+| Recipes | Travel Card, Podcast Card, Open to Work Card |
+
+## Compositions
+
+Three ready-made recipes ship with v0.2.0, each assembled entirely from library primitives:
+
+<p>
+  <img src="https://raw.githubusercontent.com/khangtrannn/ng-brutalism/main/docs/assets/compositions/personal-profile.png" width="32%" alt="Open to Work Card — personal profile composition built from Surface, Split, Chip, and MediaFrame primitives" />
+  <img src="https://raw.githubusercontent.com/khangtrannn/ng-brutalism/main/docs/assets/compositions/podcast-promo.png" width="32%" alt="Podcast Card — audio episode composition built from Surface, Section, Badge, and Avatar primitives" />
+  <img src="https://raw.githubusercontent.com/khangtrannn/ng-brutalism/main/docs/assets/compositions/travel-campaign.png" width="32%" alt="Travel Card — campaign-style composition built from Surface, MediaFrame, Display, and Sticker primitives" />
+</p>
 
 ## Documentation
 
@@ -141,6 +159,12 @@ All visual tokens are exposed as CSS custom properties (`--nb-*`). A subset of t
 **Is ng-brutalism ready for production?**
 It is pre-1.0. Component APIs are usable today, but minor versions may include breaking changes while the library settles.
 
+## Migrating from v0.1.x
+
+v0.2.0 contains breaking changes. The `Component`/`Directive` suffix was dropped from all exported names: `NbCardComponent` → `NbCard`, `NbButtonDirective` → `NbButton`, `NbSelectComponent` → `NbSelect`, etc. The `defaultValue` / `defaultOpen` inputs on `<nb-accordion>` and `<nb-select>` were removed in favour of `[value]` / `[(value)]` bindings. `NbSection`'s `border` input was renamed to `divider`.
+
+See the [full changelog](https://github.com/khangtrannn/ng-brutalism/blob/main/CHANGELOG.md) for the complete list.
+
 ## Author
 
 Created by [Khang Tran](https://github.com/khangtrannn). MIT licensed. Source code is available on GitHub.