@filip.mazev/blocks-core 0.0.2 → 0.0.4
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.
package/README.md
CHANGED
|
@@ -1,63 +1,140 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @filip.mazev/blocks-core
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## Blocks - Core Library
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**Blocks Core** is the foundational library for the Blocks ecosystem. It provides the essential infrastructure for building responsive, theme-aware Angular applications. It bridges the gap between TypeScript logic and SCSS styling, offering a unified system for breakpoints, device detection, scroll management and theming.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Styles & Theming
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
Blocks Core utilizes a robust SCSS architecture to manage design tokens and responsiveness.
|
|
10
|
+
|
|
11
|
+
### 1. Theme Provider
|
|
12
|
+
|
|
13
|
+
The library uses a CSS Variable system generated via SCSS maps. To initialize the core theme, use the `core-theme` mixin in your global styles.
|
|
14
|
+
|
|
15
|
+
```scss
|
|
16
|
+
@use '@filip.mazev/blocks-core/src/lib/styles/index' as blocks;
|
|
17
|
+
|
|
18
|
+
:root {
|
|
19
|
+
// Initialize default light theme
|
|
20
|
+
@include blocks.core-theme(blocks.$default-light-theme-config);
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
// Example: Switch to dark theme based on a class
|
|
24
|
+
body.dark-theme {
|
|
25
|
+
@include blocks.core-theme(blocks.$default-dark-theme-config);
|
|
26
|
+
}
|
|
11
27
|
```
|
|
12
28
|
|
|
13
|
-
|
|
29
|
+
This generates CSS variables with the `--fm-` prefix (e.g.,`--fm-primary`, `--fm-bg-surface`, `--fm-text-main`).
|
|
30
|
+
|
|
31
|
+
### 2. Responsive Mixins
|
|
32
|
+
|
|
33
|
+
The library provides mixins that strictly align with the WindowDimensionsService breakpoints in TypeScript.
|
|
34
|
+
|
|
35
|
+
Available Breakpoints:
|
|
36
|
+
|
|
37
|
+
* `xs`: 360px
|
|
38
|
+
* `sm`: 640px
|
|
39
|
+
* `md`: 768px
|
|
40
|
+
* `lg`: 1024px
|
|
41
|
+
* `xl`: 1280px
|
|
42
|
+
* `2xl`: 1536px
|
|
43
|
+
* `3xl`: 1920px
|
|
44
|
+
* `4xl`: 2560px
|
|
45
|
+
|
|
46
|
+
Usage:
|
|
47
|
+
|
|
48
|
+
```scss
|
|
49
|
+
@use '@filip.mazev/blocks-core/src/lib/styles/mixins' as *;
|
|
50
|
+
|
|
51
|
+
.my-element {
|
|
52
|
+
width: 100%;
|
|
14
53
|
|
|
15
|
-
|
|
16
|
-
|
|
54
|
+
// Applies when width >= 768px
|
|
55
|
+
@include respond-up(md) {
|
|
56
|
+
width: 50%;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
// Applies when width <= 640px
|
|
60
|
+
@include respond-down(sm) {
|
|
61
|
+
display: none;
|
|
62
|
+
}
|
|
17
63
|
```
|
|
18
64
|
|
|
19
|
-
##
|
|
65
|
+
## Core Services
|
|
66
|
+
|
|
67
|
+
### `WindowDimensionsService`
|
|
20
68
|
|
|
21
|
-
|
|
69
|
+
Bridges the gap between CSS media queries and TypeScript logic. It provides reactive access to window size and standard breakpoint thresholds.
|
|
22
70
|
|
|
23
|
-
```
|
|
24
|
-
|
|
71
|
+
```typescript
|
|
72
|
+
export class MyComponent {
|
|
73
|
+
constructor(private windowService: WindowDimensionsService) {
|
|
74
|
+
// Reactive stream
|
|
75
|
+
this.windowService.getWindowDimensions$().subscribe(dims => {
|
|
76
|
+
if (dims.width < dims.threshold_sm) {
|
|
77
|
+
console.log('Mobile View');
|
|
78
|
+
}
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
}
|
|
25
82
|
```
|
|
26
83
|
|
|
27
|
-
|
|
84
|
+
### `ThemingService`
|
|
28
85
|
|
|
29
|
-
|
|
86
|
+
Handles the detection of system preferences (Dark/Light mode) and manages the application-level theme state.
|
|
30
87
|
|
|
31
|
-
|
|
88
|
+
* `getSystemTheme$()`: Observes the OS/Browser prefers-color-scheme.
|
|
89
|
+
* `getApplicationTheme$()`: Observes the manually set application theme.
|
|
90
|
+
* `setApplicationTheme(theme: DeviceTheme)`: Manually overrides the current theme ('light' | 'dark').
|
|
32
91
|
|
|
33
|
-
|
|
34
|
-
```bash
|
|
35
|
-
cd dist/blocks-core
|
|
36
|
-
```
|
|
92
|
+
### `DeviceTypeService`
|
|
37
93
|
|
|
38
|
-
|
|
39
|
-
```bash
|
|
40
|
-
npm publish
|
|
41
|
-
```
|
|
94
|
+
Provides detailed information about the user's device, OS, and orientation. Useful for logic that depends on specific hardware capabilities (e.g., touch handling on Windows tablets vs Android).
|
|
42
95
|
|
|
43
|
-
|
|
96
|
+
`getDeviceState()` returns:
|
|
44
97
|
|
|
45
|
-
|
|
98
|
+
* isMobile / isTablet / isDesktop
|
|
99
|
+
* desktopOS (Windows, Mac, Linux, Unix)
|
|
100
|
+
* mobileOS (iOS, Android)
|
|
101
|
+
* isAppleDevice (checks both iOS and MacOS)
|
|
102
|
+
* isLandscapeOrientation / isPortraitOrientation
|
|
46
103
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
104
|
+
### `ScrollLockService`
|
|
105
|
+
|
|
106
|
+
A utility to prevent background scrolling when overlays (like Modals) are active. This service handles complex edge cases, including:
|
|
107
|
+
|
|
108
|
+
* **Scrollbar Compensation**: Adds padding to the body to prevent layout shifts when the scrollbar disappears.
|
|
109
|
+
|
|
110
|
+
* **Mobile Touch**: Prevents "scroll chaining" on mobile devices.
|
|
50
111
|
|
|
51
|
-
|
|
112
|
+
* **Extreme Overflow**: Optionally disables wheel and touch events entirely for strict locking.
|
|
52
113
|
|
|
53
|
-
|
|
114
|
+
```typescript
|
|
115
|
+
// Lock scroll
|
|
116
|
+
this.scrollLockService.disableScroll({
|
|
117
|
+
handleTouchInput: true,
|
|
118
|
+
handleExtremeOverflow: false
|
|
119
|
+
});
|
|
54
120
|
|
|
55
|
-
|
|
56
|
-
|
|
121
|
+
// Unlock
|
|
122
|
+
this.scrollLockService.enableScroll();
|
|
57
123
|
```
|
|
58
124
|
|
|
59
|
-
|
|
125
|
+
### `UiActionsService`
|
|
126
|
+
|
|
127
|
+
Common UI utility methods.
|
|
128
|
+
|
|
129
|
+
### `TextFormattingService`
|
|
130
|
+
|
|
131
|
+
Helper methods for string manipulation, such as:
|
|
132
|
+
|
|
133
|
+
* `generateNameCopy`: Generates unique names for duplicated items (e.g., "Item (Copy)", "Item (Copy 2)").
|
|
134
|
+
* `formattedDateString`: Converts Date objects or strings into a standardized locale date string.
|
|
135
|
+
|
|
136
|
+
## Installation
|
|
60
137
|
|
|
61
|
-
|
|
138
|
+
To use Blocks Core, install the package and ensure the SCSS partials are accessible to your build pipeline.
|
|
62
139
|
|
|
63
|
-
|
|
140
|
+
_(Installation instructions depend on your specific build/publish setup)._
|
package/package.json
CHANGED
|
@@ -29,7 +29,7 @@ $default-light-theme-config: (
|
|
|
29
29
|
'info': #3b82f6,
|
|
30
30
|
|
|
31
31
|
// Buttons
|
|
32
|
-
'button-primary': map-get($gray-palette,
|
|
32
|
+
'button-primary': map-get($gray-palette, 50),
|
|
33
33
|
'button-confirm': #40ca73,
|
|
34
34
|
'button-warn': map-get($warning-palette, 500),
|
|
35
35
|
'button-grayscale': map-get($gray-palette, 200),
|