npm - @mk-kit/ui - Versions diffs - 0.34.0 - Mend

@mk-kit/ui 0.34.0

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 (63) hide show

package/LICENSE +21 -0
package/README.md +115 -0
package/block-editor/README.md +254 -0
package/fesm2022/mk-kit-ui-block-editor.mjs +2158 -0
package/fesm2022/mk-kit-ui-block-editor.mjs.map +1 -0
package/fesm2022/mk-kit-ui-button.mjs +81 -0
package/fesm2022/mk-kit-ui-button.mjs.map +1 -0
package/fesm2022/mk-kit-ui-checkbox.mjs +136 -0
package/fesm2022/mk-kit-ui-checkbox.mjs.map +1 -0
package/fesm2022/mk-kit-ui-chip.mjs +122 -0
package/fesm2022/mk-kit-ui-chip.mjs.map +1 -0
package/fesm2022/mk-kit-ui-context-menu.mjs +144 -0
package/fesm2022/mk-kit-ui-context-menu.mjs.map +1 -0
package/fesm2022/mk-kit-ui-core.mjs +1576 -0
package/fesm2022/mk-kit-ui-core.mjs.map +1 -0
package/fesm2022/mk-kit-ui-data.mjs +6055 -0
package/fesm2022/mk-kit-ui-data.mjs.map +1 -0
package/fesm2022/mk-kit-ui-datetime.mjs +3409 -0
package/fesm2022/mk-kit-ui-datetime.mjs.map +1 -0
package/fesm2022/mk-kit-ui-directives.mjs +1779 -0
package/fesm2022/mk-kit-ui-directives.mjs.map +1 -0
package/fesm2022/mk-kit-ui-dnd.mjs +1073 -0
package/fesm2022/mk-kit-ui-dnd.mjs.map +1 -0
package/fesm2022/mk-kit-ui-feedback.mjs +2426 -0
package/fesm2022/mk-kit-ui-feedback.mjs.map +1 -0
package/fesm2022/mk-kit-ui-forms.mjs +9208 -0
package/fesm2022/mk-kit-ui-forms.mjs.map +1 -0
package/fesm2022/mk-kit-ui-icon.mjs +470 -0
package/fesm2022/mk-kit-ui-icon.mjs.map +1 -0
package/fesm2022/mk-kit-ui-media.mjs +896 -0
package/fesm2022/mk-kit-ui-media.mjs.map +1 -0
package/fesm2022/mk-kit-ui-navigation.mjs +2542 -0
package/fesm2022/mk-kit-ui-navigation.mjs.map +1 -0
package/fesm2022/mk-kit-ui-rich-text.mjs +565 -0
package/fesm2022/mk-kit-ui-rich-text.mjs.map +1 -0
package/fesm2022/mk-kit-ui-table.mjs +1378 -0
package/fesm2022/mk-kit-ui-table.mjs.map +1 -0
package/fesm2022/mk-kit-ui.mjs +32 -0
package/fesm2022/mk-kit-ui.mjs.map +1 -0
package/package.json +130 -0
package/schematics/collection.json +10 -0
package/schematics/ng-add/index.js +113 -0
package/schematics/ng-add/schema.json +22 -0
package/schematics/package.json +3 -0
package/styles/mk-kit.css +750 -0
package/types/mk-kit-ui-block-editor.d.ts +292 -0
package/types/mk-kit-ui-button.d.ts +40 -0
package/types/mk-kit-ui-checkbox.d.ts +62 -0
package/types/mk-kit-ui-chip.d.ts +59 -0
package/types/mk-kit-ui-context-menu.d.ts +57 -0
package/types/mk-kit-ui-core.d.ts +1105 -0
package/types/mk-kit-ui-data.d.ts +2580 -0
package/types/mk-kit-ui-datetime.d.ts +1171 -0
package/types/mk-kit-ui-directives.d.ts +807 -0
package/types/mk-kit-ui-dnd.d.ts +423 -0
package/types/mk-kit-ui-feedback.d.ts +1270 -0
package/types/mk-kit-ui-forms.d.ts +3586 -0
package/types/mk-kit-ui-icon.d.ts +108 -0
package/types/mk-kit-ui-media.d.ts +549 -0
package/types/mk-kit-ui-navigation.d.ts +1169 -0
package/types/mk-kit-ui-rich-text.d.ts +187 -0
package/types/mk-kit-ui-table.d.ts +739 -0
package/types/mk-kit-ui.d.ts +17 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Mateusz Kornaś
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,115 @@
+# @mk-kit/ui
+**Themable, accessible Angular 22 component library for admin dashboards & UIs.**
+Signals-first. WCAG 2.1 AA. Every pixel controlled by CSS variables. Light &
+dark mode out of the box. Zero runtime dependencies beyond Angular.
+> Like Angular Material — but leaner, admin-oriented, and re-themable by editing
+> a handful of CSS custom properties.
+## Install
+```bash
+ng add @mk-kit/ui
+```
+`ng add` installs the package from npm and wires the theme stylesheet into
+your `angular.json`. To do it by hand instead:
+```bash
+npm install @mk-kit/ui
+```
+Peer dependencies: `@angular/core`, `@angular/common`, `@angular/forms` (v22+).
+## Setup
+**1. Import the theme stylesheet** once (e.g. in `angular.json` `styles` or your
+global `styles.css`):
+```css
+@import '@mk-kit/ui/styles.css';
+```
+**2. Add the `mk-app` class** to your `<body>` (or a top-level wrapper) so the
+background, text color, fonts and themed scrollbars apply:
+```html
+<body class="mk-app">
+```
+**3. Use components** — everything is standalone, just import what you need:
+```ts
+import { Component, inject } from '@angular/core';
+import { MkButton, MkCard, MkThemeService } from '@mk-kit/ui';
+@Component({
+  selector: 'app-root',
+  imports: [MkButton, MkCard],
+  template: `
+    <mk-card variant="elevated">
+      <button mkButton tone="primary" (click)="theme.toggle()">
+        Toggle theme
+      </button>
+    </mk-card>
+  `,
+})
+export class AppRoot {
+  protected readonly theme = inject(MkThemeService);
+}
+```
+## Theming
+The entire look is driven by `--mk-*` custom properties defined on `:root`.
+Override any of them — globally or scoped to a subtree — to re-brand instantly:
+```css
+:root {
+  --mk-primary: #7c3aed;
+  --mk-primary-hover: #6d28d9;
+  --mk-radius-md: 4px;
+  --mk-font-sans: 'Inter', system-ui, sans-serif;
+}
+```
+### Dark mode
+Dark mode works with no JavaScript — it follows the OS `prefers-color-scheme`.
+To let users choose explicitly, set `data-mk-theme` on `<html>` (`"light"` |
+`"dark"`), or use the built-in `MkThemeService`:
+```ts
+const theme = inject(MkThemeService);
+theme.setTheme('dark');      // force dark
+theme.setTheme('system');    // follow the OS
+theme.toggle();              // flip light/dark
+theme.resolvedTheme();       // signal: 'light' | 'dark'
+```
+The service persists the choice to `localStorage` and is fully SSR-safe.
+## What's inside
+- **Forms** — Button, FormField, Input, Select, Checkbox, Radio, Switch, Slider
+- **Data** — Table (sortable/sticky), Card, Badge, Tag, Chip, Avatar, List,
+  StatCard, ProgressBar, Spinner, Skeleton, Divider
+- **Feedback** — Alert, Toast, Dialog (+confirm), Tooltip
+- **Navigation & layout** — Tabs, Accordion, Breadcrumb, Pagination, Menu,
+  AppShell, NavList
+All components: `OnPush`, signal inputs/outputs, keyboard-operable, screen-reader
+labelled, `:focus-visible` rings, and `prefers-reduced-motion` aware.
+## Accessibility
+mk-kit targets **WCAG 2.1 AA**: semantic roles, complete `aria-*` wiring, focus
+trapping for overlays, roving tabindex for composite widgets, live-region status
+announcements, and color contrast that holds in both themes. Information is never
+conveyed by color alone.
+## License
+MIT © Mateusz Kornaś

