@jpahd/kalendus 0.1.7 → 0.7.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 (42) hide show
  1. package/README.11tydata.json +8 -0
  2. package/README.md +70 -44
  3. package/custom-elements.json +282 -8
  4. package/dist/components/Day.d.ts.map +1 -1
  5. package/dist/components/Entry.d.ts.map +1 -1
  6. package/dist/components/Header.d.ts.map +1 -1
  7. package/dist/components/Menu.d.ts.map +1 -1
  8. package/dist/generated/locale-codes.d.ts +2 -2
  9. package/dist/generated/locale-codes.d.ts.map +1 -1
  10. package/dist/generated/locales/cs.d.ts +33 -0
  11. package/dist/generated/locales/cs.d.ts.map +1 -0
  12. package/dist/generated/locales/da.d.ts +33 -0
  13. package/dist/generated/locales/da.d.ts.map +1 -0
  14. package/dist/generated/locales/el.d.ts +33 -0
  15. package/dist/generated/locales/el.d.ts.map +1 -0
  16. package/dist/generated/locales/fi.d.ts +33 -0
  17. package/dist/generated/locales/fi.d.ts.map +1 -0
  18. package/dist/generated/locales/he.d.ts +33 -0
  19. package/dist/generated/locales/he.d.ts.map +1 -0
  20. package/dist/generated/locales/nb.d.ts +33 -0
  21. package/dist/generated/locales/nb.d.ts.map +1 -0
  22. package/dist/generated/locales/sv.d.ts +33 -0
  23. package/dist/generated/locales/sv.d.ts.map +1 -0
  24. package/dist/kalendus.js +254 -206
  25. package/dist/kalendus.js.map +1 -1
  26. package/dist/lib/SlotManager.d.ts.map +1 -1
  27. package/dist/lib/colorParser.d.ts +18 -0
  28. package/dist/lib/colorParser.d.ts.map +1 -0
  29. package/dist/lib/getColorTextWithContrast.d.ts +1 -1
  30. package/dist/lib/getColorTextWithContrast.d.ts.map +1 -1
  31. package/dist/lib/localization.d.ts.map +1 -1
  32. package/dist/lib/messages.d.ts.map +1 -1
  33. package/dist/lib/weekDisplayContext.d.ts.map +1 -1
  34. package/dist/lib/weekStartHelper.d.ts.map +1 -1
  35. package/dist/lms-calendar.d.ts +104 -0
  36. package/dist/lms-calendar.d.ts.map +1 -1
  37. package/dist/themes/brutalist.css +100 -0
  38. package/dist/themes/default.css +100 -0
  39. package/dist/themes/ink.css +98 -0
  40. package/dist/themes/midnight.css +110 -0
  41. package/dist/themes/soft.css +97 -0
  42. package/package.json +131 -123
package/README.11tydata.json ADDED
@@ -0,0 +1,8 @@
1
+ {
2
+ "layout": "base.njk",
3
+ "title": "Kalendus",
4
+ "order": 0,
5
+ "tags": "docs",
6
+ "section": "Getting Started",
7
+ "permalink": "/"
8
+ }
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # kalendus
2
2
 
3
- A sophisticated, responsive calendar web component built with Lit 3.x and TypeScript. Multiple view modes, overlapping event handling, per-instance localization, and 80+ CSS design tokens.
3
+ A sophisticated, responsive calendar web component built with Lit 3.x and TypeScript. Multiple view modes, overlapping event handling, per-instance localization, and 151 CSS design tokens.
4
4
 
5
5
  ![demo](assets/demo.gif)
6
6
 
@@ -51,12 +51,12 @@ Each instance auto-detects its locale from `<html lang="...">`. Override per-ins
51
51
  - **Responsive Design**: Mobile-first approach with adaptive layouts and container queries
52
52
  - **Color Dot Indicators**: Scalable month view with color-coded event dots
53
53
  - **Accessibility**: Full keyboard navigation, ARIA labels, focus trapping, and screen reader support
54
- - **CSS Custom Properties**: 80+ design tokens for comprehensive theming
54
+ - **CSS Custom Properties**: 151 design tokens for comprehensive theming
55
55
 
56
56
  ### Per-Instance Localization
57
57
 
58
58
  - **Independent Locale Per Instance**: Multiple calendars on the same page can each display a different locale
59
- - **21 Built-in Locales**: English, German, Spanish, French, Hindi, Bengali, Russian, Indonesian, Korean, Turkish, Vietnamese, Italian, Thai, Polish, Ukrainian, Dutch, Japanese, Portuguese, Arabic, Chinese (Simplified), and German (DE)
59
+ - **28 Built-in Locales**: See [Supported Locales](#supported-locales) below for the full list
60
60
  - **Localized UI Strings**: All buttons, labels, and messages translated per instance
61
61
  - **Localized Date Formatting**: Weekday names, month names, and date formats use the instance's locale
62
62
  - **Configurable Week Start**: `firstDayOfWeek` property supports Monday (ISO), Sunday (US/JP), Saturday (AR), or any day
@@ -68,7 +68,7 @@ Each instance auto-detects its locale from `<html lang="...">`. Override per-ins
68
68
  | `heading` | `string` | `undefined` | Calendar title displayed in header |
69
69
  | `activeDate` | `CalendarDate` | Current date | Initially displayed date |
70
70
  | `entries` | `CalendarEntry[]` | `[]` | Array of calendar events |
71
- | `color` | `string` | `'#000000'` | Primary theme color |
71
+ | `color` | `string` | `'#000000'` | Primary theme color (any CSS color format) |
72
72
  | `locale` | `string` | `document.documentElement.lang \|\| 'en'` | Locale for UI strings and date formatting (auto-detected from page, overridable per-instance) |
73
73
  | `firstDayOfWeek` | `0-6` | `1` | First day of the week (0=Sun, 1=Mon, ..., 6=Sat) |
74
74
  | `yearDrillTarget` | `'day' \| 'month'` | `'month'` | Determines whether a year-view click opens day or month view |
@@ -80,7 +80,7 @@ Each instance auto-detects its locale from `<html lang="...">`. Override per-ins
80
80
  interface CalendarEntry {
81
81
  heading: string;
82
82
  content: string;
83
- color: string;
83
+ color: string; // any CSS color: hex, named, rgb(), hsl(), oklch(), …
84
84
  isContinuation: boolean;
85
85
  date: {
86
86
  start: { day: number; month: number; year: number };
@@ -108,57 +108,81 @@ interface CalendarEntry {
108
108
 
109
109
  ### Supported Locales
110
110
 
111
- | Code | Language | Default Week Start |
112
- | --------- | -------------------- | ------------------ |
113
- | `en` | English | Sunday |
114
- | `de` | German | Monday |
115
- | `de-DE` | German (Germany) | Monday |
116
- | `es` | Spanish | Monday |
117
- | `fr` | French | Monday |
118
- | `hi` | Hindi | Sunday |
119
- | `bn` | Bengali | Sunday |
120
- | `ru` | Russian | Monday |
121
- | `id` | Indonesian | Sunday |
122
- | `ko` | Korean | Sunday |
123
- | `tr` | Turkish | Monday |
124
- | `vi` | Vietnamese | Monday |
125
- | `it` | Italian | Monday |
126
- | `th` | Thai | Sunday |
127
- | `pl` | Polish | Monday |
128
- | `uk` | Ukrainian | Monday |
129
- | `nl` | Dutch | Monday |
130
- | `ja` | Japanese | Sunday |
131
- | `pt` | Portuguese | Sunday |
132
- | `ar` | Arabic | Saturday |
133
- | `zh-Hans` | Chinese (Simplified) | Sunday |
111
+ <!-- GENERATED:LOCALE_TABLE:START -->
112
+
113
+ | Code | Language | Default Week Start |
114
+ | --------- | ------------------ | ------------------ |
115
+ | `en` | English | Sunday |
116
+ | `ar` | Arabic | Saturday |
117
+ | `bn` | Bangla | Sunday |
118
+ | `cs` | Czech | Monday |
119
+ | `da` | Danish | Monday |
120
+ | `de` | German | Monday |
121
+ | `de-DE` | German (Germany) | Monday |
122
+ | `el` | Greek | Monday |
123
+ | `es` | Spanish | Monday |
124
+ | `fi` | Finnish | Monday |
125
+ | `fr` | French | Monday |
126
+ | `he` | Hebrew | Sunday |
127
+ | `hi` | Hindi | Sunday |
128
+ | `id` | Indonesian | Sunday |
129
+ | `it` | Italian | Monday |
130
+ | `ja` | Japanese | Sunday |
131
+ | `ko` | Korean | Sunday |
132
+ | `nb` | Norwegian Bokmål | Monday |
133
+ | `nl` | Dutch | Monday |
134
+ | `pl` | Polish | Monday |
135
+ | `pt` | Portuguese | Sunday |
136
+ | `ru` | Russian | Monday |
137
+ | `sv` | Swedish | Monday |
138
+ | `th` | Thai | Sunday |
139
+ | `tr` | Turkish | Monday |
140
+ | `uk` | Ukrainian | Monday |
141
+ | `vi` | Vietnamese | Monday |
142
+ | `zh-Hans` | Simplified Chinese | Sunday |
143
+
144
+ <!-- GENERATED:LOCALE_TABLE:END -->
134
145
 
135
146
  ## Styling & Theming
136
147
 
137
- Override CSS custom properties to match your design system:
148
+ Kalendus ships **unstyled by default** (neutral base, respects OS light/dark mode). Import a built-in theme for an opinionated look:
149
+
150
+ ```js
151
+ import '@jpahd/kalendus/themes/default.css'; // polished light theme
152
+ import '@jpahd/kalendus/themes/ink.css'; // monochrome editorial
153
+ import '@jpahd/kalendus/themes/soft.css'; // pastel, generous radii
154
+ import '@jpahd/kalendus/themes/brutalist.css'; // bold borders, stark contrast
155
+ import '@jpahd/kalendus/themes/midnight.css'; // dark mode
156
+ ```
157
+
158
+ Override individual CSS custom properties to fine-tune any theme:
138
159
 
139
160
  ```css
140
161
  lms-calendar {
141
162
  --primary-color: #1976d2;
142
163
  --background-color: #ffffff;
143
164
  --entry-border-radius: 6px;
144
- --header-height: 4em;
145
165
  }
146
166
  ```
147
167
 
148
- See [docs/theming.md](docs/theming.md) for the full token reference (primary colors, entry styling, layout & spacing, week column controls, year view tokens).
168
+ See [Theming Reference](docs/theming.md) for all 5 built-in themes, color format support, and quick-start examples. For the complete token list, see the [CSS Token Reference](docs/css-tokens.md).
149
169
 
150
170
  ## Documentation Map
151
171
 
152
- | Audience | Document | Highlights |
153
- | ---------------------- | ------------------------------------------------------------ | ----------------------------------------------------- |
154
- | Integrators | [Integration Guide](docs/integration-guide.md) | Framework recipes, theming tokens, analytics hooks |
155
- | Application Developers | [Library Usage](docs/library-usage.md) | API surface, data contracts, DOM events |
156
- | Component Contributors | [Developer Guide](docs/developer-guide.md) | Internal architecture, debugging tips, adding locales |
157
- | Rendering Internals | [Rendering Calculations](docs/rendering-calculations.md) | Grid math, condensed weeks, density modes |
158
- | Design Systems | [Theming Reference](docs/theming.md) | Full CSS custom property reference (80+ tokens) |
159
- | Architecture | [Architecture Overview](docs/architecture.md) | Component tree, technologies, design patterns |
160
- | Design Tokens | [Design Token Refactoring](docs/design-token-refactoring.md) | Token audit and proposed hierarchy |
161
- | Backend/API | [API Server Guide](docs/api-server.md) | REST + SSE backend, database + adapters |
172
+ | Audience | Document | Highlights |
173
+ | ---------------------- | ------------------------------------------------------------ | -------------------------------------------------------- |
174
+ | Integrators | [Integration Guide](docs/integration-guide.md) | Framework recipes, theming tokens, analytics hooks |
175
+ | Application Developers | [Library Usage](docs/library-usage.md) | API surface, data contracts, DOM events |
176
+ | CSS / Design Systems | [CSS Token Reference](docs/css-tokens.md) | Complete reference of all 151 CSS custom properties |
177
+ | CSS / Design Systems | [Theming Reference](docs/theming.md) | Built-in themes, color formats, quick-start examples |
178
+ | Events | [Events Reference](docs/events.md) | All 8 custom events with payloads and code examples |
179
+ | Layout | [Layout & Positioning](docs/layout-and-positioning.md) | Height requirements, responsive behavior, all-day events |
180
+ | Troubleshooting | [Troubleshooting](docs/troubleshooting.md) | Top consumer issues and fixes |
181
+ | Component Contributors | [Developer Guide](docs/developer-guide.md) | Internal architecture, debugging tips, adding locales |
182
+ | Rendering Internals | [Rendering Calculations](docs/rendering-calculations.md) | Grid math, condensed weeks, density modes |
183
+ | Architecture | [Architecture Overview](docs/architecture.md) | Component tree, technologies, design patterns |
184
+ | Design Tokens | [Design Token Refactoring](docs/design-token-refactoring.md) | Historical: token audit and proposed hierarchy |
185
+ | Backend/API | [API Server Guide](docs/api-server.md) | REST + SSE backend, database + adapters |
162
186
 
163
187
  ## Testing
164
188
 
@@ -193,19 +217,21 @@ pnpm storybook
193
217
  ### Available Stories
194
218
 
195
219
  - **Default**: Basic calendar with sample events
220
+ - **Theme stories**: Default, Ink, Soft, Brutalist, Midnight — one story per built-in theme
221
+ - **Custom Theming**: Inline CSS variable overrides
196
222
  - **Locale stories**: Individual stories for each supported locale (German, French, Spanish, Japanese, etc.)
197
- - **LocaleShowcase**: 19 calendars on one page, each with a different locale
223
+ - **LocaleShowcase**: 26 calendars on one page, each with a different locale
198
224
  - **WeekStartComparison**: Side-by-side Monday-first vs Sunday-first
199
225
  - **Heavy Event Load**: Stress testing with 200+ events
200
226
  - **Overlapping Events**: Extreme overlap scenarios
227
+ - **Tall Container**: Verifies layout in oversized containers
201
228
  - **Mobile View**: Responsive mobile experience
202
- - **Custom Theming**: Theme variations and customization
203
229
 
204
230
  ## Development
205
231
 
206
232
  ```bash
207
233
  pnpm install
208
- pnpm storybook # Start Storybook dev server
234
+ pnpm storybook # Start Storybook dev server
209
235
  pnpm build # Build with Vite
210
236
  pnpm test # Run tests
211
237
  pnpm lint # Run lit-analyzer + oxlint