@egose/shadcn-theme-ng 0.1.0 → 0.3.0

package/button/fesm2022/button.mjs

@@ -7,6 +7,59 @@ import { NgTemplateOutlet } from '@angular/common';
 import { HlmSpinner } from '@egose/shadcn-theme-ng/spinner';
 import { cva } from 'class-variance-authority';
 
+// Keep complete utility names here so consumer Tailwind builds can discover every tone.
+const toneTextClasses = {
+    default: "text-primary",
+    primary: "text-primary",
+    secondary: "text-secondary",
+    success: "text-success",
+    warning: "text-warning",
+    danger: "text-danger",
+    info: "text-info",
+    light: "text-light-foreground",
+    dark: "text-dark",
+    accent: "text-accent",
+    destructive: "text-destructive",
+    muted: "text-muted-foreground",
+    outline: "text-primary",
+    link: "text-primary",
+    ghost: "text-light-foreground",
+};
+const outlineClasses = {
+    default: "border-primary hover:bg-primary/10",
+    primary: "border-primary hover:bg-primary/10",
+    secondary: "border-secondary hover:bg-secondary/10",
+    success: "border-success hover:bg-success/10",
+    warning: "border-warning hover:bg-warning/10",
+    danger: "border-danger hover:bg-danger/10",
+    info: "border-info hover:bg-info/10",
+    light: "border-light hover:bg-light/10",
+    dark: "border-dark hover:bg-dark/10",
+    accent: "border-accent hover:bg-accent/10",
+    destructive: "border-destructive hover:bg-destructive/10",
+    muted: "border-muted hover:bg-muted/10",
+    outline: "border-primary hover:bg-primary/10",
+    link: '',
+    ghost: '',
+};
+const outlineFilledClasses = {
+    default: "hover:bg-primary hover:text-primary-foreground",
+    primary: "hover:bg-primary hover:text-primary-foreground",
+    secondary: "hover:bg-secondary hover:text-secondary-foreground",
+    success: "hover:bg-success hover:text-success-foreground",
+    warning: "hover:bg-warning hover:text-warning-foreground",
+    danger: "hover:bg-danger hover:text-danger-foreground",
+    info: "hover:bg-info hover:text-info-foreground",
+    light: "hover:bg-light hover:text-light-foreground",
+    dark: "hover:bg-dark hover:text-dark-foreground",
+    accent: "hover:bg-accent hover:text-accent-foreground",
+    destructive: "hover:bg-destructive hover:text-destructive-foreground",
+    muted: "hover:bg-muted hover:text-muted-foreground",
+    outline: "hover:bg-primary hover:text-primary-foreground",
+    link: "hover:underline",
+    ghost: "hover:bg-light",
+};
+/** Semantic color utilities and appearances. Merge the result with hlm() for custom hosts. */
 const buttonVariants = cva([
     "cursor-pointer",
     "active:translate-y-[0.5px]",
@@ -45,7 +98,7 @@ const buttonVariants = cva([
             accent: "border border-accent bg-accent text-accent-foreground shadow-sm hover:bg-accent/90",
             destructive: "border border-destructive bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90",
             muted: "border border-muted bg-muted text-muted-foreground shadow-sm hover:bg-muted/90",
-            outline: "border border-primary bg-white text-primary shadow-sm hover:bg-primary/10",
+            outline: "border border-primary bg-background text-primary shadow-sm hover:bg-primary/10",
             link: "text-primary underline-offset-4 hover:underline",
             ghost: "hover:bg-light hover:text-light-foreground",
         },
@@ -66,14 +119,33 @@ const buttonVariants = cva([
         },
         appearance: {
             solid: '',
-            outline: "bg-white border",
-            'outline-filled': "bg-white border",
+            outline: "bg-background border shadow-sm",
+            'outline-filled': "bg-background border shadow-sm",
+            ghost: "bg-transparent border-0 shadow-none",
+            link: "bg-transparent border-0 shadow-none hover:bg-transparent underline-offset-4 hover:underline",
         },
         loading: {
             true: "pointer-events-none",
             false: null,
         },
     },
+    compoundVariants: Object.keys(toneTextClasses).flatMap((variant) => [
+        {
+            variant,
+            appearance: ['outline', 'outline-filled', 'ghost', 'link'],
+            class: toneTextClasses[variant],
+        },
+        {
+            variant,
+            appearance: ['outline', 'outline-filled', 'ghost'],
+            class: outlineClasses[variant],
+        },
+        {
+            variant,
+            appearance: 'outline-filled',
+            class: outlineFilledClasses[variant],
+        },
+    ]),
     defaultVariants: {
         variant: 'primary',
         size: 'default',
@@ -82,11 +154,12 @@ const buttonVariants = cva([
     },
 });
 class HlmButton {
-    /** Props as signal-based inputs */
+    /** Semantic color token. Legacy default, outline, link, and ghost variants remain supported. */
     variant = input('primary', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "variant" }] : /* istanbul ignore next */ []));
     size = input('default', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "size" }] : /* istanbul ignore next */ []));
