@mk-kit/ui 0.34.0 → 0.34.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +118 -34
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,12 +1,17 @@
1
1
  # @mk-kit/ui
2
2
 
3
- **Themable, accessible Angular 22 component library for admin dashboards & UIs.**
3
+ **Themable, accessible Angular component library for admin dashboards, back-offices and internal tools.**
4
4
 
5
- Signals-first. WCAG 2.1 AA. Every pixel controlled by CSS variables. Light &
6
- dark mode out of the box. Zero runtime dependencies beyond Angular.
5
+ 165+ standalone components, directives and services — data tables, charts,
6
+ date & time pickers, editors, kanban, overlays, an app shell — written for
7
+ Angular 22 with signals and `OnPush` from day one. Every visual value is a
8
+ `--mk-*` CSS custom property; light and dark ship out of the box; WCAG 2.1 AA
9
+ is the target, not the marketing. MIT licensed. Zero runtime dependencies
10
+ beyond Angular.
7
11
 
8
- > Like Angular Material — but leaner, admin-oriented, and re-themable by editing
9
- > a handful of CSS custom properties.
12
+ - **Docs & live demos:** <https://github.com/mk-kit/mk-kit> (site: mk-kit.dev — coming soon)
13
+ - **Changelog:** [CHANGELOG.md](https://github.com/mk-kit/mk-kit/blob/main/CHANGELOG.md)
14
+ - **Issues:** <https://github.com/mk-kit/mk-kit/issues>
10
15
 
11
16
  ## Install
12
17
 
@@ -14,32 +19,33 @@ dark mode out of the box. Zero runtime dependencies beyond Angular.
14
19
  ng add @mk-kit/ui
15
20
  ```
16
21
 
17
- `ng add` installs the package from npm and wires the theme stylesheet into
18
- your `angular.json`. To do it by hand instead:
22
+ `ng add` installs the package and wires the theme stylesheet into
23
+ `angular.json`. By hand instead:
19
24
 
20
25
  ```bash
21
26
  npm install @mk-kit/ui
22
27
  ```
23
28
 
24
- Peer dependencies: `@angular/core`, `@angular/common`, `@angular/forms` (v22+).
29
+ Peer dependencies: `@angular/core`, `@angular/common`, `@angular/forms`,
30
+ `@angular/platform-browser` (^22) and `rxjs` (^7.8).
25
31
 
26
32
  ## Setup
27
33
 
28
- **1. Import the theme stylesheet** once (e.g. in `angular.json` `styles` or your
29
- global `styles.css`):
34
+ **1. Import the theme stylesheet** once (in `angular.json` `styles` or your
35
+ global stylesheet):
30
36
 
31
37
  ```css
32
38
  @import '@mk-kit/ui/styles.css';
33
39
  ```
34
40
 
35
- **2. Add the `mk-app` class** to your `<body>` (or a top-level wrapper) so the
36
- background, text color, fonts and themed scrollbars apply:
41
+ **2. Add the `mk-app` class** to `<body>` (or a top-level wrapper) so
42
+ background, text colour, fonts and themed scrollbars apply:
37
43
 
38
44
  ```html
39
45
  <body class="mk-app">
40
46
  ```
41
47
 
42
- **3. Use components** — everything is standalone, just import what you need:
48
+ **3. Use components** — everything is standalone; import what you need:
43
49
 
44
50
  ```ts
45
51
  import { Component, inject } from '@angular/core';
@@ -61,25 +67,64 @@ export class AppRoot {
61
67
  }
62
68
  ```
63
69
 
70
+ ## What's inside
71
+
72
+ | Group | Highlights |
73
+ |---|---|
74
+ | **Forms & inputs** (49) | text, number, password (strength meter), OTP, phone (country prefix), postal code, currency, card number, IBAN, tax id, masked input, tag input, select, autocomplete, multi-select, tree-select, transfer list, checkbox, radio, switch, slider, range slider, rating, colour picker, file upload (dropzone), signature pad, numeric keypad & on-screen keyboard, repeater (`FormArray`), form field with automatic validation messages, form error summary |
75
+ | **Date & time** | calendar, date picker, date-range picker, time picker, month/year picker, week picker, inline mini date, event calendar with editable week/day grid (drag to move / resize) |
76
+ | **Tables & grids** (6) | data table — sort, multi-select, expandable rows, grouping, sticky header, column resize / reorder / pin, inline cell edit, responsive stacking — plus `MkTableDataSource` for server-side sort/page/filter |
77
+ | **Charts** (12) | line/area, bar (stacked, horizontal, label fitting), donut, gauge, progress ring, scatter/bubble, radar, funnel, treemap, heatmap, calendar heatmap, sparkline — SVG, themed, accessible |
78
+ | **Data display** (25) | cards, lists, stat cards, badges, tags, chips, avatars & groups, timeline, description list, tree, empty state, countdown, QR code, diff view, JSON viewer, code block, virtual scroll, carousel, kanban |
79
+ | **Navigation & layout** (18) | app shell (responsive sidebar), nav list & groups, tabs, stepper, breadcrumb, pagination, menu, context menu, command palette (⌘K), page header, toolbar, splitter, drawer, scroll area, FAB, back-to-top |
80
+ | **Feedback & overlays** (20) | dialogs (+ `confirm()` / `alert()` / `prompt()`), bottom sheet, drawer, popover, popconfirm, hovercard, tooltip, toast, snackbar, alert, banner, result page, notification center, product tour, progress bar, loading bar, spinner, skeletons |
81
+ | **Editors & interactions** (22) | block editor (Notion-style, HTML round-trip), rich text, markdown renderer, code editor, log viewer, drag & drop, sortable list, @mentions, hotkeys, undo/redo history, permissions (`*mkCan`), clipboard, intersect, infinite scroll, ripple, scrollspy |
82
+ | **Media** (6) | image with states, gallery, lightbox, cropper, media manager |
83
+ | **Core services** | theme (light/dark/system + density), overlay & anchored panels, focus trap, live announcer, icon registry, i18n |
84
+
85
+ The full, searchable index lives in the docs (`/components-index`).
86
+
87
+ ## Entry points
88
+
89
+ Import from the umbrella `@mk-kit/ui`, or from a group to keep bundles lean:
90
+
91
+ ```ts
92
+ import { MkTable } from '@mk-kit/ui/table';
93
+ import { MkLineChart } from '@mk-kit/ui/data';
94
+ import { MkDatePicker } from '@mk-kit/ui/datetime';
95
+ ```
96
+
97
+ Available: `core`, `forms`, `datetime`, `table`, `data`, `navigation`,
98
+ `feedback`, `directives`, `dnd`, `media`, `icon`, `button`, `checkbox`, `chip`,
99
+ `context-menu`, `rich-text`, `block-editor`. `sideEffects: false` throughout.
100
+
64
101
  ## Theming
65
102
 
66
- The entire look is driven by `--mk-*` custom properties defined on `:root`.
67
- Override any of them — globally or scoped to a subtree — to re-brand instantly:
103
+ The entire look is driven by `--mk-*` custom properties on `:root`. Override
104
+ any of them — globally, or scoped to a subtree — to re-brand at runtime, no
105
+ rebuild:
68
106
 
69
107
  ```css
70
108
  :root {
71
- --mk-primary: #7c3aed;
72
- --mk-primary-hover: #6d28d9;
109
+ --mk-primary: #0f766e;
110
+ --mk-primary-contrast: #ffffff;
73
111
  --mk-radius-md: 4px;
74
112
  --mk-font-sans: 'Inter', system-ui, sans-serif;
75
113
  }
114
+
115
+ [data-mk-theme='dark'] {
116
+ --mk-primary: #2dd4bf;
117
+ --mk-primary-contrast: #042f2e;
118
+ }
76
119
  ```
77
120
 
121
+ The docs include a theme builder that exports a ready-to-paste `:root` block.
122
+
78
123
  ### Dark mode
79
124
 
80
- Dark mode works with no JavaScript — it follows the OS `prefers-color-scheme`.
81
- To let users choose explicitly, set `data-mk-theme` on `<html>` (`"light"` |
82
- `"dark"`), or use the built-in `MkThemeService`:
125
+ Dark mode follows the OS `prefers-color-scheme` with no JavaScript. To let
126
+ users choose, set `data-mk-theme` on `<html>` (`"light"` | `"dark"`) or use
127
+ `MkThemeService`:
83
128
 
84
129
  ```ts
85
130
  const theme = inject(MkThemeService);
@@ -89,26 +134,65 @@ theme.toggle(); // flip light/dark
89
134
  theme.resolvedTheme(); // signal: 'light' | 'dark'
90
135
  ```
91
136
 
92
- The service persists the choice to `localStorage` and is fully SSR-safe.
137
+ The choice is persisted to `localStorage`; the service is SSR-safe.
93
138
 
94
- ## What's inside
139
+ ### Density & touch
95
140
 
96
- - **Forms** — Button, FormField, Input, Select, Checkbox, Radio, Switch, Slider
97
- - **Data** — Table (sortable/sticky), Card, Badge, Tag, Chip, Avatar, List,
98
- StatCard, ProgressBar, Spinner, Skeleton, Divider
99
- - **Feedback** — Alert, Toast, Dialog (+confirm), Tooltip
100
- - **Navigation & layout** — Tabs, Accordion, Breadcrumb, Pagination, Menu,
101
- AppShell, NavList
141
+ Three densities — `comfortable`, `compact`, `touch` — via `data-mk-density`
142
+ or `MkThemeService.setDensity()`. Touch density enlarges every hit target;
143
+ inputs use 16px text on coarse pointers, drag starts on long-press, overlays
144
+ respect safe-area insets.
102
145
 
103
- All components: `OnPush`, signal inputs/outputs, keyboard-operable, screen-reader
104
- labelled, `:focus-visible` rings, and `prefers-reduced-motion` aware.
146
+ ## Internationalisation
147
+
148
+ Every string the library renders comes from one provider:
149
+
150
+ ```ts
151
+ import { provideMkI18n } from '@mk-kit/ui/core';
152
+
153
+ bootstrapApplication(AppRoot, {
154
+ providers: [provideMkI18n({ close: 'Zamknij', noData: 'Brak danych' })],
155
+ });
156
+ ```
157
+
158
+ Overrides can be scoped to a component subtree for mixed-locale screens.
159
+ Layout and arrow keys flip under `dir="rtl"`.
105
160
 
106
161
  ## Accessibility
107
162
 
108
- mk-kit targets **WCAG 2.1 AA**: semantic roles, complete `aria-*` wiring, focus
109
- trapping for overlays, roving tabindex for composite widgets, live-region status
110
- announcements, and color contrast that holds in both themes. Information is never
111
- conveyed by color alone.
163
+ Target: **WCAG 2.1 AA**. Semantic roles and complete `aria-*` wiring, roving
164
+ tabindex for composite widgets, focus trapping and background `inert` for
165
+ modals, an Escape that closes only the topmost overlay, live-region
166
+ announcements for async state, contrast-checked tokens in both themes,
167
+ `prefers-reduced-motion` and `forced-colors` support. Axe runs over rendered
168
+ fixtures in the test suite; information is never conveyed by colour alone.
169
+
170
+ ## SSR & zoneless
171
+
172
+ Every component guards non-browser platforms (an SSR smoke suite renders the
173
+ whole library on the server), and nothing depends on Zone.js.
174
+
175
+ ## Coming from PrimeNG?
176
+
177
+ The admin surface maps closely — `p-table` → `mk-table`, `p-select` →
178
+ `mk-select`, `p-datePicker` → `mk-date-picker`, `DialogService` →
179
+ `MkDialogService`, `MessageService` → `MkToastService` — and the parts
180
+ PrimeUI sells separately (charts, text editor, scheduler, task board) are
181
+ here under MIT. The docs landing page carries a mapping table.
182
+
183
+ ## Versioning & support
184
+
185
+ mk-kit tracks the current Angular major. A matching release follows each new
186
+ Angular major within weeks; the previous major keeps receiving fixes for six
187
+ months. Releases are published from CI with npm provenance
188
+ (`npm audit signatures`).
189
+
190
+ ## Contributing
191
+
192
+ See [CONTRIBUTING.md](https://github.com/mk-kit/mk-kit/blob/main/CONTRIBUTING.md)
193
+ (DCO sign-off), [SECURITY.md](https://github.com/mk-kit/mk-kit/blob/main/SECURITY.md)
194
+ for vulnerability reports, and [TRADEMARK.md](https://github.com/mk-kit/mk-kit/blob/main/TRADEMARK.md)
195
+ for use of the name and logo.
112
196
 
113
197
  ## License
114
198
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mk-kit/ui",
3
- "version": "0.34.0",
3
+ "version": "0.34.1",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },