@besaitech/ng-design-system 0.0.11

package/README.md

@@ -0,0 +1,219 @@
+# @besaitech/ng-design-system
+
+Reusable **Angular 20** component library (`sds-` prefix) styled with **Tailwind CSS v4**, based on
+the Saitech visual language. Buttons, inputs, selects, tables, tabs, accordions, a date picker,
+phone input, plus the app shell (top bar + sidebar).
+
+> **Important:** components are styled with Tailwind utility classes that live *in their templates* —
+> the package does **not** ship compiled CSS. Your app must run Tailwind v4, scan this package, and
+> define the design tokens (see [Tailwind setup](#3-tailwind-v4-setup)). Without that step the
+> components render unstyled.
+
+---
+
+## Requirements
+
+- Angular **20.3+, 21.x or 22.x** (`@angular/common`, `core`, `forms`, `platform-browser`, `router`)
+- Tailwind CSS **v4** in the consuming app
+
+---
+
+## 1. Install
+
+```bash
+npm install @besaitech/ng-design-system
+```
+
+Published to the public npm registry, so no `.npmrc` and no read token are needed.
+
+> Earlier releases were served from an internal GitLab Package Registry and this section carried the
+> `@besaitech:registry=…` + `_authToken=…` lines for it. Those instructions no longer match where the
+> package comes from — following them against a public install yields a 401 for a registry you do not
+> need to reach.
+
+## 2. Tailwind setup
+
+The Angular peer dependencies (`@angular/common`, `core`, `forms`, …) are already present in any
+Angular 20.3+ / 21 / 22 app. If you don't have Tailwind yet, add it as a dev dependency:
+
+```bash
+npm install -D tailwindcss @tailwindcss/postcss
+```
+
+## 3. Tailwind v4 setup
+
+This is the step that makes the components look right. Tailwind v4 is CSS-first — there is no
+`tailwind.config.js`.
+
+**a. Register the PostCSS plugin.** Create `.postcssrc.json` at your project root:
+
+```json
+{
+  "plugins": {
+    "@tailwindcss/postcss": {}
+  }
+}
+```
+
+**b. Import Tailwind, scan the library, and define the tokens** in your global stylesheet
+(`src/styles.css`). The `@source` line is what tells Tailwind to generate the utility classes used
+*inside* the library, and the `@theme` block defines the colors/radii those classes refer to —
+**both are required**:
+
+```css
+@import "tailwindcss";
+
+/* Generate the utilities used inside @besaitech/ng-design-system templates.
+   Path is relative to THIS file (src/styles.css → ../node_modules). */
+@source "../node_modules/@besaitech/ng-design-system";
+
+/* Brand ramp: pick a theme preset. Must come AFTER the tailwindcss import —
+   Tailwind v4 processes @theme in imported files and later declarations win. */
+@import "@besaitech/ng-design-system/themes/saitech.css";  /* blues */
+/* @import "@besaitech/ng-design-system/themes/belvigo.css";   black */
+
+/* Everything else is yours to tune (Tailwind utilities + CSS vars). */
+@theme {
+  /* Neutrals / surfaces */
+  --color-canvas: #f5f6f8;
+  --color-surface: #ffffff;
+  --color-muted: #f8f9fb;
+  --color-border: #e6e9f0;
+  --color-ink: #1b2440;
+  --color-ink-soft: #5b6577;
+  --color-ink-faint: #8a93a6;
+
+  /* Accent icon-tiles (foreground + soft background) */
+  --color-accent-blue: #2f6bd4;
+  --color-accent-blue-soft: #e8effb;
+  --color-accent-green: #1f9d57;
+  --color-accent-green-soft: #e6f5ec;
+  --color-accent-amber: #e0902a;
+  --color-accent-amber-soft: #fdf0dd;
+  --color-accent-red: #df4f6b;
+  --color-accent-red-soft: #fde7ec;
+  --color-accent-indigo: #6c5ce7;
+  --color-accent-indigo-soft: #ece9fb;
+
+  /* Status */
+  --color-success: #27c06b;
+  --color-warning: #f3b73c;
+  --color-danger: #df4f6b;
+
+  /* Radius */
+  --radius-control: 0.5rem;
+  --radius-card: 0.75rem;
+
+  /* Typography */
+  --font-sans: "Inter", "Segoe UI", system-ui, -apple-system, sans-serif;
+}
+
+/* Layout dimensions used by <sds-shell> / <sds-sidebar> / <sds-topbar>.
+   Only needed if you use the layout components. */
+@layer base {
+  :root {
+    --sds-topbar-h: 64px;
+    --sds-sidebar-w: 256px;
+    --sds-sidebar-w-collapsed: 76px;
+  }
+
+  body {
+    margin: 0;
+    font-family: var(--font-sans);
+    background-color: var(--color-canvas);
+    color: var(--color-ink);
+  }
+}
+```
+
+> Why `@source`? Tailwind v4 ignores `node_modules` by default. The explicit `@source` re-includes
+> this package so the classes baked into its compiled templates produce real CSS. If components show
+> up unstyled, this line (or a wrong relative path) is almost always the cause.
+
+## 4. Use a component
+
+All components are **standalone** — import the ones you need directly into a component's `imports`:
+
+```ts
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { SdsButton, SdsInput, SdsIcon } from '@besaitech/ng-design-system';
+
+@Component({
+  selector: 'app-member-form',
+  imports: [FormsModule, SdsButton, SdsInput, SdsIcon],
+  template: `
+    <sds-input label="Nom" [(ngModel)]="name" leadingIcon="search" clearable />
+
+    <sds-button variant="primary" (click)="save()">
+      <sds-icon sdsIconLeading name="user-plus" [size]="18" />
+      Créer un membre
+    </sds-button>
+  `,
+})
+export class MemberForm {
+  name = '';
+  save() {/* ... */}
+}
+```
+
+Form controls (`sds-input`, `sds-textarea`, `sds-select`, `sds-multi-select`, `sds-toggle-switch`,
+`sds-date-picker`, `sds-phone-input`) implement `ControlValueAccessor`, so they work with both
+template-driven (`[(ngModel)]`) and reactive (`formControlName`) forms.
+
+---
+
+## Component catalog
+
+Import names are the `Sl…` classes; the markup selectors are `sds-…`.
+
+**Controls & primitives**
+
+| Component | Selector | Notes |
+| --- | --- | --- |
+| `SdsButton` | `<sds-button>` | `variant` (primary·secondary·tertiary·ghost·danger), `size`, `loading`, `block`, `iconOnly`; `[sdsIconLeading]`/`[sdsIconTrailing]` slots |
+| `SdsInput` | `<sds-input>` | CVA. `label`, `hint`, `error`, `size`, `appearance` (default·on-brand), `leading/trailingIcon`, `clearable` |
+| `SdsTextarea` | `<sds-textarea>` | CVA. Auto-grow, `label`, `hint`, `error` |
+| `SdsToggleSwitch` | `<sds-toggle-switch>` | CVA boolean toggle |
+| `SdsSelect` | `<sds-select>` | CVA single-select dropdown |
+| `SdsMultiSelect` | `<sds-multi-select>` | CVA multi-select with chips |
+| `SdsDatePicker` / `SdsCalendar` | `<sds-date-picker>` / `<sds-calendar>` | CVA date field + popover calendar (`date-utils` helpers) |
+| `SdsPhoneInput` | `<sds-phone-input>` | CVA phone field with country selector (`phone-countries`) |
+| `SdsIcon` | `<sds-icon>` | Inline-SVG icon; `name`, `size`, `strokeWidth` |
+| `SdsAvatar` | `<sds-avatar>` | Initials/image + status dot |
+| `SdsBadge` | `<sds-badge>` | Status pill; `variant`, `dot` |
+| `SdsCard` | `<sds-card>` | Surface container; `variant`, `interactive`, `padding` |
+
+**Composite**
+
+| Component | Selectors |
+| --- | --- |
+| Tabs | `<sds-tabs>` · `<sds-tab-list>` · `<sds-tab>` · `<sds-tab-panels>` · `<sds-tab-panel>` |
+| Accordion | `<sds-accordion>` · `<sds-accordion-panel>` · `<sds-accordion-header>` · `<sds-accordion-content>` |
+| Table | `<sds-table>` · `<sds-table-cell>` · `<sds-table-row-expansion>` |
+| Paginator | `<sds-paginator>` |
+
+**Layout** (use the design tokens / layout vars from step 3b)
+
+| Component | Selector | Notes |
+| --- | --- | --- |
+| `SdsShell` | `<sds-shell>` | Top bar + sidebar + scrollable content; `[sdsTopbar]`/`[sdsSidebar]` slots |
+| `SdsTopbar` | `<sds-topbar>` | `appName`, `user`, `(logout)`; `[sdsLogo]` slot |
+| `SdsSidebar` + `SdsNavGroup` + `SdsNavItem` | `<sds-sidebar>` … | Collapsible nav rail; collapse state via root-provided `SidebarStore`; items render `routerLink` or `<button>` |
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+| --- | --- |
+| `404 Project not found` on install | `.npmrc` missing the `@besaitech:registry` line, or token lacks access to project 922 |
+| `403 insufficient_scope` | Token is missing `read_package_registry` scope |
+| Components render unstyled | Missing/incorrect `@source` line, or no theme preset imported (step 3b) |
+| Brand colours are wrong / absent | The theme preset is imported BEFORE `@import "tailwindcss"`, so it is overridden |
+| `sds-icon` shows nothing | The `name` isn't in the icon registry; check available names via the `SdsIconName` type |
+
+## Versioning
+
+Semver. Each release is published from the workspace with `npm run release:lib` (bump → build →
+publish). Pin a version in your app and bump deliberately.