@sinequa/galactik 2.1.1 → 2.3.0

package/README.md

@@ -5,7 +5,9 @@ Angular UI primitives built on top of [`@angular/aria`](https://www.npmjs.com/pa
 ## Requirements
 
 - Angular `^22.0.0`
-- `@angular/aria` `^22.0.0`
+- `@angular/aria` `^22.2.0`
+- [`cn`](https://www.npmjs.com/package/cn) `^0.2.5` (class-name merging, a peer dependency)
+- Tailwind CSS v4 — components are styled with galactik design tokens through Tailwind utilities
 
 ## Installation
 
@@ -24,10 +26,14 @@ one from `@sinequa/ui`.
 
 Public API surface (see `public-api.ts`):
 
-- **Menu** — `MenuComponent`, `MenuContentComponent`, `MenuItemComponent`, `SubMenuComponent`, `MenuTriggerDirective`
-- **Tabs** — `TabsComponent`, `TabListComponent`, `TabComponent`, `TabPanelComponent`
-- **Popover** — `DropdownDirective` (alias of `PopoverDirective`, kept for backward compatibility)
-- **Utils** — `cn` helper for merging Tailwind class names
+- **Actions** — `ButtonComponent`, `ToggleComponent`, `ToggleGroupComponent`, `LinkComponent`
+- **Form controls** — `InputComponent`, `TextareaComponent`, `CheckboxComponent`, `RadioComponent`, `SwitchComponent`, `SelectComponent`, `AutocompleteComponent`, `TagInputComponent`, `SearchInputComponent`, `SearchBarComponent`
+- **Display** — `TagComponent`, `TagRemoveComponent`, `BadgeComponent`, `BulletComponent`, `KbdComponent`, `AvatarComponent`
+- **Lists and navigation** — `ListComponent`, `TreeComponent`, `RowGridComponent`, `RowFeedComponent`, `TabsComponent`, `MenuComponent`, `SidebarComponent`
+- **Overlays** — `DialogComponent`, `SheetComponent`, `PopoverDirective` (alias `DropdownDirective`), `TooltipDirective`, `injectFloatingPanel`, `createCallable` (dialogs opened from code)
+- **Layout** — `ResizablePanelGroupComponent`, `ResizablePanelComponent`, `ResizableHandleComponent`
+- **Services** — `BreakpointObserverService`
+- **Icons** — the icon catalogue is re-exported from the main entry point (for example `CheckIcon`)
 
 ## Usage
 
@@ -119,7 +125,7 @@ import { TabsComponent, TabListComponent, TabComponent, TabPanelComponent } from
   `,
 })
 export class TabsExampleComponent {
-  onTabChange(value: string) {
+  onTabChange(value: string | undefined) {
     console.log("Selected tab:", value);
   }
 }
@@ -146,6 +152,216 @@ import { DropdownDirective } from "@sinequa/galactik";
 export class PopoverExampleComponent {}
 ```
 
+### Button
+
+`ButtonComponent` is a directive on the native `<button>` selector: importing it restyles every
+`<button>` the component's own template renders, and leaves `type`, `disabled` and keyboard behaviour
+to the platform.
+
+```ts
+import { Component } from "@angular/core";
+import { ButtonComponent } from "@sinequa/galactik";
+
+@Component({
+  selector: "app-button-example",
+  imports: [ButtonComponent],
+  template: `
+    <button type="button" variant="primary" size="md" (click)="save()">Save</button>
+    <button type="button" variant="secondary" size="md">Cancel</button>
+  `,
+})
+export class ButtonExampleComponent {
+  save() {
+    /* ... */
+  }
+}
+```
+
+### Input
+
+`InputComponent` (`<input-group>`) wraps a native `<input input-control>`; focus, disabled and read-only
+styles come from the input's own state.
+
+```ts
+import { Component } from "@angular/core";
+import { InputComponent, InputControlDirective } from "@sinequa/galactik";
+
+@Component({
+  selector: "app-input-example",
+  imports: [InputComponent, InputControlDirective],
+  template: `
+    <input-group>
+      <input input-control type="text" placeholder="Enter your name" />
+    </input-group>
+  `,
+})
+export class InputExampleComponent {}
+```
+
+### Select
+
+`SelectComponent` (`<SelectMenu>`) is a single- or multiple-choice dropdown built on the accessible
+`@angular/aria` combobox. It implements the Signal Forms `FormValueControl` contract, so it binds with
+`[(value)]` or `[formField]`.
+
+```ts
+import { Component, signal } from "@angular/core";
+import { SelectComponent } from "@sinequa/galactik";
+
+@Component({
+  selector: "app-select-example",
+  imports: [SelectComponent],
+  template: `
+    <SelectMenu
+      [options]="fruits"
+      [(value)]="fruit"
+      fieldLabel="Fruit"
+      placeholder="Choose a fruit…"
+      hint="Pick your favorite." />
+  `,
+})
+export class SelectExampleComponent {
+  fruits = ["Apple", "Banana", "Cherry", "Date", "Elderberry"];
+  fruit = signal<string | null>(null);
+}
+```
+
+### Dialog
+
+Bind a dialog component once with `createCallable`, then `await` it from anywhere. Register
+`provideCallable()` once in the application providers.
+
+```ts title="confirm-dialog.ts"
+import { afterNextRender, Component, viewChild } from "@angular/core";
+import {
+  ButtonComponent,
+  createCallable,
+  DialogBodyComponent,
+  DialogComponent,
+  DialogContentComponent,
+  DialogDescriptionComponent,
+  DialogFooterComponent,
+  DialogHeaderComponent,
+  DialogTitleComponent,
+  injectCallRef,
+} from "@sinequa/galactik";
+
+@Component({
+  selector: "confirm-dialog",
+  imports: [
+    DialogComponent,
+    DialogContentComponent,
+    DialogHeaderComponent,
+    DialogTitleComponent,
+    DialogBodyComponent,
+    DialogDescriptionComponent,
+    DialogFooterComponent,
+    ButtonComponent,
+  ],
+  template: `
+    <dialog #dialog="dialog" (closed)="call.end($event === 'dialog-confirm')">
+      <DialogContent size="sm">
+        <DialogHeader>
+          <DialogTitle>Please confirm</DialogTitle>
+        </DialogHeader>
+        <DialogBody>
+          <DialogDescription>{{ call.props().message }}</DialogDescription>
+        </DialogBody>
+        <DialogFooter>
+          <button variant="secondary" size="md" (click)="dialog.close('dialog-cancel')">Cancel</button>
+          <button variant="primary" size="md" (click)="dialog.close('dialog-confirm')">Confirm</button>
+        </DialogFooter>
+      </DialogContent>
+    </dialog>
+  `,
+})
+export class ConfirmDialog {
+  protected readonly call = injectCallRef<{ message: string }, boolean>();
+  private readonly dialog = viewChild.required(DialogComponent);
+
+  constructor() {
+    afterNextRender(() => this.dialog().showModal());
+  }
+}
+
+export const Confirm = createCallable<{ message: string }, boolean>(ConfirmDialog);
+```
+
+```ts title="delete-item.component.ts"
+import { Component, signal } from "@angular/core";
+import { ButtonComponent } from "@sinequa/galactik";
+import { Confirm } from "./confirm-dialog";
+
+@Component({
+  selector: "app-delete-item",
+  imports: [ButtonComponent],
+  template: `
+    <button variant="primary" size="md" (click)="deleteItem()">Delete item…</button>
+    @if (deleted()) {
+      <p>Item was deleted.</p>
+    }
+  `,
+})
+export class DeleteItemComponent {
+  protected readonly deleted = signal(false);
+
+  protected async deleteItem() {
+    const confirmed = await Confirm.call({ message: "Delete this item? This cannot be undone." });
+    if (confirmed) this.deleted.set(true);
+  }
+}
+```
+
+### Tooltip
+
+`TooltipDirective` (`[tooltip]`) opens on hover and on keyboard focus, and closes on `Escape`. It
+describes the element, it does not name it: an icon-only button still needs an `aria-label`.
+
+```ts
+import { Component } from "@angular/core";
+import { TooltipDirective } from "@sinequa/galactik";
+
+@Component({
+  selector: "app-tooltip-example",
+  imports: [TooltipDirective],
+  template: `
+    <button type="button" aria-label="Delete" tooltip="Delete this item" tooltipPosition="top">Delete</button>
+  `,
+})
+export class TooltipExampleComponent {}
+```
+
+## Releases
+
+A summary of the changes published for `@sinequa/galactik`. Versioning follows [SemVer](https://semver.org/): a **major** version may break the API, a **minor** version
+adds backward-compatible features, a **patch** fixes bugs.
+
+**2.1.1**
+
+- A non-native `DialogComponent` (`[dialog]`) now takes the focus when it opens, makes the page
+  behind it inert, keeps Tab from leaving the modal and gives the focus back to the element that
+  opened it on close.
+
+**2.1.0**
+
+- New `KeyboardIcon`.
+
+**2.0.0** — first published version of the library
+
+- Components added: `Autocomplete` (replaces `SearchSelect`), `Sheet`, `Sidebar`, `Textarea`,
+  `TagInput`, `TagRemove`, `Tree` (built on `@angular/aria/tree`), `RowGrid`, `RowFeed`, `Bullet`,
+  `Resizable*`, `Kbd`, `TooltipDirective` (opens on keyboard focus, closes on `Escape`),
+  `injectFloatingPanel()`, `BreakpointObserverService`, checkable menu items, decorative `Switch`.
+- Icon catalogue (over 120 icons) re-exported from the main barrel; icons now follow the size
+  imposed by their container.
+- Accessibility: focus rings that are actually painted, `SelectMenu` named from its label,
+  translatable `closeLabel` on `Dialog` / `Sheet`, `ariaLabel` on `SearchBar`, `fieldLabelLang` on
+  `Autocomplete`.
+- ⚠️ Behaviour changes: list item text is no longer truncated by default; content projected into
+  `SearchBar` renders between the clear button and the send button (use `slot="trailing"` to keep
+  it at the end of the field); `Tooltip`: `life` defaults to 0.
+- Compatible with `@angular/aria` 22.2 (`ToggleGroup` owns its selection).
+
 ## Development
 
 This library is part of the `atomic-angular` workspace and is built with the Angular CLI: