kalendly 0.3.3 → 0.3.4

package/README.md

@@ -497,28 +497,73 @@ Clicking a day opens a popup with a grid of slots. Each shows only "Booked" or "
 
 The grid renders `1440 / slot-duration` slots, and `cal-availability-select` emits times on that granularity — half-hour slots produce half-hour selections.
 
-Precision below `slot-duration` is not representable: a booking from 17:30 on a 60-minute grid marks 17:00–18:00 booked, because that hour cannot be sold. A vendor working in half-hours sets `slot-duration="30"` rather than expecting the grid to subdivide itself.
+Precision below `slot-duration` is not representable: a booking from 17:30 on a 60-minute grid marks 17:00–18:00 booked, because that hour cannot be sold. A schedule kept in half-hours sets `slot-duration="30"` rather than expecting the grid to subdivide itself.
 
 ### Colouring the navigation arrows
 
 The `‹` and `›` arrows take their hover fill from `--calendar-primary-color` by
 default, so changing `primary` moves them along with the selected-day fill and
-today outline. To colour them on their own:
+today outline. Five tokens colour them on their own:
+
+| Token                           | Theme key         | Default                    |
+| ------------------------------- | ----------------- | -------------------------- |
+| `--calendar-nav-arrow-fg`       | `navArrowFg`      | `--calendar-text-color`    |
+| `--calendar-nav-arrow-bg`       | `navArrowBg`      | `--calendar-background`    |
+| `--calendar-nav-arrow-border`   | `navArrowBorder`  | `--calendar-border-color`  |
+| `--calendar-nav-arrow-hover-fg` | `navArrowHoverFg` | `--calendar-on-accent`     |
+| `--calendar-nav-arrow-hover-bg` | `navArrowHoverBg` | `--calendar-primary-color` |
+
+Each defaults to the value it replaces, so setting none of them changes nothing.
+
+**Set them straight on the element.** This is the only way that scopes to one
+calendar:
+
+```html
+<kal-calendar
+  style="
+    --calendar-nav-arrow-fg: #0f766e;
+    --calendar-nav-arrow-border: #0f766e;
+    --calendar-nav-arrow-hover-bg: #0f766e;
+    --calendar-nav-arrow-hover-fg: #fff;
+  "
+></kal-calendar>
+```
+
+Or from a stylesheet, which is usually tidier. There is no shadow DOM, so your
+CSS reaches the component:
+
+```css
+#booking-calendar {
+  --calendar-nav-arrow-fg: #0f766e;
+  --calendar-nav-arrow-border: #0f766e;
+  --calendar-nav-arrow-hover-bg: #0f766e;
+  --calendar-nav-arrow-hover-fg: #fff;
+}
+```
+
+The same works in every framework, since it is just an attribute or a class:
+
+```jsx
+<kal-calendar style={{ '--calendar-nav-arrow-hover-bg': '#0f766e' }} />
+```
+
+**Or use the `theme` property** — but note it is page-wide:
 
 ```js
-cal.theme = {
-  navArrowFg: '#0f766e',
-  navArrowBorder: '#0f766e',
-  navArrowHoverBg: '#0f766e',
-  navArrowHoverFg: '#ffffff',
-};
+cal.theme = { navArrowFg: '#0f766e', navArrowHoverBg: '#0f766e' };
 ```
 
-Each defaults to the value it replaces, so setting none of them changes nothing.
+> `theme` writes its values to `:root`, so it colours **every** `<kal-calendar>`
+> on the page, not the element you set it on. With one calendar that is
+> harmless. With two, the last assignment wins for both — use the CSS custom
+> properties above to theme them separately.
+
+Every other token works the same way: anything in the theming table can be set
+per element as a CSS variable, or page-wide through `theme`.
 
 ### Booking constraints
 
