@sinequa/galactik 0.0.0-stage → 2.1.0

package/README.md

@@ -1,3 +1,156 @@
-# Temporary Holding Version
+# @sinequa/galactik
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Angular UI primitives built on top of [`@angular/aria`](https://www.npmjs.com/package/@angular/aria), [`@floating-ui/dom`](https://floating-ui.com/) and [`class-variance-authority`](https://cva.style/), designed to be composed and themed with Tailwind CSS.
+
+## Requirements
+
+- Angular `^22.0.0`
+- `@angular/aria` `^22.0.0`
+
+## Installation
+
+```bash
+npm install @sinequa/galactik
+```
+
+## Contributing
+
+`CONTRIBUTING.md` is the contract for working inside this library: project layout, file and
+naming conventions, how components are written, the tokens-only styling rule, accessibility,
+the public API, documentation, tests, and the checklists for adding a component or migrating
+one from `@sinequa/ui`.
+
+## Exports
+
+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
+
+## Usage
+
+### Menu
+
+`Menu` exposes the `itemSelected` output — it emits the `value` of the chosen `<MenuItem>` (keyboard or mouse). Items that open a submenu never emit.
+
+> **Note** — always declare the template ref with the `exportAs` form (`#menu="menu"`). Without it, Angular types the reference as the host `HTMLElement` instead of the `MenuComponent` instance, which makes `[menuTrigger]="menu"` fail type-checking and prevents accessing the component's API.
+
+```ts
+import { Component } from "@angular/core";
+import { MenuComponent, MenuContentComponent, MenuItemComponent, MenuTriggerDirective } from "@sinequa/galactik";
+
+@Component({
+  selector: "app-menu-example",
+  imports: [MenuComponent, MenuContentComponent, MenuItemComponent, MenuTriggerDirective],
+  template: `
+    <button [menuTrigger]="menu">Open</button>
+    <Menu #menu="menu" (itemSelected)="onSelect($event)">
+      <MenuContent>
+        <MenuItem value="edit">Edit</MenuItem>
+        <MenuItem value="delete">Delete</MenuItem>
+      </MenuContent>
+    </Menu>
+  `,
+})
+export class MenuExampleComponent {
+  onSelect(value: string) {
+    console.log("Selected item:", value);
+  }
+}
+```
+
+#### Submenus
+
+Nest a `<SubMenu>` inside a `<MenuItem>` and wire them together with `[submenu]`:
+
+```ts
+import { Component } from "@angular/core";
+import { MenuComponent, MenuContentComponent, MenuItemComponent, MenuTriggerDirective, SubMenuComponent } from "@sinequa/galactik";
+
+@Component({
+  selector: "app-submenu-example",
+  imports: [MenuComponent, MenuContentComponent, MenuItemComponent, MenuTriggerDirective, SubMenuComponent],
+  template: `
+    <button [menuTrigger]="menu">Open</button>
+    <Menu #menu="menu" (itemSelected)="onSelect($event)">
+      <MenuContent>
+        <MenuItem value="copy">Copy</MenuItem>
+        <MenuItem value="more" [submenu]="moreSub">More…</MenuItem>
+
+        <SubMenu #moreSub="ngMenu">
+          <MenuItem value="rename">Rename</MenuItem>
+          <MenuItem value="delete">Delete</MenuItem>
+        </SubMenu>
+      </MenuContent>
+    </Menu>
+  `,
+})
+export class SubmenuExampleComponent {
+  onSelect(value: string) {
+    console.log("Selected item:", value);
+  }
+}
+```
+
+> **Note** — the ref must be `#moreSub="ngMenu"`, **not** `="submenu"`. The `[submenu]` input on `<MenuItem>` expects the underlying `Menu` directive instance from `@angular/aria` (exported as `ngMenu`), which `<SubMenu>` applies via `hostDirectives`. Exporting `="submenu"` would give you the wrapper component instead, and `[submenu]="moreSub"` would fail type-checking.
+
+### Tabs
+
+`TabList` re-exposes the `selectedTabChange` output from `@angular/aria` — it emits the `value` of the currently selected tab.
+
+```ts
+import { Component } from "@angular/core";
+import { TabsComponent, TabListComponent, TabComponent, TabPanelComponent } from "@sinequa/galactik";
+
+@Component({
+  selector: "app-tabs-example",
+  imports: [TabsComponent, TabListComponent, TabComponent, TabPanelComponent],
+  template: `
+    <Tabs>
+      <TabList (selectedTabChange)="onTabChange($event)">
+        <Tab value="overview">Overview</Tab>
+        <Tab value="details">Details</Tab>
+      </TabList>
+      <TabPanel value="overview">Overview content</TabPanel>
+      <TabPanel value="details">Details content</TabPanel>
+    </Tabs>
+  `,
+})
+export class TabsExampleComponent {
+  onTabChange(value: string) {
+    console.log("Selected tab:", value);
+  }
+}
+```
+
+### Popover / Dropdown
+
+The `[popover]` and `[dropdown]` selectors are provided by the same directive. Use `[dropdown]` when you want the floating panel to close on click (it's the default for the dropdown alias).
+
+```ts
+import { Component } from "@angular/core";
+import { DropdownDirective } from "@sinequa/galactik";
+
+@Component({
+  selector: "app-popover-example",
+  imports: [DropdownDirective],
+  template: `
+    <button popovertarget="my-dropdown">Open</button>
+    <div dropdown id="my-dropdown" placement="bottom-start">
+      Dropdown content
+    </div>
+  `,
+})
+export class PopoverExampleComponent {}
+```
+
+## Development
+
+This library is part of the `atomic-angular` workspace and is built with the Angular CLI:
+
+```bash
+ng build galactik
+ng test galactik
+```