+    /** Visual treatment independent of color: solid, outline, outline-filled, ghost, or link. */
     appearance = input('solid', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "appearance" }] : /* istanbul ignore next */ []));
     loading = input(false, /* @ts-ignore */
@@ -105,114 +178,19 @@ class HlmButton {
     _additionalClasses = signal('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "_additionalClasses" }] : /* istanbul ignore next */ []));
     /** Computed button class merging */
-    _computedClass = computed(() => {
-        const outlineClasses = this.appearance() === 'outline' || this.appearance() === 'outline-filled'
-            ? [this.getOutlineClasses(this.variant())]
-            : [];
-        if (this.appearance() === 'outline-filled') {
-            outlineClasses.push(this.getOutlineFilledClasses(this.variant()));
-        }
-        return hlm(buttonVariants({
-            variant: this.variant(),
-            size: this.size(),
-            appearance: this.appearance(),
-            loading: this.loading(),
-            className: this.userClass(),
-        }), outlineClasses, this.loading() ? "pointer-events-none" : '', this._additionalClasses());
-    }, /* @ts-ignore */
+    _computedClass = computed(() => hlm(buttonVariants({
+        variant: this.variant(),
+        size: this.size(),
+        appearance: this.appearance(),
+        loading: this.loading(),
+    }), this.userClass(), this.loading() ? "pointer-events-none" : '', this._additionalClasses()), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "_computedClass" }] : /* istanbul ignore next */ []));
-    /** Computed spinner classes */
-    spinnerClass = computed(() => {
-        const base = this.appearance() === 'outline' || this.appearance() === 'outline-filled'
-            ? this.getOutlineSpinnerClasses(this.variant())
-            : this.getSpinnerClasses(this.variant());
-        return hlm(base, this.spinnerUserClass());
-    }, /* @ts-ignore */
+    /** Inherit the button's resolved text color, including theme and consumer overrides. */
+    spinnerClass = computed(() => hlm("[&>svg]:text-current", this.spinnerUserClass()), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "spinnerClass" }] : /* istanbul ignore next */ []));
     setClass(classes) {
         this._additionalClasses.set(classes);
     }