-Four optional attributes describe when a vendor is open. Omit them all and nothing is constrained.
+Four optional attributes describe when bookings are accepted. Omit them all and nothing is constrained.
 
 ```html
 <kal-calendar
@@ -544,7 +589,7 @@ None substitutes for another. A horizon cannot say "weekdays only", a weekday li
 
 `available-hours` takes a comma-separated list because a working day is not always contiguous: `"09:00-12:00,13:00-17:00"` closes for lunch, and `"09:00-17:00,17:30-22:00"` runs meetings then an evening class. Each range is half-open, `[start, end)` — `"09:00-17:00"` on an hourly grid makes 16:00–17:00 the last bookable slot, the same convention events use.
 
-Excluded **days** are not click targets at all: no hover response, and neither `cal-date-select` nor `cal-availability-select` fires. Excluded **hours** render greyed and marked `Closed`, and emit no `cal-slot-select`. They are shown rather than hidden so a booking that falls outside the window is still visible to the vendor.
+Excluded **days** are not click targets at all: no hover response, and neither `cal-date-select` nor `cal-availability-select` fires. Excluded **hours** render greyed and marked `Closed`, and emit no `cal-slot-select`. They are shown rather than hidden so a booking that falls outside the window is still visible.
 
 Style either with `--calendar-out-of-range-bg` and `--calendar-out-of-range-fg`, or the `outOfRangeBg` / `outOfRangeFg` theme keys.
 
@@ -842,10 +887,90 @@ Type, radius, elevation and spacing scales are exposed the same way —
 `--calendar-font-*`, `--calendar-radius-*`, `--calendar-shadow-*` and
 `--calendar-space-*`. See `dist/styles/calendar.css` for the full set.
 
+### Where you set a token decides what it colours
+
+The same token means different things depending on where you declare it.
+
+| Set on                       | Colours                                   |
+| ---------------------------- | ----------------------------------------- |
+| `:root` or a stylesheet      | every `<kal-calendar>` on the page        |
+| the `<kal-calendar>` element | that calendar only                        |
+| the `theme` property         | **every** calendar — it writes to `:root` |
+
+To theme one calendar, set the custom properties on the element. There is no
+shadow DOM, so they inherit straight through:
+
+```html
+<kal-calendar
+  style="
+    --calendar-primary-color: #4f46e5;
+    --calendar-primary-color-rgb: 79, 70, 229;
+    --calendar-on-accent: #fff;
+  "
+></kal-calendar>
+```
+
+Or from your own stylesheet, which is usually tidier:
+
+```css
+#booking-calendar {
+  --calendar-primary-color: #4f46e5;
+  --calendar-primary-color-rgb: 79, 70, 229;
+  --calendar-on-accent: #fff;
+}
+```
+
+It is only an attribute, so every framework does it its own way:
+
+```jsx
+/* React — cast because CSS custom properties are not in CSSProperties */
+<kal-calendar
+  style={{
+    '--calendar-primary-color': 'var(--primary)',
+    '--calendar-primary-color-rgb': 'var(--primary-rgb)',
+    '--calendar-on-accent': 'var(--primary-foreground)',
+  } as React.CSSProperties}
+/>
+```
+
+```vue
+<kal-calendar :style="{ '--calendar-primary-color': brand }" />
+```
+
+```svelte
+<kal-calendar style="--calendar-primary-color: {brand}" />
+```
+
+```html
+<!-- Angular -->
+<kal-calendar [style.--calendar-primary-color]="brand"></kal-calendar>
+```
+
+Pointing a token at one of your own design-system variables works, since it
+resolves in the element's scope:
+
+```html
+<kal-calendar style="--calendar-primary-color: var(--primary)"></kal-calendar>
+```
+
+> **Set `--calendar-primary-color-rgb` alongside `--calendar-primary-color`.**
+> Translucent fills — cell hover, the picker shadow — are built as
+> `rgba(var(--calendar-primary-color-rgb), …)`, because CSS cannot take the
+> channels out of a hex colour. Change the colour without the channels and
+> those fills keep the old hue. The value is three bare numbers, no `rgb()`.
+
+Every demo under `docs/examples/` has a **Brand Colour** control that does
+exactly this, so you can see which parts of the calendar follow the base token.
+
 ### JS theme property (full reference)
 
 Every `--calendar-*` colour token has a matching camelCase theme key.
 
+> `theme` writes its values to `:root`, so it colours **every** `<kal-calendar>`
+> on the page, not the element you assign it to. With one calendar that is
+> harmless; with two, the last assignment wins for both. Use the element-scoped
+> custom properties above to theme them separately.
+
 ```js
 cal.theme = {
   primary: '#3b82f6',

package/dist/styles/calendar.css

@@ -56,12 +56,6 @@
   --calendar-event-indicator: var(--kal-blue-500);
   --calendar-input-invalid: var(--kal-red-500);
   --calendar-input-invalid-rgb: 239, 68, 68;
-  --calendar-input-invalid-bg: rgba(var(--calendar-input-invalid-rgb), 0.1);
-  --calendar-nav-arrow-fg: var(--calendar-text-color);
-  --calendar-nav-arrow-bg: var(--calendar-background);
-  --calendar-nav-arrow-border: var(--calendar-border-color);
-  --calendar-nav-arrow-hover-fg: var(--calendar-on-accent);
-  --calendar-nav-arrow-hover-bg: var(--calendar-primary-color);
   --calendar-popup-header-fg: var(--kal-white);
   --calendar-popup-close-fg: var(--kal-white);
   --calendar-popup-close-bg: rgba(255, 255, 255, 0.2);
@@ -135,8 +129,6 @@
   --calendar-shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.08);
   --calendar-shadow-md: 0 2px 6px rgba(0, 0, 0, 0.12);
   --calendar-shadow-lg: 0 4px 12px rgba(0, 0, 0, 0.15);
-  --calendar-shadow-primary: 0 2px 8px
-    rgba(var(--calendar-primary-color-rgb), 0.2);
   /* Spacing scale — rem so padding tracks the type scale */
   --calendar-space-0-5: 0.125rem;
   --calendar-space-1: 0.25rem;
@@ -212,20 +204,27 @@
   justify-content: center;
   width: 36px;
   height: 36px;
-  border: 1px solid var(--calendar-nav-arrow-border);
+  border: 1px solid
+    var(--calendar-nav-arrow-border, var(--calendar-border-color));
   border-radius: var(--calendar-radius-md);
-  background: var(--calendar-nav-arrow-bg);
+  background: var(--calendar-nav-arrow-bg, var(--calendar-background));
   cursor: pointer;
   font-size: var(--calendar-font-lg);
-  color: var(--calendar-nav-arrow-fg);
+  color: var(--calendar-nav-arrow-fg, var(--calendar-text-color));
   transition: all 0.2s ease;
   flex-shrink: 0;
 }
 
 .calendar-nav-arrow:hover {
-  background-color: var(--calendar-nav-arrow-hover-bg);
-  border-color: var(--calendar-nav-arrow-hover-bg);
-  color: var(--calendar-nav-arrow-hover-fg);
+  background-color: var(
+    --calendar-nav-arrow-hover-bg,
+    var(--calendar-primary-color)
+  );
+  border-color: var(
+    --calendar-nav-arrow-hover-bg,
+    var(--calendar-primary-color)
+  );
+  color: var(--calendar-nav-arrow-hover-fg, var(--calendar-on-accent));
 }
 
 .calendar-picker-container {
@@ -258,7 +257,10 @@
 
 .calendar-picker-btn[aria-expanded='true'] {
   border-color: var(--calendar-primary-color);
-  box-shadow: var(--calendar-shadow-primary);
+  box-shadow: var(
+    --calendar-shadow-primary,
+    0 2px 8px rgba(var(--calendar-primary-color-rgb), 0.2)
+  );
 }
 
 .calendar-picker-chevron {
@@ -370,7 +372,10 @@
 
 .calendar-picker-year-input.invalid {
   border-color: var(--calendar-input-invalid);
-  background-color: var(--calendar-input-invalid-bg);
+  background-color: var(
+    --calendar-input-invalid-bg,
+    rgba(var(--calendar-input-invalid-rgb), 0.1)
+  );
 }
 
 .calendar-picker-months {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kalendly",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "A universal calendar web component — works in React, Vue, Angular, Svelte, Solid.js, and plain HTML with no framework dependency",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",