Skip to content

Commit 89b5180

Browse files
eksrhaeksrha
committed
feat: add theme switch module + docs
1 parent 8f410c3 commit 89b5180

25 files changed

+754
-80
lines changed

‎README.md‎

Lines changed: 4 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -37,28 +37,8 @@ add to your local `.npmrc` the following line to be able to use this package:
3737

3838
Live Demo with all current modules at https://fullstack-devops.github.io/ngx-mat-components
3939

40-
Api Documentation: https://fullstack-devops.github.io/libraries/ngx-mat-components.
40+
- [Navigation and Toolbar Frame](https://github.com/fullstack-devops/ngx-mat-components/blob/main/docs/fs-nav-frame.md)
41+
- [Theme Switcher](https://github.com/fullstack-devops/ngx-mat-components/blob/main/docs/fs-theme-switcher.md)
42+
- [Calendar](https://github.com/fullstack-devops/ngx-mat-components/blob/main/docs/fs-calendar.md)
4143

42-
## Development server
43-
44-
Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files.
45-
46-
## Code scaffolding
47-
48-
Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.
49-
50-
## Build
51-
52-
Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory.
53-
54-
## Running unit tests
55-
56-
Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).
57-
58-
## Running end-to-end tests
59-
60-
Run `ng e2e` to execute the end-to-end tests via a platform of your choice. To use this command, you need to first add a package that implements end-to-end testing capabilities.
61-
62-
## Further help
63-
64-
To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.
44+
> Note: Sometimes I cannot document everything in the `docs/`, so please check the `workspace application` and source code for more information. Or sumbit an [Issue](https://github.com/fullstack-devops/ngx-mat-components/issues)

‎docs/calendar.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# FsCalendarModule Documentation
2+
3+
The `FsCalendarModule` provides advanced, flexible calendar components for Angular Material applications. It includes both calendar panels and table views, supporting custom data, range selection, and Material 3 theming.
4+
5+
---
6+
7+
## Features
8+
9+
- **Calendar Panels** for monthly or annual views
10+
- **Calendar Table** for tabular, multi-entry calendar data
11+
- **Range and single date selection** support
12+
- **Custom day rendering** (colors, tooltips, badges, etc.)
13+
- **Material 3 theming** and accessibility
14+
- **Highly configurable** via inputs
15+
16+
---
17+
18+
## Module Import
19+
20+
```ts
21+
import { FsCalendarModule } from '@fullstack-devops/ngx-mat-components';
22+
```
23+
24+
---
25+
26+
## Main Components & Directives
27+
28+
- [`FsCalendarPanelsComponent`](../projects/ngx-mat-components/src/fs-calendar/calendar-panels/calendar-panels.component.ts)
29+
- [`FsCalendarTableComponent`](../projects/ngx-mat-components/src/fs-calendar/calendar-table/fs-calendar-table.component.ts)
30+
- [`FsCalendarTableNameDirective`](../projects/ngx-mat-components/src/fs-calendar/directives/fs-calendar-table-name.directive.ts)
31+
32+
---
33+
34+
## Usage Examples
35+
36+
### Calendar Panels
37+
38+
```html
39+
<fs-calendar-panels
40+
[dataSource]="calendarPanelsData"
41+
[year]="year"
42+
[month]="month"
43+
[monthsBefore]="monthsBefore"
44+
[monthsAfter]="monthsAfter"
45+
[placeholderDay]="placeholder"
46+
(selection)="onSelection($event)">
47+
</fs-calendar-panels>
48+
```
49+
50+
### Calendar Table
51+
52+
```html
53+
<fs-calendar-table [(month)]="month" [(year)]="year" [dataSource]="calendarTableData">
54+
<fs-calendar-table-name>Persons</fs-calendar-table-name>
55+
</fs-calendar-table>
56+
```
57+
58+
---
59+
60+
## Configuration
61+
62+
### Calendar Panels Data
63+
64+
[`CalendarPanels`](../projects/ngx-mat-components/src/fs-calendar/calendar.models.ts):
65+
66+
```ts
67+
export interface CalendarPanels<T = void> {
68+
config: CalendarPanelsConfig;
69+
data: CalendarExtendedDay<T>[];
70+
}
71+
```
72+
73+
#### Example Config
74+
75+
[`CalendarPanelsConfig`](../projects/ngx-mat-components/src/fs-calendar/calendar.models.ts):
76+
77+
```ts
78+
export interface CalendarPanelsConfig {
79+
renderMode: 'monthly' | 'annual';
80+
selectMode: 'click' | 'range';
81+
calendarWeek: boolean;
82+
displayYear?: boolean;
83+
switches?: boolean;
84+
bluredDays?: boolean;
85+
markWeekend?: boolean;
86+
firstDayOfWeekMonday?: boolean;
87+
panelWidth?: string;
88+
}
89+
```
90+
91+
#### Example Data
92+
93+
[`CalendarExtendedDay`](../projects/ngx-mat-components/src/fs-calendar/calendar.models.ts):
94+
95+
```ts
96+
export interface CalendarExtendedDay<T = void> {
97+
date: Date;
98+
char?: string;
99+
colors?: {
100+
backgroundColor: string;
101+
color?: string;
102+
};
103+
toolTip?: string;
104+
badge?: {
105+
badgeMode: 'int' | 'icon';
106+
badgeInt?: number;
107+
badgeIcon?: string;
108+
};
109+
_meta?: CalendarExtendedDayMeta;
110+
customData?: T;
111+
}
112+
```
113+
114+
### Calendar Table Data
115+
116+
[`CalendarTableEntry`](../projects/ngx-mat-components/src/fs-calendar/calendar.models.ts):
117+
118+
```ts
119+
export interface CalendarTableEntry {
120+
name: string;
121+
data: CalendarExtendedDay[];
122+
}
123+
```
124+
125+
---
126+
127+
## Selection Events
128+
129+
- The panels emit a `(selection)` event with a [`CalendarEvent`](../projects/ngx-mat-components/src/fs-calendar/calendar.models.ts):
130+
- Range selection: `{ type: 'range', start, end, affectedDays }`
131+
- Single date: `{ type: 'click', date }`
132+
133+
---
134+
135+
## Theming & Styling
136+
137+
- The module supports Material 3 theming.
138+
- SCSS mixin: `fs-calendar-theme` ([styles/fs-calendar/_theming.scss](../projects/ngx-mat-components/styles/fs-calendar/_theming.scss))
139+
- To use the theme in your styles:
140+
```scss
141+
@use '@fullstack-devops/ngx-mat-components' as fsc;
142+
@include fsc.core();
143+
```
144+
145+
---
146+
147+
## API Reference
148+
149+
- [`FsCalendarPanelsComponent`](../projects/ngx-mat-components/src/fs-calendar/calendar-panels/calendar-panels.component.ts)
150+
- [`FsCalendarTableComponent`](../projects/ngx-mat-components/src/fs-calendar/calendar-table/fs-calendar-table.component.ts)
151+
- [`FsCalendarTableNameDirective`](../projects/ngx-mat-components/src/fs-calendar/directives/fs-calendar-table-name.directive.ts)
152+
- [`CalendarPanels`](../projects/ngx-mat-components/src/fs-calendar/calendar.models.ts)
153+
- [`CalendarPanelsConfig`](../projects/ngx-mat-components/src/fs-calendar/calendar.models.ts)
154+
- [`CalendarExtendedDay`](../projects/ngx-mat-components/src/fs-calendar/calendar.models.ts)
155+
- [`CalendarTableEntry`](../projects/ngx-mat-components/src/fs-calendar/calendar.models.ts)
156+
- [`CalendarEvent`](../projects/ngx-mat-components/src/fs-calendar/calendar.models.ts)
157+
- [`FsCalendarService`](../projects/ngx-mat-components/src/fs-calendar/services/fs-calendar.service.ts)
158+
159+
---
160+
161+
## Example Screenshots
162+
163+
![Calendar Panels Example](../projects/lib-workspace/src/assets/calendar-panels-shot.png)
164+
![Calendar Table Example](../projects/lib-workspace/src/assets/calendar-table-shot.png)
165+
166+
---
167+
168+
## See Also
169+
170+
- [Live Demo](https://fullstack-devops.github.io/ngx-mat-components)
171+
- Workspace Examples:
172+
- [showcase-calendar-panels](https://github.com/fullstack-devops/ngx-mat-components/tree/main/projects/lib-workspace/src/app/content/showcase-calendar-panels)
173+
- [showcase-calendar-table](https://github.com/fullstack-devops/ngx-mat-components/tree/main/projects/lib-workspace/src/app/content/showcase-calendar-table)

‎docs/fs-nav-frame.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# FsNavFrameModule Documentation
2+
3+
The `FsNavFrameModule` provides a flexible, modern navigation frame for Angular Material applications. It includes a responsive sidebar, toolbar, and user profile area, supporting content projection and theming.
4+
5+
---
6+
7+
## Features
8+
9+
- **Responsive sidebar navigation** with customizable items and icons
10+
- **Toolbar** with start, center, and end content slots
11+
- **User profile section** with name, subname, actions, and profile picture
12+
- **Configurable sizing** for toolbar and sidebar
13+
- **Content projection** for full layout flexibility
14+
- **Material 3 theming** support
15+
16+
---
17+
18+
## Module Import
19+
20+
```ts
21+
import { FsNavFrameModule } from '@fullstack-devops/ngx-mat-components';
22+
```
23+
24+
---
25+
26+
## Main Components & Directives
27+
28+
- [`FsNavFrameComponent`](../projects/ngx-mat-components/src/fs-nav-frame/fs-nav-frame.component.ts)
29+
- [`FsNavFrameToolbarComponent`](../projects/ngx-mat-components/src/fs-nav-frame/nav-frame-toolbar/fs-nav-frame-toolbar.component.ts)
30+
- [`FsNavFrameSidebar`](../projects/ngx-mat-components/src/fs-nav-frame/components/fs-nav-frame-sidebar.ts)
31+
- [`FsNavFrameSidebarItemComponent`](../projects/ngx-mat-components/src/fs-nav-frame/components/fs-nav-frame-sidebar-item/fs-nav-frame-sidebar-item.component.ts)
32+
- [`FsNavUserProfileComponent`](../projects/ngx-mat-components/src/fs-nav-frame/fs-nav-user-profile/fs-nav-user-profile.component.ts)
33+
- [`FsNavFrameContentDirective`](../projects/ngx-mat-components/src/fs-nav-frame/directives/fs-nav-frame-content.directive.ts)
34+
- Toolbar slot directives:
35+
- [`FsNavFrameToolbarStartDirective`](../projects/ngx-mat-components/src/fs-nav-frame/nav-frame-toolbar/directives/fs-nav-frame-toolbar-start.directive.ts)
36+
- [`FsNavFrameToolbarCenterDirective`](../projects/ngx-mat-components/src/fs-nav-frame/nav-frame-toolbar/directives/fs-nav-frame-toolbar-center.directive.ts)
37+
- [`FsNavFrameToolbarEndDirective`](../projects/ngx-mat-components/src/fs-nav-frame/nav-frame-toolbar/directives/fs-nav-frame-toolbar-end.directive.ts)
38+
- User profile slot directives:
39+
- [`FsNavUserProfileNameDirective`](../projects/ngx-mat-components/src/fs-nav-frame/fs-nav-user-profile/directives/fs-nav-user-profile-name.directive.ts)
40+
- [`FsNavUserProfileSubNameDirective`](../projects/ngx-mat-components/src/fs-nav-frame/fs-nav-user-profile/directives/fs-nav-user-profile-subname.directive.ts)
41+
- [`FsNavUserProfileActionsDirective`](../projects/ngx-mat-components/src/fs-nav-frame/fs-nav-user-profile/directives/fs-nav-user-profile-actions.directive.ts)
42+
43+
---
44+
45+
## Usage Example
46+
47+
```html
48+
<fs-nav-frame [navFrameConfig]="navFrameConfig" [sizing]="sizing">
49+
<fs-nav-frame-toolbar>
50+
<fs-nav-frame-toolbar-start>App Title</fs-nav-frame-toolbar-start>
51+
<fs-nav-frame-toolbar-center>
52+
<!-- Centered toolbar content -->
53+
</fs-nav-frame-toolbar-center>
54+
<fs-nav-frame-toolbar-end>
55+
<!-- Toolbar actions, e.g. search, theme switcher -->
56+
</fs-nav-frame-toolbar-end>
57+
</fs-nav-frame-toolbar>
58+
59+
<fs-nav-frame-sidebar>
60+
<fs-nav-frame-sidebar-item routerLink="/home">
61+
<i-lucide [img]="HomeIcon"></i-lucide>
62+
<span>Home</span>
63+
</fs-nav-frame-sidebar-item>
64+
<!-- More sidebar items -->
65+
</fs-nav-frame-sidebar>
66+
67+
<fs-nav-user-profile [profilePicture]="profilePicUrl">
68+
<fs-nav-user-profile-name>Jane Doe</fs-nav-user-profile-name>
69+
<fs-nav-user-profile-subname>Engineer</fs-nav-user-profile-subname>
70+
<fs-nav-user-profile-actions>
71+
<button mat-icon-button>...</button>
72+
</fs-nav-user-profile-actions>
73+
</fs-nav-user-profile>
74+
75+
<fs-nav-frame-content>
76+
<router-outlet></router-outlet>
77+
</fs-nav-frame-content>
78+
</fs-nav-frame>
79+
```
80+
81+
---
82+
83+
## Configuration
84+
85+
### `navFrameConfig` ([`NavFrameConfig`](../projects/ngx-mat-components/src/fs-nav-frame/fs-nav-frame.modules.ts))
86+
87+
```ts
88+
export interface NavFrameConfig {
89+
appName?: string; // Displayed app name (opened mode)
90+
appVersion?: string; // Optional app version
91+
logoSrc?: string; // Optional logo URL
92+
sizing?: NavFrameSizing; // Optional sizing config
93+
}
94+
```
95+
96+
### `sizing` ([`NavFrameSizing`](../projects/ngx-mat-components/src/fs-nav-frame/fs-nav-frame.modules.ts))
97+
98+
```ts
99+
export interface NavFrameSizing {
100+
toolbarHeight?: number; // Toolbar height in rem (default: 3)
101+
sidebarWidthClosed?: number; // Sidebar width (closed) in rem (default: 4)
102+
sidebarWidthOpened?: number; // Sidebar width (opened) in rem (default: 18)
103+
}
104+
```
105+
106+
---
107+
108+
## Sidebar Navigation
109+
110+
- Use `<fs-nav-frame-sidebar>` to define the sidebar.
111+
- Add `<fs-nav-frame-sidebar-item>` for each navigation entry.
112+
- Use `[routerLink]` for Angular routing.
113+
- You can project icons and labels.
114+
115+
---
116+
117+
## Toolbar
118+
119+
- Use `<fs-nav-frame-toolbar>` to define the toolbar.
120+
- Slot content using `<fs-nav-frame-toolbar-start>`, `<fs-nav-frame-toolbar-center>`, and `<fs-nav-frame-toolbar-end>` for flexible layouts.
121+
122+
---
123+
124+
## User Profile
125+
126+
- Use `<fs-nav-user-profile>` for the user section.
127+
- Project name, subname, and actions using:
128+
- `<fs-nav-user-profile-name>`
129+
- `<fs-nav-user-profile-subname>`
130+
- `<fs-nav-user-profile-actions>`
131+
132+
---
133+
134+
## Theming & Styling
135+
136+
- The module supports Material 3 theming.
137+
- SCSS mixin: `fs-nav-frame-theme` ([styles/fs-nav-frame/_theming.scss](../projects/ngx-mat-components/styles/fs-nav-frame/_theming.scss))
138+
- To use the theme in your styles:
139+
```scss
140+
@use '@fullstack-devops/ngx-mat-components' as fsc;
141+
142+
@include mat.app-background();
143+
144+
@include fsc.core();
145+
```
146+
147+
---
148+
149+
## API Reference
150+
151+
- [`FsNavFrameComponent`](../projects/ngx-mat-components/src/fs-nav-frame/fs-nav-frame.component.ts)
152+
- [`FsNavFrameModule`](../projects/ngx-mat-components/src/fs-nav-frame/fs-nav-frame.module.ts)
153+
- [`NavFrameConfig`](../projects/ngx-mat-components/src/fs-nav-frame/fs-nav-frame.modules.ts)
154+
- [`NavFrameSizing`](../projects/ngx-mat-components/src/fs-nav-frame/fs-nav-frame.modules.ts)
155+
156+
---
157+
158+
## Example Screenshot
159+
160+
![Nav Frame Example](../projects/lib-workspace/src/assets/nav-frame-shot.png)
161+
162+
---
163+
164+
## See Also
165+
166+
- [Live Demo](https://fullstack-devops.github.io/ngx-mat-components)
167+
- Workspace Example:
168+
- [app.html](https://github.com/fullstack-devops/ngx-mat-components/blob/main/projects/lib-workspace/src/app/app.html)
169+
- [app.ts](https://github.com/fullstack-devops/ngx-mat-components/blob/main/projects/lib-workspace/src/app/app.ts)

0 commit comments

Comments
 (0)