-    /** Helper functions */
-    getOutlineClasses(variant) {
-        const colors = {
-            default: "border-primary text-primary shadow-sm hover:bg-primary/10",
-            primary: "border-primary text-primary shadow-sm hover:bg-primary/10",
-            secondary: "border-secondary text-secondary shadow-sm hover:bg-secondary/10",
-            success: "border-success text-success shadow-sm hover:bg-success/10",
-            warning: "border-warning text-warning shadow-sm hover:bg-warning/10",
-            danger: "border-danger text-danger shadow-sm hover:bg-danger/10",
-            info: "border-info text-info shadow-sm hover:bg-info/10",
-            light: "border-light text-light-foreground shadow-sm hover:bg-light/10",
-            dark: "border-dark text-dark shadow-sm hover:bg-dark/10",
-            accent: "border-accent text-accent shadow-sm hover:bg-accent/10",
-            destructive: "border-destructive text-destructive shadow-sm hover:bg-destructive/10",
-            muted: "border-muted text-muted-foreground shadow-sm hover:bg-muted/10",
-            outline: "border-primary text-primary shadow-sm hover:bg-primary/10",
-            link: "text-primary",
-            ghost: "text-light-foreground",
-        };
-        return colors[variant];
-    }
-    getOutlineFilledClasses(variant) {
-        const colors = {
-            default: "hover:bg-primary hover:text-primary-foreground",
-            primary: "hover:bg-primary hover:text-primary-foreground",
-            secondary: "hover:bg-secondary hover:text-secondary-foreground",
-            success: "hover:bg-success hover:text-success-foreground",
-            warning: "hover:bg-warning hover:text-warning-foreground",
-            danger: "hover:bg-danger hover:text-danger-foreground",
-            info: "hover:bg-info hover:text-info-foreground",
-            light: "hover:bg-light hover:text-light-foreground",
-            dark: "hover:bg-dark hover:text-dark-foreground",
-            accent: "hover:bg-accent hover:text-accent-foreground",
-            destructive: "hover:bg-destructive hover:text-destructive-foreground",
-            muted: "hover:bg-muted hover:text-muted-foreground",
-            outline: "hover:bg-primary hover:text-primary-foreground",
-            link: "hover:underline",
-            ghost: "hover:bg-light",
-        };
-        return colors[variant];
-    }
-    getSpinnerClasses(variant) {
-        const colors = {
-            default: "[&>svg]:text-primary-foreground",
-            primary: "[&>svg]:text-primary-foreground",
-            secondary: "[&>svg]:text-secondary-foreground",
-            success: "[&>svg]:text-success-foreground",
-            warning: "[&>svg]:text-warning-foreground",
-            danger: "[&>svg]:text-danger-foreground",
-            info: "[&>svg]:text-info-foreground",
-            light: "[&>svg]:text-light-foreground",
-            dark: "[&>svg]:text-dark-foreground",
-            accent: "[&>svg]:text-accent-foreground",
-            destructive: "[&>svg]:text-destructive-foreground",
-            muted: "[&>svg]:text-muted-foreground",
-            outline: "[&>svg]:text-primary",
-            link: "[&>svg]:text-primary",
-            ghost: "[&>svg]:text-light-foreground",
-        };
-        return colors[variant];
-    }
-    getOutlineSpinnerClasses(variant) {
-        const colors = {
-            default: "[&>svg]:text-primary",
-            primary: "[&>svg]:text-primary",
-            secondary: "[&>svg]:text-secondary",
-            success: "[&>svg]:text-success",
-            warning: "[&>svg]:text-warning",
-            danger: "[&>svg]:text-danger",
-            info: "[&>svg]:text-info",
-            light: "[&>svg]:text-light",
-            dark: "[&>svg]:text-dark",
-            accent: "[&>svg]:text-accent",
-            destructive: "[&>svg]:text-destructive",
-            muted: "[&>svg]:text-muted-foreground",
-            outline: "[&>svg]:text-primary",
-            link: "[&>svg]:text-primary",
-            ghost: "[&>svg]:text-light-foreground",
-        };
-        return colors[variant];
-    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmButton, deps: [], target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.3", type: HlmButton, isStandalone: true, selector: "button[hlmButton], a[hlmButton]", inputs: { variant: { classPropertyName: "variant", publicName: "variant", isSignal: true, isRequired: false, transformFunction: null }, size: { classPropertyName: "size", publicName: "size", isSignal: true, isRequired: false, transformFunction: null }, appearance: { classPropertyName: "appearance", publicName: "appearance", isSignal: true, isRequired: false, transformFunction: null }, loading: { classPropertyName: "loading", publicName: "loading", isSignal: true, isRequired: false, transformFunction: null }, icon: { classPropertyName: "icon", publicName: "icon", isSignal: true, isRequired: false, transformFunction: null }, iconPosition: { classPropertyName: "iconPosition", publicName: "iconPosition", isSignal: true, isRequired: false, transformFunction: null }, userClass: { classPropertyName: "userClass", publicName: "class", isSignal: true, isRequired: false, transformFunction: null }, spinnerUserClass: { classPropertyName: "spinnerUserClass", publicName: "spinnerUserClass", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, type: { classPropertyName: "type", publicName: "type", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "class": "_computedClass()", "attr.aria-busy": "loading() || null", "attr.disabled": "(loading() || disabled()) ? true : null", "attr.type": "type()" } }, hostDirectives: [{ directive: i1.BrnButton, inputs: ["disabled", "disabled"] }], ngImport: i0, template: "\n    <ng-template #projected>\n      <ng-content></ng-content>\n    </ng-template>\n\n    @if (loading()) {\n      <div class=\"relative inline-flex items-center\">\n        <span class=\"invisible\">\n          <ng-container *ngTemplateOutlet=\"projected\" />\n        </span>\n        <span class=\"absolute inset-0 flex items-center justify-center\">\n          <hlm-spinner [spinnerClass]=\"spinnerClass()\" />\n        </span>\n      </div>\n    } @else {\n      <div class=\"flex items-center gap-1\">\n        @if (icon() && iconPosition() === 'left') {\n          <ng-container *ngTemplateOutlet=\"icon()\" />\n        }\n        <ng-container *ngTemplateOutlet=\"projected\" />\n        @if (icon() && iconPosition() === 'right') {\n          <ng-container *ngTemplateOutlet=\"icon()\" />\n        }\n      </div>\n    }\n  ", isInline: true, dependencies: [{ kind: "component", type: HlmSpinner, selector: "hlm-spinner", inputs: ["size", "show", "class", "spinnerClass"] }, { kind: "directive", type: NgTemplateOutlet, selector: "[ngTemplateOutlet]", inputs: ["ngTemplateOutletContext", "ngTemplateOutlet", "ngTemplateOutletInjector"] }] });
 }

