@sd-angular/core 19.0.0-beta.89 → 19.0.0-beta.91

package/assets/scss/README.md

@@ -0,0 +1,524 @@
+# SD Angular — SCSS Documentation
+
+## Mục lục
+
+1. [Cài đặt vào Angular](#1-cài-đặt-vào-angular)
+2. [Hệ thống màu sắc](#2-hệ-thống-màu-sắc)
+3. [Custom theme](#3-custom-theme)
+4. [Utility classes](#4-utility-classes)
+   - [Spacing](#spacing--margin--padding)
+   - [Sizing](#sizing--width--height)
+   - [Border](#border)
+   - [Grid & Layout](#grid--layout)
+   - [Flexbox](#flexbox)
+   - [Display](#display)
+   - [Gap](#gap)
+   - [Typography](#typography)
+   - [Overflow](#overflow)
+   - [Position](#position)
+   - [Elevation](#elevation)
+   - [Misc](#misc)
+
+---
+
+## 1. Cài đặt vào Angular
+
+Thêm vào `angular.json` (trong phần `styles` của build target):
+
+```json
+"styles": [
+  "./node_modules/@sd-angular/core/assets/scss/sd-core.scss",
+  "src/styles.scss"
+]
+```
+
+`sd-core.scss` bao gồm toàn bộ: reset CSS, utilities, màu theme, form overrides, scrollbar, và Angular Material theme.
+
+---
+
+## 2. Hệ thống màu sắc
+
+Màu được định nghĩa dưới dạng **CSS custom properties** có tiền tố `--sd-*`, cho phép override runtime (không cần recompile SCSS).
+
+### Màu mặc định
+
+| Token | CSS Variable | Giá trị mặc định | Dùng cho |
+|---|---|---|---|
+| `primary` | `--sd-primary` | `#2A66F4` | Màu chủ đạo — button, checkbox, accent |
+| `primary-light` | `--sd-primary-light` | `#EAF1FF` | Background nhẹ của primary |
+| `primary-dark` | `--sd-primary-dark` | `#1C4AD9` | Hover/active state của primary |
+| `info` | `--sd-info` | `#2962FF` | Link, thông tin, badge info |
+| `info-light` | `--sd-info-light` | `#E7E9FF` | Background nhẹ của info |
+| `info-dark` | `--sd-info-dark` | `#2240CC` | Hover state của info |
+| `success` | `--sd-success` | `#4CAF50` | Trạng thái thành công, validation OK |
+| `success-light` | `--sd-success-light` | `#DBEFDC` | Background nhẹ của success |
+| `success-dark` | `--sd-success-dark` | `#39833C` | Hover state của success |
+| `warning` | `--sd-warning` | `#FF9600` | Cảnh báo, trạng thái cần chú ý |
+| `warning-light` | `--sd-warning-light` | `#FFEACC` | Background nhẹ của warning |
+| `warning-dark` | `--sd-warning-dark` | `#BF7000` | Hover state của warning |
+| `error` | `--sd-error` | `#F82C13` | Lỗi, validation fail, trạng thái nguy hiểm |
+| `error-light` | `--sd-error-light` | `#FED5D0` | Background nhẹ của error |
+| `error-dark` | `--sd-error-dark` | `#BA200E` | Hover state của error |
+| `secondary` | `--sd-secondary` | `#212121` | Text phụ, icon secondary |
+| `secondary-light` | `--sd-secondary-light` | `#E9E9E9` | Background nhẹ |
+| `secondary-dark` | `--sd-secondary-dark` | `#000000` | — |
+| `light` | `--sd-light` | `#F8F9FA` | Background trang, surface nhẹ |
+| `dark` | `--sd-dark` | `#343A40` | Text đậm, dark surface |
+| `black500` | `--sd-black500` | `#212121` | Text chính |
+| `black400` | `--sd-black400` | `#757575` | Text phụ, placeholder |
+| `black300` | `--sd-black300` | `#BFBFBF` | Divider, border nhẹ |
+| `black200` | `--sd-black200` | `#E6E6E6` | Border mặc định, separator |
+| `black100` | `--sd-black100` | `#F2F2F2` | Background disabled, row hover |
+
+### Dùng màu trong SCSS component
+
+```scss
+@use '@sd-angular/core/assets/scss/core/color.scss' as color;
+@use 'sass:map';
+
+.my-element {
+  color: map.get(color.$color_map, 'primary');
+  background: map.get(color.$color_map, 'primary-light');
+  border-color: map.get(color.$color_map, 'black200');
+}
+```
+
+### Dùng màu qua utility class trong template
+
+```html
+<!-- Text color -->
+<span class="text-primary">Primary</span>
+<span class="text-error">Lỗi</span>
+<span class="text-secondary">Phụ</span>
+<span class="text-success">Thành công</span>
+<span class="text-warning">Cảnh báo</span>
+
+<!-- Background color -->
+<div class="bg-primary-light">...</div>
+<div class="bg-error-light">...</div>
+<div class="bg-white">...</div>
+
+<!-- Border color -->
+<div class="border-primary">...</div>
+```
+
+Tất cả token đều có class: `.text-{token}`, `.bg-{token}`, `.border-{token}`.
+
+---
+
+## 3. Custom theme
+
+Trong `styles.scss` của ứng dụng, import theme mixin và Angular Material, sau đó gọi `sd.theme()` với các màu muốn override.
+
+Chỉ cần khai báo các màu muốn **thay đổi** — màu không khai báo sẽ dùng giá trị mặc định.
+
+```scss
+@use '@sd-angular/core/assets/scss/themes/default' as sd;
+@use '@angular/material' as mat;
+@include mat.core();
+
+html {
+  @include sd.theme(
+    (
+      primary:         #AE7129,
+      primary-light:   #F4F2F1,
+      primary-dark:    #6B4414,
+    )
+  );
+}
+
+// --- Angular Material M2 Palette ---
+
+$custom-primary-palette: mat.m2-define-palette((
+  50: #F4F2F1,
+  100: #E7E1DA,
+  200: #DAC8B4,
+  300: #D1AC80,
+  400: #CD9450,
+  500: #AE7129,
+  600: #8D5A1E,
+  700: #6B4414,
+  800: #4B2F0E,
+  900: #34210A,
+  contrast: (
+    600: white,
+    700: white,
+    800: white,
+    900: white,
+  )
+));
+
+$custom-accent-palette: mat.m2-define-palette((
+  50: #F1F3F1,
+  100: #DCE5DD,
+  200: #BBD3BC,
+  300: #8FC291,
+  400: #67B76A,
+  500: #4CAF50,
+  600: #3A8C3D,
+  700: #29692C,
+  800: #1C471E,
+  900: #132F14,
+  contrast: (
+    700: white,
+    800: white,
+    900: white,
+  )
+));
+
+$custom-warn-palette: mat.m2-define-palette((
+  50: #F5F0F0,
+  100: #EAD9D6,
+  200: #E4B0AA,
+  300: #E6786B,
+  400: #EE4430,
+  500: #F82C13,
+  600: #D11801,
+  700: #9A1100,
+  800: #680B00,
+  900: #440700,
+  contrast: (
+    600: white,
+    700: white,
+    800: white,
+    900: white,
+  )
+));
+
+$custom-theme: mat.m2-define-light-theme((
+  color: (
+    primary: $custom-primary-palette,
+    accent:  $custom-accent-palette,
+    warn:    $custom-warn-palette,
+  ),
+  density: -3,
+));
+
+@include mat.all-component-themes($custom-theme);
+```
+
+> **Lưu ý:** `sd.theme()` và `mat.all-component-themes()` đều cần được gọi trong `styles.scss`, không phải trong component SCSS.
+
+---
+
+## 4. Utility classes
+
+Tất cả utility classes đều có `!important` để đảm bảo override được khi kết hợp với Angular Material.
+
+---
+
+### Spacing — Margin & Padding
+
+Hệ thống spacing theo đơn vị **px**, range từ 0 đến 200.
+
+```
+m-{n}     mt-{n}    mr-{n}    mb-{n}    ml-{n}    mx-{n}    my-{n}
+p-{n}     pt-{n}    pr-{n}    pb-{n}    pl-{n}    px-{n}    py-{n}
+```
+
+Ví dụ: `m-0`, `mt-8`, `px-16`, `py-24`, `mb-4`
+
+**Auto margin:**
+```
+m-auto   mt-auto   mr-auto   mb-auto   ml-auto   mx-auto   my-auto
+```
+
+---
+
+### Sizing — Width & Height
+
+**Theo px** (0–200): `w-{n}`, `h-{n}`
+
+**Theo %/keyword:**
+
+| Class | CSS |
+|---|---|
+| `w-full` | `width: 100%` |
+| `w-100` | `width: 100%` (alias) |
+| `w-auto` | `width: auto` |
+| `w-screen` | `width: 100vw` |
+| `w-fit` | `width: fit-content` |
+| `h-full` | `height: 100%` |
+| `h-100` | `height: 100%` (alias) |
+| `h-auto` | `height: auto` |
+| `h-screen` | `height: 100vh` |
+| `h-fit` | `height: fit-content` |
+| `min-h-full` | `min-height: 100%` |
+| `min-h-screen` | `min-height: 100vh` |
+| `min-w-full` | `min-width: 100%` |
+| `max-h-full` | `max-height: 100%` |
+| `max-w-full` | `max-width: 100%` |
+
+---
+
+### Border
+
+**Border-radius** (0–200px): `rounded-{n}`, `rounded-full` (9999px)
+
+**Border utilities:**
+
+| Class | CSS |
+|---|---|
+| `border` | `border: 1px solid var(--sd-black200)` |
+| `border-0` | `border: 0` |
+| `border-top` | `border-top: 1px solid var(--sd-black200)` |
+| `border-bottom` | `border-bottom: 1px solid var(--sd-black200)` |
+| `border-left` | `border-left: 1px solid var(--sd-black200)` |
+| `border-right` | `border-right: 1px solid var(--sd-black200)` |
+
+---
+
+### Grid & Layout
+
+#### Flexbox row/col
+
+```html
+<div class="row">
+  <div class="col-6">50%</div>
+  <div class="col-6">50%</div>
+</div>
+```
+
+`.row` là flex container có gutter `16px`. Các class `.col-{1-12}` chia theo 12 cột.
+
+**Gutter variants:**
+
+| Class | Gutter |
+|---|---|
+| `row` | 16px (mặc định) |
+| `row-md` | 8px |
+| `row-sm` | 4px |
+| `row-xs` | 2px |
+
+**Responsive columns** (mobile-first — áp dụng từ breakpoint trở lên):
+
+| Class | Min-width |
+|---|---|
+| `col-sm-{1-12}` | ≥ 576px |
+| `col-md-{1-12}` | ≥ 768px |
+| `col-lg-{1-12}` | ≥ 992px |
+| `col-xl-{1-12}` | ≥ 1200px |
+
+Ví dụ:
+```html
+<div class="row">
+  <!-- Full width trên mobile, 50% từ md trở lên, 33% từ lg trở lên -->
+  <div class="col-md-6 col-lg-4">...</div>
+</div>
+```
+
+#### CSS Grid container
+
+```html
+<div class="grid-container grid-cols-3">
+  <div class="col-span-2">Chiếm 2 cột</div>
+  <div class="col-span-1">Chiếm 1 cột</div>
+  <div class="col-span-full">Full width</div>
+</div>
+```
+
+| Class | Mô tả |
+|---|---|
+| `grid-container` | `display: grid`, gutter cột 8px |
+| `grid-cols-{1-12}` | Số cột của grid |
+| `col-span-{1-12}` | Chiếm n cột |
+| `col-span-full` | Chiếm toàn bộ chiều ngang |
+| `row-span-{1-12}` | Chiếm n hàng |
+| `row-span-full` | Chiếm toàn bộ chiều dọc |
+
+---
+
+### Flexbox
+
+**Flex shorthand:**
+
+| Class | CSS |
+|---|---|
+| `flex-1` | `flex: 1` |
+| `flex-none` | `flex: none` |
+| `flex-auto` | `flex: auto` |
+
+**Direction:**
+```
+flex-row   flex-column   flex-row-reverse   flex-column-reverse
+```
+
+**Wrap:**
+```
+flex-wrap   flex-nowrap
+```
+
+**Grow & shrink:**
+```
+flex-grow-0   flex-grow-1   flex-shrink-0   flex-shrink-1
+```
+
+**Align items:**
+```
+align-items-start   align-items-end   align-items-center
+align-items-baseline   align-items-stretch
+```
+
+**Align self:**
+```
+align-self-start   align-self-end   align-self-center
+align-self-stretch   align-self-auto
+```
+
+**Align content:**
+```
+align-content-start   align-content-end   align-content-center
+align-content-between   align-content-around   align-content-stretch
+```
+
+**Justify content:**
+```
+justify-content-start   justify-content-end   justify-content-center
+justify-content-between   justify-content-around   justify-content-evenly
+```
+
+---
+
+### Display
+
+| Class | CSS |
+|---|---|
+| `d-none` | `display: none` |
+| `d-block` | `display: block` |
+| `d-inline` | `display: inline` |
+| `d-inline-block` | `display: inline-block` |
+| `d-flex` | `display: flex` |
+| `d-inline-flex` | `display: inline-flex` |
+| `d-grid` | `display: grid` |
+
+---
+
+### Gap
+
+Hệ thống gap theo đơn vị **px**, range từ 0 đến 200.
+
+| Class | CSS |
+|---|---|
+| `gap-{n}` | `gap: npx` |
+| `gap-x-{n}` | `column-gap: npx` |
+| `gap-y-{n}` | `row-gap: npx` |
+
+Ví dụ: `gap-8`, `gap-x-16`, `gap-y-4`
+
+---
+
+### Typography
+
+#### Design token classes
+
+Hệ thống typography theo quy ước `T{size}{weight}` — `M` = Medium (500), `R` = Regular (400).
+
+| Class | Font size | Weight | Line height |
+|---|---|---|---|
+| `T48M` / `T48R` | 48px | 500 / 400 | 56px |
+| `T32M` / `T32R` | 32px | 500 / 400 | 48px |
+| `T24M` / `T24R` | 24px / 20px | 500 / 400 | 28px |
+| `T20M` / `T20R` | 20px | 500 / 400 | 28px |
+| `T18M` / `T18R` | 18px | 500 / 400 | 28px |
+| `T16M` / `T16R` | 16px | 500 / 400 | 24px |
+| `T14M` / `T14R` | 14px | 500 / 400 | 20px |
+| `T12M` / `T12R` | 12px | 500 / 400 | 16px |
+| `T10M` / `T10R` | 10px | 500 / 400 | 12px |
+
+#### Font-size utilities (px-based, 0–200)
+
+```
+fs-0   fs-12   fs-14   fs-16   ...   fs-200
+```
+
+#### Font-weight utilities
+
+```
+font-weight-light    (300)
+font-weight-normal   (400)
+font-weight-medium   (500)
+font-weight-bold     (600)
+font-weight-bolder   (700)
+```
+
+#### Text alignment
+
+```
+text-left   text-center   text-right   text-justify
+```
+
+#### Text wrapping & overflow
+
+| Class | CSS |
+|---|---|
+| `text-wrap` | `white-space: normal` |
+| `text-nowrap` | `white-space: nowrap` |
+| `text-ellipsis` | `overflow: hidden; text-overflow: ellipsis; white-space: nowrap` |
+| `text-break` | `overflow-wrap: break-word; word-break: break-word` |
+
+#### Text transform
+
+```
+text-uppercase   text-lowercase   text-capitalize
+```
+
+---
+
+### Overflow
+
+| Class | CSS |
+|---|---|
+| `overflow-auto` | `overflow: auto` |
+| `overflow-hidden` | `overflow: hidden` |
+| `overflow-visible` | `overflow: visible` |
+| `overflow-scroll` | `overflow: scroll` |
+| `overflow-x-auto` | `overflow-x: auto` |
+| `overflow-y-auto` | `overflow-y: auto` |
+
+---
+
+### Position
+
+```
+position-relative   position-absolute   position-fixed
+position-sticky     position-static
+```
+
+---
+
+### Elevation
+
+CSS shadow tĩnh tương đương Angular Material `mat-elevation-z{n}`.
+
+| Class | Dùng cho |
+|---|---|
+| `mat-elevation-z0` | Reset shadow |
+| `mat-elevation-z1` | Card, chip |
+| `mat-elevation-z2` | Button raised |
+| `mat-elevation-z3` | Card hover |
+| `mat-elevation-z4` | App bar |
+| `mat-elevation-z5` | — |
+| `mat-elevation-z6` | Floating action button |
+| `mat-elevation-z7` | — |
+| `mat-elevation-z8` | Dialog, drawer |
+
+---
+
+### Misc
+
+**Vertical align:**
+```
+align-middle   align-top   align-bottom   align-baseline
+```
+
+**Cursor:**
+```
+cursor-pointer   cursor-default   cursor-not-allowed
+```
+
+**Visibility:**
+
+| Class | CSS |
+|---|---|
+| `visible` | `visibility: visible` |
+| `invisible` | `visibility: hidden` |

package/assets/scss/core/bootstrap.scss

@@ -11,128 +11,3 @@
 @import '../bootstrap-4.6.2/reboot';
 @import '../bootstrap-4.6.2/utilities';
 @import '../bootstrap-4.6.2/grid';
-
-// Custom spacing utilities for any number (0-999)
-@for $i from 0 through 200 {
-  // Margin
-  .m-#{$i} {
-    margin: #{$i}px !important;
-  }
-  .mt-#{$i} {
-    margin-top: #{$i}px !important;
-  }
-  .mr-#{$i} {
-    margin-right: #{$i}px !important;
-  }
-  .mb-#{$i} {
-    margin-bottom: #{$i}px !important;
-  }
-  .ml-#{$i} {
-    margin-left: #{$i}px !important;
-  }
-  .mx-#{$i} {
-    margin-left: #{$i}px !important;
-    margin-right: #{$i}px !important;
-  }
-  .my-#{$i} {
-    margin-top: #{$i}px !important;
-    margin-bottom: #{$i}px !important;
-  }
-
-  // Padding
-  .p-#{$i} {
-    padding: #{$i}px !important;
-  }
-  .pt-#{$i} {
-    padding-top: #{$i}px !important;
-  }
-  .pr-#{$i} {
-    padding-right: #{$i}px !important;
-  }
-  .pb-#{$i} {
-    padding-bottom: #{$i}px !important;
-  }
-  .pl-#{$i} {
-    padding-left: #{$i}px !important;
-  }
-  .px-#{$i} {
-    padding-left: #{$i}px !important;
-    padding-right: #{$i}px !important;
-  }
-  .py-#{$i} {
-    padding-top: #{$i}px !important;
-    padding-bottom: #{$i}px !important;
-  }
-
-  // Border radius
-  .rounded-#{$i} {
-    border-radius: #{$i}px !important;
-  }
-
-  // Width height
-  .w-#{$i} {
-    width: #{$i}px !important;
-  }
-  .h-#{$i} {
-    height: #{$i}px !important;
-  }
-
-  // Font size
-  .fs-#{$i} {
-    font-size: #{$i}px !important;
-  }
-
-  // Gap
-  .gap-#{$i} {
-    gap: #{$i}px !important;
-  }
-
-  .gap-y-#{$i} {
-    row-gap: #{$i}px !important;
-  }
-
-  .gap-x-#{$i} {
-    column-gap: #{$i}px !important;
-  }
-}
-
-.flex-1 {
-  flex: 1;
-}
-
-.w-full {
-  width: 100% !important;
-}
-
-.h-full {
-  height: 100% !important;
-}
-
-.font-weight-medium {
-  font-weight: 500 !important;
-}
-
-// Custom grid
-.row-md {
-  @include make-row(16px);
-
-  > * {
-    @include make-col-ready(16px);
-  }
-}
-
-.row-sm {
-  @include make-row(8px);
-
-  > * {
-    @include make-col-ready(8px);
-  }
-}
-
-.row-xs {
-  @include make-row(4px);
-
-  > * {
-    @include make-col-ready(4px);
-  }
-}