package/block-editor/README.md ADDED Viewed

@@ -0,0 +1,254 @@
+# Block Editor (`@mk-kit/ui`)
+A configurable, Gutenberg-style **block content editor** for authoring blog
+posts and content pages, plus a read-only **renderer** for displaying the saved
+document. Dependency-free: built on native `contenteditable` + the Selection API
+(`document.execCommand` is used for inline formatting — deprecated but
+universally supported and the only practical way to do inline formatting without
+a heavyweight editor engine).
+Everything is themed through `--mk-*` tokens (light/dark aware), keyboard
+operable, and WCAG 2.1 AA minded.
+```ts
+import {
+  MkBlockEditor,
+  MkBlockRenderer,
+  mkBlocksToHtml,
+  type MkBlockDocument,
+} from '@mk-kit/ui'; // (barrel: block-editor.barrel.ts)
+```
+---
+## 1. The document model
+The value is a small, 100% JSON-serialisable document — persist it as-is.
+```ts
+interface MkBlock {
+  id: string;                  // stable unique id
+  type: string;                // registry key: 'paragraph', 'columns', …
+  data: Record<string, any>;   // per-block state, e.g. { html } or { src, alt }
+  children?: MkBlock[];         // nested blocks (layout/columns)
+}
+interface MkBlockDocument {
+  version: number;             // schema version (MK_BLOCK_DOCUMENT_VERSION)
+  blocks: MkBlock[];           // top-level blocks, in order
+}
+```
+Built-in block `data` shapes:
+| type        | `data`                                                           | `children`         |
+| ----------- | ---------------------------------------------------------------- | ------------------ |
+| `paragraph` | `{ html }`                                                       | —                  |
+| `heading`   | `{ html, level: 1..4 }`                                          | —                  |
+| `list`      | `{ ordered: boolean, items: string[] }`                         | —                  |
+| `quote`     | `{ html, citation }`                                             | —                  |
+| `code`      | `{ code, language }`                                             | —                  |
+| `image`     | `{ src, alt, caption, align, width }`                            | —                  |
+| `embed`     | `{ url, embedUrl, provider, aspectRatio }`                      | —                  |
+| `button`    | `{ label, href, tone, variant, align }`                         | —                  |
+| `divider`   | `{}`                                                             | —                  |
+| `columns`   | `{ count, ratio, gap, align, justify }`                          | `column[]`         |
+| `column`    | `{}`                                                             | any block[]        |
+---
+## 2. Wiring the editor with `[(value)]`
+```ts
+import { Component, signal } from '@angular/core';
+import { MkBlockEditor, mkEmptyDocument, type MkBlockDocument } from '@mk-kit/ui';
+@Component({
+  selector: 'app-post-editor',
+  imports: [MkBlockEditor],
+  template: `<mk-block-editor [(value)]="doc" placeholder="Write your post…" />`,
+})
+export class PostEditor {
+  readonly doc = signal<MkBlockDocument>(mkEmptyDocument());
+}
+```
+Because the editor implements `ControlValueAccessor`, it also works with forms:
+```html
+<mk-block-editor [(ngModel)]="doc" />
+<mk-block-editor [formControl]="control" />
+```
+### Editor inputs / outputs
+| input            | type                            | notes                                            |
+| ---------------- | ------------------------------- | ------------------------------------------------ |
+| `value`          | `model<MkBlockDocument>`        | two-way document binding                         |
+| `blocks`         | `MkBlockDefinition[] \| null`   | custom/extended palette (merged over defaults)   |
+| `placeholder`    | `string`                        | empty text-block prompt                          |
+| `readonly`       | `boolean`                       | hides editing chrome                             |
+| `disabled`       | `boolean`                       | form-level disable                               |
+| `uploadHandler`  | `(f: File) => Promise<string>`  | image upload (see §4)                            |
+| `embedProviders` | `MkEmbedProvider[] \| null`     | extra embed providers (see §5)                   |
+| `ariaLabel`      | `string`                        | region label                                     |
+| **output**       |                                 |                                                  |
+| `change`         | `MkBlockDocument`               | fires on every edit (alongside the `value` model)|
+### Keyboard
+- **Enter** in a text block splits at the caret and starts a new paragraph.
+- **Backspace** at the start of an empty block deletes it and focuses the previous.
+- **Arrow Up/Down** at a block edge move the caret to the adjacent block.
+- **Select text** to reveal the floating toolbar (Bold, Italic, Underline,
+  Strikethrough, Inline code, Link, Clear).
+- The inserter is a combobox → listbox: type to filter, Arrow keys to move,
+  Enter to insert, Esc to close.
+---
+## 3. Providing a custom block (registerBlockType-style)
+A block is described by an `MkBlockDefinition`. Supply extras via the `blocks`
+input or, app-wide, via the `MK_BLOCK_DEFINITIONS` multi-token.
+```ts
+import { type MkBlockDefinition, MK_DEFAULT_BLOCKS, mkBlockId } from '@mk-kit/ui';
+const calloutBlock: MkBlockDefinition = {
+  type: 'callout',
+  label: 'Callout',
+  icon: '💡',
+  group: 'Text',
+  description: 'A highlighted note.',
+  keywords: ['note', 'tip', 'info'],
+  create: () => ({ id: mkBlockId('callout'), type: 'callout', data: { html: '', tone: 'info' } }),
+};
+// Per-editor:
+@Component({
+  template: `<mk-block-editor [(value)]="doc" [blocks]="palette" />`,
+})
+class Editor {
+  readonly palette = [...MK_DEFAULT_BLOCKS, calloutBlock];
+}
+```
+App-wide via the token (merged over `MK_DEFAULT_BLOCKS`, then the input wins):
+```ts
+import { MK_BLOCK_DEFINITIONS } from '@mk-kit/ui';
+providers: [
+  { provide: MK_BLOCK_DEFINITIONS, multi: true, useValue: [calloutBlock] },
+];
+```
+> The editor renders a built-in edit UI per known `type`. A brand-new `type`
+> appears in the inserter and serialises through your `create()` data, but the
+> editor shows an "Unknown block" placeholder unless the type matches a built-in
+> (extend the switch by contributing to the library, or model your custom block
+> on an existing `data` shape such as `{ html }`).
+---
+## 4. Image upload handler
+If an `uploadHandler` is provided (editor input **or** the
+`MK_BLOCK_UPLOAD_HANDLER` token), it is called with the chosen `File` and must
+resolve to a URL. Otherwise the image falls back to an inline `data:` URL via
+`FileReader`.
+```ts
+import { MK_BLOCK_UPLOAD_HANDLER } from '@mk-kit/ui';
+async function uploadToCdn(file: File): Promise<string> {
+  const body = new FormData();
+  body.append('file', file);
+  const res = await fetch('/api/upload', { method: 'POST', body });
+  return (await res.json()).url;
+}
+// Per editor:
+// <mk-block-editor [(value)]="doc" [uploadHandler]="uploadToCdn" />
+// Or app-wide:
+providers: [{ provide: MK_BLOCK_UPLOAD_HANDLER, useValue: uploadToCdn }];
+```
+The image block also accepts a pasted URL and drag-and-drop, and exposes alt
+text, caption, alignment and width settings.
+---
+## 5. Adding an embed provider
+Embeds render a **sandboxed** iframe for allow-listed providers (YouTube and
+Vimeo out of the box). Add your own:
+```ts
+import { type MkEmbedProvider } from '@mk-kit/ui';
+const codepen: MkEmbedProvider = {
+  name: 'CodePen',
+  test: /codepen\.io\/([\w-]+)\/pen\/([\w-]+)/i,
+  aspectRatio: 16 / 9,
+  toEmbedUrl(url) {
+    const m = url.match(/codepen\.io\/([\w-]+)\/pen\/([\w-]+)/i);
+    return m ? `https://codepen.io/${m[1]}/embed/${m[2]}` : null;
+  },
+};
+// <mk-block-editor [(value)]="doc" [embedProviders]="[codepen]" />
+// or app-wide: { provide: MK_BLOCK_EMBED_PROVIDERS, multi: true, useValue: [codepen] }
+```
+Non-matching URLs render a safe link card instead of an iframe.
+**Security model:** rich-text is stored as HTML but always sanitised — through
+`sanitizeInlineHtml` (an allow-list cleaner) on serialise, and Angular's
+`DomSanitizer` via `[innerHTML]` on render. The **only** value ever passed to
+`bypassSecurityTrustResourceUrl` is a provider-transformed `embedUrl`, never a
+raw pasted string.
+---
+## 6. Rendering saved content
+### Component (themed, interactive iframes)
+```ts
+import { MkBlockRenderer } from '@mk-kit/ui';
+@Component({
+  imports: [MkBlockRenderer],
+  template: `<mk-block-renderer [value]="doc()" />`,
+})
+class PublishedPost { /* doc() is a stored MkBlockDocument */ }
+```
+`mk-block-renderer` re-uses the editor's layout CSS, so authored columns look
+identical when published, and renders embeds as sandboxed iframes.
+### Static HTML string (SSG/SSR, emails, feeds)
+```ts
+import { mkBlocksToHtml, mkBlocksToText } from '@mk-kit/ui';
+const html = mkBlocksToHtml(doc);   // clean, self-contained semantic HTML
+const text = mkBlocksToText(doc);   // plain text for excerpts / meta descriptions
+```
+Serializer signatures:
+```ts
+function mkBlocksToHtml(doc: MkBlockDocument | null | undefined): string;
+function mkBlocksToText(doc: MkBlockDocument | null | undefined): string;
+```
+`mkBlocksToHtml` emits layout blocks as responsive grid wrappers with inline
+styles, so the output is portable to any page. It is dependency-free and safe to
+run on a server. Because it returns a string, always let a sanitiser (or the
+`mk-block-renderer`) handle final display — never feed it back into `innerHTML`
+without sanitising again.
+```