package/button/types/button.d.ts

@@ -18,10 +18,11 @@ declare class HlmBtn {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<HlmBtn, "button[hlmBtn], a[hlmBtn]", ["hlmBtn"], { "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.BrnButton; inputs: { "disabled": "disabled"; }; outputs: {}; }]>;
 }
 
+/** Semantic color utilities and appearances. Merge the result with hlm() for custom hosts. */
 declare const buttonVariants: (props?: ({
     variant?: "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "info" | "light" | "dark" | "accent" | "destructive" | "muted" | "outline" | "link" | "ghost" | null | undefined;
     size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | "compact-xs" | "compact-sm" | "compact-default" | "compact-lg" | "compact-icon" | null | undefined;
-    appearance?: "outline" | "solid" | "outline-filled" | null | undefined;
+    appearance?: "outline" | "link" | "ghost" | "solid" | "outline-filled" | null | undefined;
     loading?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type ButtonVariants = VariantProps<typeof buttonVariants>;
@@ -29,9 +30,10 @@ type VariantType = NonNullable<ButtonVariants['variant']>;
 type SizeType = NonNullable<ButtonVariants['size']>;
 type AppearanceType = NonNullable<ButtonVariants['appearance']>;
 declare class HlmButton {
-    /** Props as signal-based inputs */
+    /** Semantic color token. Legacy default, outline, link, and ghost variants remain supported. */
     readonly variant: _angular_core.InputSignal<VariantType>;
     readonly size: _angular_core.InputSignal<SizeType>;
+    /** Visual treatment independent of color: solid, outline, outline-filled, ghost, or link. */
     readonly appearance: _angular_core.InputSignal<AppearanceType>;
     readonly loading: _angular_core.InputSignal<boolean>;
     readonly icon: _angular_core.InputSignal<TemplateRef<unknown> | undefined>;
@@ -43,14 +45,9 @@ declare class HlmButton {
     private readonly _additionalClasses;
     /** Computed button class merging */
     protected readonly _computedClass: _angular_core.Signal<string>;
-    /** Computed spinner classes */
+    /** Inherit the button's resolved text color, including theme and consumer overrides. */
     protected readonly spinnerClass: _angular_core.Signal<string>;
     setClass(classes: string): void;
-    /** Helper functions */
-    private getOutlineClasses;
-    private getOutlineFilledClasses;
-    private getSpinnerClasses;
-    private getOutlineSpinnerClasses;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<HlmButton, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<HlmButton, "button[hlmButton], a[hlmButton]", never, { "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "appearance": { "alias": "appearance"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "iconPosition": { "alias": "iconPosition"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "spinnerUserClass": { "alias": "spinnerUserClass"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, [{ directive: typeof i1.BrnButton; inputs: { "disabled": "disabled"; }; outputs: {}; }]>;
 }

package/button-group/README.md

@@ -1,11 +1,324 @@
-# ButtonGroup
+# Button Group (`@egose/shadcn-theme-ng/button-group`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli).
+A joined, toolbar-style group layout that fuses buttons, inputs, selects, and static text into one visually continuous control — the Angular port of shadcn/ui `Button Group`. There is no interactive behavior of its own: `HlmButtonGroup` is a thin `cva`-styled layout directive (`orientation: horizontal | vertical`) that strips inner border-radii and collapses adjacent borders, while `HlmButtonGroupText` and `HlmButtonGroupSeparator` provide the static-text cell and the divider cell. The only headless primitive involved is `BrnSeparator` from `@spartan-ng/brain/separator` (used inside the separator directive).
 
-## Building
+Ships as `@egose/shadcn-theme-ng/button-group` and `@egose/shadcn-theme-ng-tw/button-group` (the `tw:`-prefixed variant). See the [package README](../../README.md) for install, peer dependencies, and Tailwind setup. Do not publish this project directory independently — it is consumed via the published subpath only.
 
-To build the library, run:
+## Installation
 
 ```bash
-ng build button-group
+# Plain Tailwind (no prefix):
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant:
+npm install @egose/shadcn-theme-ng-tw
+```
+
+Peer dependencies (Angular, `@spartan-ng/brain`, etc.) are documented in the [package README](../../README.md). This subpath itself declares `@angular/common`, `@angular/core`, and `@spartan-ng/brain` as peers (see `projects/button-group/package.json`).
+
+## Imports
+
+Named imports from the subpath public API (`projects/button-group/src/public-api.ts`):
+
+```ts
+import {
+  HlmButtonGroup,
+  HlmButtonGroupText,
+  HlmButtonGroupSeparator,
+  HlmButtonGroupImports,
+  HlmButtonGroupModule,
+} from '@egose/shadcn-theme-ng/button-group';
+// tw variant:
+// import { ... } from '@egose/shadcn-theme-ng-tw/button-group';
+```
+
+Standalone-component usage (preferred):
+
+```ts
+import { Component } from '@angular/core';
+import { HlmButtonGroupImports } from '@egose/shadcn-theme-ng/button-group';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmButtonGroupImports],
+  template: `...`,
+})
+export class DemoComponent {}
+```
+
+NgModule usage:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmButtonGroupModule } from '@egose/shadcn-theme-ng/button-group';
+
+@NgModule({ imports: [HlmButtonGroupModule] })
+export class DemoModule {}
+```
+
+You can also import the three directives individually (`HlmButtonGroup`, `HlmButtonGroupText`, `HlmButtonGroupSeparator`) instead of the whole `HlmButtonGroupImports` array.
+
+## Anatomy / Structure
+
+```html
+<!-- Element OR attribute form for the group itself -->
+<hlm-button-group orientation="horizontal">
+  <button hlmBtn variant="outline">Left</button>
+  <button hlmBtn variant="outline">Middle</button>
+  <button hlmBtn variant="outline">Right</button>
+</hlm-button-group>
+
+<!-- With static text + separator (attribute forms also work) -->
+<div hlmButtonGroup orientation="horizontal">
+  <span hlmButtonGroupText>https://</span>
+  <input hlmInput placeholder="example.com" />
+  <hlm-button-group-separator></hlm-button-group-separator>
+  <button hlmBtn>Go</button>
+</div>
+```
+
+Real selectors (from source):
+
+| Class                     | Selectors                                                 |
+| ------------------------- | --------------------------------------------------------- |
+| `HlmButtonGroup`          | `[hlmButtonGroup]`, `hlm-button-group`                    |
+| `HlmButtonGroupText`      | `[hlmButtonGroupText]`, `hlm-button-group-text`           |
+| `HlmButtonGroupSeparator` | `[hlmButtonGroupSeparator]`, `hlm-button-group-separator` |
+
+All three carry a `data-slot` host attribute (`button-group`, `button-group-text`, `button-group-separator`). The group host also sets `role="group"` and `[attr.data-orientation]`.
+
+## API reference
+
+### `HlmButtonGroup` (`[hlmButtonGroup]`, `hlm-button-group`)
+
+| Input         | Type                         | Default        | Description                                                                                                                                                            |
+| ------------- | ---------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout axis. `horizontal` collapses left/right radii and left borders; `vertical` stacks, collapses top/bottom radii and top borders. Reflected as `data-orientation`. |
+
+No outputs, no methods. Styling is computed by `buttonGroupVariants({ orientation })` (cva) plus helpers for nested `select-trigger`, `input`, and nested `button-group` spacing.
+
+### `HlmButtonGroupText` (`[hlmButtonGroupText]`, `hlm-button-group-text`)
+
+Thin directive wrapper — no inputs, outputs, or methods. Renders a muted, bordered, static-text cell (`bg-muted`, `rounded-lg`, `px-2.5`, icon-aware). Use for prefixes/suffixes such as `https://`, `.com`, currency symbols, or counts.
+
+### `HlmButtonGroupSeparator` (`[hlmButtonGroupSeparator]`, `hlm-button-group-separator`)
+
+| Brain input (via `BrnSeparator` hostDirective) | Type                         | Default                                        | Description                                                                                                                          |
+| ---------------------------------------------- | ---------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `orientation`                                  | `'horizontal' \| 'vertical'` | `'vertical'` (via `provideBrnSeparatorConfig`) | Separator axis. The provider defaults it to `vertical` so it divides horizontal groups out of the box; override for vertical groups. |
+| `decorative`                                   | `boolean`                    | —                                              | Passed straight to `BrnSeparator` (aria-hidden handling).                                                                            |
+
+No outputs of its own. Host classes make it `self-stretch`, `bg-input`, 1px thick on the active axis.
+
+## Examples
+
+### 1. Basic horizontal button cluster
+
+Three outline buttons fused into one segmented control.
+
+```ts
+import { Component } from '@angular/core';
+import { HlmButtonGroupImports } from '@egose/shadcn-theme-ng/button-group';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'app-basic-group',
+  standalone: true,
+  imports: [...HlmButtonGroupImports, ...HlmButtonImports],
+  template: `
+    <hlm-button-group>
+      <button hlmBtn variant="outline">Left</button>
+      <button hlmBtn variant="outline">Center</button>
+      <button hlmBtn variant="outline">Right</button>
+    </hlm-button-group>
+  `,
+})
+export class BasicGroupComponent {}
+```
+
+### 2. All orientations
+
+`horizontal` (default) vs `vertical`. Vertical stacks children and collapses vertical borders instead.
+
+```ts
+import { Component } from '@angular/core';
+import { HlmButtonGroupImports } from '@egose/shadcn-theme-ng/button-group';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'app-orientations',
+  standalone: true,
+  imports: [...HlmButtonGroupImports, ...HlmButtonImports],
+  template: `
+    <div class="flex gap-8">
+      <hlm-button-group orientation="horizontal">
+        <button hlmBtn variant="outline">A</button>
+        <button hlmBtn variant="outline">B</button>
+        <button hlmBtn variant="outline">C</button>
+      </hlm-button-group>
+
+      <hlm-button-group orientation="vertical">
+        <button hlmBtn variant="outline">Top</button>
+        <button hlmBtn variant="outline">Middle</button>
+        <button hlmBtn variant="outline">Bottom</button>
+      </hlm-button-group>
+    </div>
+  `,
+})
+export class OrientationsComponent {}
+```
+
+### 3. Input group with static prefix/suffix text
+
+Classic URL / price field: muted text cells fused with a native-styled input and an action button.
+
+```ts
+import { Component } from '@angular/core';
+import { HlmButtonGroupImports } from '@egose/shadcn-theme-ng/button-group';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  selector: 'app-addon-group',
+  standalone: true,
+  imports: [...HlmButtonGroupImports, ...HlmButtonImports, HlmInput],
+  template: `
+    <div hlmButtonGroup>
+      <span hlmButtonGroupText>https://</span>
+      <input hlmInput placeholder="example.com" class="w-48" />
+      <span hlmButtonGroupText>.com</span>
+      <button hlmBtn>Visit</button>
+    </div>
+  `,
+})
+export class AddonGroupComponent {}
+```
+
+### 4. Separated actions (divider cells)
+
+Use `hlm-button-group-separator` between clusters instead of spacing utilities so the divider stretches to the group height.
+
+```ts
+import { Component } from '@angular/core';
+import { HlmButtonGroupImports } from '@egose/shadcn-theme-ng/button-group';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'app-separated-group',
+  standalone: true,
+  imports: [...HlmButtonGroupImports, ...HlmButtonImports],
+  template: `
+    <hlm-button-group>
+      <button hlmBtn variant="outline">Cut</button>
+      <button hlmBtn variant="outline">Copy</button>
+      <button hlmBtn variant="outline">Paste</button>
+      <hlm-button-group-separator></hlm-button-group-separator>
+      <button hlmBtn variant="outline">Undo</button>
+      <button hlmBtn variant="outline">Redo</button>
+    </hlm-button-group>
+  `,
+})
+export class SeparatedGroupComponent {}
+```
+
+Explanation: the separator defaults to `orientation="vertical"` via its provider. Inside a `orientation="vertical"` group, bind it explicitly:
+
+```html
+<hlm-button-group orientation="vertical">
+  <button hlmBtn variant="outline">One</button>
+  <hlm-button-group-separator orientation="horizontal"></hlm-button-group-separator>
+  <button hlmBtn variant="outline">Two</button>
+</hlm-button-group>
+```
+
+### 5. Mixed controls: select + input + button
+
+The group stylesheet special-cases `select-trigger` and `input` children (`w-fit` triggers, `flex-1` inputs), so mixed toolbars fuse cleanly.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmButtonGroupImports } from '@egose/shadcn-theme-ng/button-group';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+import { HlmSelectImports } from '@egose/shadcn-theme-ng/select';
+
+@Component({
+  selector: 'app-mixed-group',
+  standalone: true,
+  imports: [...HlmButtonGroupImports, ...HlmButtonImports, HlmInput, ...HlmSelectImports],
+  template: `
+    <div hlmButtonGroup>
+      <hlm-select [value]="unit()">
+        <hlm-select-trigger class="w-28">
+          <hlm-select-value />
+        </hlm-select-trigger>
+        <hlm-select-content *hlmSelectPortal>
+          <hlm-select-item value="px">px</hlm-select-item>
+          <hlm-select-item value="rem">rem</hlm-select-item>
+          <hlm-select-item value="em">em</hlm-select-item>
+        </hlm-select-content>
+      </hlm-select>
+      <input hlmInput type="number" value="16" class="w-24" />
+      <button hlmBtn (click)="apply()">Apply</button>
+    </div>
+  `,
+})
+export class MixedGroupComponent {
+  readonly unit = signal('px');
+  apply() {
+    console.log('apply', this.unit());
+  }
+}
+```
+
+### 6. Icon toolbar with labels for assistive tech
+
+Buttons keep their own `aria-label`s; the group only adds `role="group"` — give it an `aria-label` for context.
+
+```ts
+import { Component } from '@angular/core';
+import { HlmButtonGroupImports } from '@egose/shadcn-theme-ng/button-group';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideBold, lucideItalic, lucideUnderline } from '@ng-icons/lucide';
+
+@Component({
+  selector: 'app-toolbar-group',
+  standalone: true,
+  imports: [...HlmButtonGroupImports, ...HlmButtonImports, NgIcon],
+  providers: [provideIcons({ lucideBold, lucideItalic, lucideUnderline })],
+  template: `
+    <hlm-button-group aria-label="Text formatting">
+      <button hlmBtn variant="outline" size="icon" aria-label="Bold">
+        <ng-icon name="lucideBold" />
+      </button>
+      <button hlmBtn variant="outline" size="icon" aria-label="Italic">
+        <ng-icon name="lucideItalic" />
+      </button>
+      <button hlmBtn variant="outline" size="icon" aria-label="Underline">
+        <ng-icon name="lucideUnderline" />
+      </button>
+    </hlm-button-group>
+  `,
+})
+export class ToolbarGroupComponent {}
 ```
+
+## Accessibility notes
+
+- The group host renders `role="group"` — always pair it with `aria-label` or `aria-labelledby` when the purpose is not obvious from the buttons alone.
+- `HlmButtonGroupSeparator` delegates to `BrnSeparator`: mark purely visual dividers `decorative`, otherwise keep them exposed so screen readers announce the grouping break.
+- `HlmButtonGroupText` is a plain `<span>`-style cell with no semantics; never put interactive content inside it.
+- Keyboard behavior is unchanged — Tab moves through each fused button/input normally; roving tabindex is not applied.
+
+## Theming / CSS variables
+
+No component-specific CSS variables. Styling is Tailwind-driven (`bg-muted` text cells, `bg-input` separators, ring/border tokens). Dark mode follows the shared `tw:dark:` theme tokens. Override via `class` on any cell — the `classes()` helper merges your classes with the defaults.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/button` — `hlmBtn` / `HlmBtn` used for every fused button.
+- `@egose/shadcn-theme-ng/input` — `hlmInput` fused text/number fields.
+- `@egose/shadcn-theme-ng/select` — triggers auto-size (`w-fit`) inside groups.
+- `@egose/shadcn-theme-ng/separator` — standalone separator primitive (the group ships its own opinionated divider).