forty-cdk 0.25.2 → 0.26.0

package/calendar/README.md

@@ -13,6 +13,12 @@ Headless and styleless — the date table at the heart of the APG [Date Picker D
 
 `ForCalendar` is the grid widget, **not a form value** — it exposes `[(value)]` as a `model<D | null>`. The form-control contract (`FormValueControl<D>`) arrives with the follow-up `ForDatePicker` / `ForDateField`.
 
+## When to choose
+
+- **Calendar** — the date grid itself, always visible, exposing `[(value)]` as a model. It is a widget, not a form control: it implements no `FormValueControl` contract, so `[formField]` binds a picker or a field instead.
+- **[Date Picker](../date-picker/README.md)** — wraps this same grid in a trigger-anchored floating surface and _is_ the form value. Choose it when a form owns the date and the grid should stay collapsed until asked for.
+- **[Date Field](../date-field/README.md)** — segmented typed entry with no grid. Choose it when the date is known rather than browsed.
+
 ## Date adapter
 
 All date math goes through a `DateAdapter<D>`, so the library hard-depends on **no** date library. Provide exactly one adapter in your application (or component) providers (required):
@@ -22,6 +28,8 @@ All date math goes through a `DateAdapter<D>`, so the library hard-depends on **
 | `provideInternationalizedDateAdapter()` | `CalendarDate` (`@internationalized/date`) | **Recommended.** From `forty-cdk/internationalized-date`; needs `@internationalized/date` (optional peer) |
 | `provideNativeDateAdapter()`            | `Date`                                     | None (zero-dependency fallback)                                                                           |
 
+<!-- snippet: fragment -->
+
 ```ts
 import { bootstrapApplication } from '@angular/platform-browser';
 import { provideInternationalizedDateAdapter } from 'forty-cdk/internationalized-date';
@@ -42,9 +50,31 @@ bootstrapApplication(App, {
 ```html
 <div forCalendar [(value)]="date">
   <header>
-    <button forCalendarPrevButton [ariaLabel]="'Previous month'">‹</button>
+    <button forCalendarPrevButton [ariaLabel]="'Previous month'">
+      <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
+        <path
+          d="m15.75 19.5-7.5-7.5 7.5-7.5"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="1.75"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        />
+      </svg>
+    </button>
     <h2 forCalendarHeading #heading="forCalendarHeading">{{ heading.label() }}</h2>
-    <button forCalendarNextButton [ariaLabel]="'Next month'">›</button>
+    <button forCalendarNextButton [ariaLabel]="'Next month'">
+      <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
+        <path
+          d="m8.25 4.5 7.5 7.5-7.5 7.5"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="1.75"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        />
+      </svg>
+    </button>
   </header>
 
   <table forCalendarGrid #grid="forCalendarGrid">
@@ -67,9 +97,11 @@ bootstrapApplication(App, {
 
 ## Examples
 
+Move across the grid with the arrow keys, page with `PageUp` / `PageDown`, and select with `Enter` — every cell reflects `data-selected`, `data-today` and `data-outside-month`.
+
 ```ts
 import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
-import { CalendarDate, today, getLocalTimeZone } from '@internationalized/date';
+import { type CalendarDate, getLocalTimeZone, today } from '@internationalized/date';
 import {
   ForCalendar,
   ForCalendarCell,
@@ -79,9 +111,10 @@ import {
   ForCalendarNextButton,
   ForCalendarPrevButton,
 } from 'forty-cdk/calendar';
+import { provideInternationalizedDateAdapter } from 'forty-cdk/internationalized-date';
 
 @Component({
-  selector: 'app-date',
+  selector: 'app-calendar-default-example',
   changeDetection: ChangeDetectionStrategy.OnPush,
   imports: [
     ForCalendar,
@@ -92,19 +125,46 @@ import {
     ForCalendarGridHeader,
     ForCalendarCell,
   ],
+  providers: [...provideInternationalizedDateAdapter()],
   template: `
-    <div forCalendar [(value)]="date">
-      <header>
-        <button forCalendarPrevButton [ariaLabel]="'Previous month'">‹</button>
-        <h2 forCalendarHeading #heading="forCalendarHeading">{{ heading.label() }}</h2>
-        <button forCalendarNextButton [ariaLabel]="'Next month'">›</button>
+    <div forCalendar class="calendar" [(value)]="value">
+      <header class="calendar-header">
+        <button forCalendarPrevButton class="calendar-nav" [ariaLabel]="'Previous month'">
+          <svg viewBox="0 0 24 24" aria-hidden="true">
+            <path
+              d="m15.75 19.5-7.5-7.5 7.5-7.5"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="1.75"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+            />
+          </svg>
+        </button>
+        <h2 forCalendarHeading #heading="forCalendarHeading" class="calendar-title">
+          {{ heading.label() }}
+        </h2>
+        <button forCalendarNextButton class="calendar-nav" [ariaLabel]="'Next month'">
+          <svg viewBox="0 0 24 24" aria-hidden="true">
+            <path
+              d="m8.25 4.5 7.5 7.5-7.5 7.5"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="1.75"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+            />
+          </svg>
+        </button>
       </header>
 
-      <table forCalendarGrid #grid="forCalendarGrid">
+      <table forCalendarGrid #grid="forCalendarGrid" class="calendar-grid">
         <thead forCalendarGridHeader>
           <tr>
             @for (day of grid.weekDays(); track day.key) {
-              <th scope="col" [attr.aria-label]="day.long">{{ day.short }}</th>
+              <th scope="col" class="calendar-weekday" [attr.aria-label]="day.long">
+                {{ day.narrow }}
+              </th>
             }
           </tr>
         </thead>
@@ -121,13 +181,33 @@ import {
     </div>
   `,
 })
-export class DatePage {
-  readonly date = signal<CalendarDate | null>(today(getLocalTimeZone()));
+export class CalendarDefaultExample {
+  protected readonly value = signal<CalendarDate | null>(today(getLocalTimeZone()));
 }
 ```
 
 The library is styleless: style the boolean `data-*` hooks on `[forCalendarCell]` yourself (`[data-selected]`, `[data-today]`, `[data-outside-month]`, `[data-highlighted]`, and `:not([data-disabled])` for the enabled state).
 
+### States
+
+One class and one directive, three states. `disabled` turns off focus movement and selection for the whole calendar; `readonly` keeps days focusable and the grid still pages, but clicking or pressing `Enter` no longer changes the selection. Each reflects a root hook — `data-disabled` and `data-readonly` — and the example's stylesheet keys on nothing else.
+
+### Constraints & week start
+
+`min` disables past dates and `isDateUnavailable` blocks weekends — both reflect `aria-disabled` and refuse selection, while arrows still move across them so navigation is never trapped. `firstDayOfWeek` starts the week on Monday.
+
+### Range selection
+
+Set `selectionMode="range"` and bind `[(range)]` to a `DateRange` signal. Click a first cell to anchor the range, move the pointer to preview, click a second cell to commit. Committed cells reflect `data-range-start` / `data-range-end` / `data-in-range`; the preview band uses `data-range-preview`.
+
+### Month / year dropdowns
+
+`[forCalendarMonthSelect]` and `[forCalendarYearSelect]` wire native selects to the calendar's month/year navigation. Render the options yourself from `m.options()` and `y.years()`; months and years entirely outside `[min, max]` are disabled.
+
+### View switching (month / year picker)
+
+Click the heading button to cycle from day → month → year view. Click a month to drill down to days; click a year to drill down to months. Prev/next pages by month, year, or block depending on the active view, and `min` / `max` disable out-of-range cells.
+
 ## API
 
 ### `ForCalendar`
@@ -251,7 +331,18 @@ The recommended path is `[forCalendarMonthSelect]` and `[forCalendarYearSelect]`
 ```html
 <div forCalendar [(value)]="date">
   <header>
-    <button forCalendarPrevButton [ariaLabel]="'Previous month'">‹</button>
+    <button forCalendarPrevButton [ariaLabel]="'Previous month'">
+      <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
+        <path
+          d="m15.75 19.5-7.5-7.5 7.5-7.5"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="1.75"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        />
+      </svg>
+    </button>
     <select forCalendarMonthSelect #m="forCalendarMonthSelect">
       @for (opt of m.options(); track opt.value) {
       <option [value]="opt.value" [disabled]="opt.disabled">{{ opt.label }}</option>
@@ -262,7 +353,18 @@ The recommended path is `[forCalendarMonthSelect]` and `[forCalendarYearSelect]`
       <option [value]="opt.value" [disabled]="opt.disabled">{{ opt.value }}</option>
       }
     </select>
-    <button forCalendarNextButton [ariaLabel]="'Next month'">›</button>
+    <button forCalendarNextButton [ariaLabel]="'Next month'">
+      <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
+        <path
+          d="m8.25 4.5 7.5 7.5-7.5 7.5"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="1.75"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        />
+      </svg>
+    </button>
     <h2 forCalendarHeading class="sr-only" #h="forCalendarHeading">{{ h.label() }}</h2>
   </header>
   <table forCalendarGrid>
@@ -317,9 +419,31 @@ The lower-level hooks (`visibleMonthNumber()`, `visibleYear()`, `monthOptions()`
 ```html
 <div forCalendar [(value)]="date" #cal="forCalendar">
   <header>
-    <button forCalendarPrevButton [ariaLabel]="'Previous'">‹</button>
+    <button forCalendarPrevButton [ariaLabel]="'Previous'">
+      <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
+        <path
+          d="m15.75 19.5-7.5-7.5 7.5-7.5"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="1.75"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        />
+      </svg>
+    </button>
     <button forCalendarViewTrigger #vt="forCalendarViewTrigger">{{ vt.label() }}</button>
-    <button forCalendarNextButton [ariaLabel]="'Next'">›</button>
+    <button forCalendarNextButton [ariaLabel]="'Next'">
+      <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
+        <path
+          d="m8.25 4.5 7.5 7.5-7.5 7.5"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="1.75"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        />
+      </svg>
+    </button>
     <!-- keep a visually-hidden heading so the grid stays labelled -->
     <h2 forCalendarHeading #h="forCalendarHeading" class="sr-only">{{ h.label() }}</h2>
   </header>

package/carousel/README.md

@@ -15,7 +15,18 @@ Headless and styleless: it ships slide tracking, keyboard navigation, focus mana
 
 ```html
 <div forCarousel [(activeIndex)]="index" loop ariaLabel="Featured products">
-  <button forCarouselPrevious aria-label="Previous slide">‹</button>
+  <button forCarouselPrevious aria-label="Previous slide">
+    <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
+      <path
+        d="m15.75 19.5-7.5-7.5 7.5-7.5"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.75"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      />
+    </svg>
+  </button>
 
   <div forCarouselViewport>
     <div forCarouselTrack>
@@ -24,7 +35,18 @@ Headless and styleless: it ships slide tracking, keyboard navigation, focus mana
     </div>
   </div>
 
-  <button forCarouselNext aria-label="Next slide">›</button>
+  <button forCarouselNext aria-label="Next slide">
+    <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
+      <path
+        d="m8.25 4.5 7.5 7.5-7.5 7.5"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.75"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      />
+    </svg>
+  </button>
 
   <div forCarouselIndicators ariaLabel="Choose slide to display">
     <!-- one [forCarouselIndicator] per slide, same order -->
@@ -35,44 +57,122 @@ Headless and styleless: it ships slide tracking, keyboard navigation, focus mana
 
 ## Examples
 
-### Basic carousel
+Page through the slides with the buttons, the arrow keys or a drag — `data-dragging` is on while a pointer holds the track, and the root carries `data-orientation`.
 
-```html
-<div
-  forCarousel
-  [(activeIndex)]="index"
-  loop
-  orientation="horizontal"
-  ariaLabel="Featured products"
->
-  <button forCarouselPrevious aria-label="Previous slide">‹</button>
+```ts
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import {
+  ForCarousel,
+  ForCarouselIndicator,
+  ForCarouselIndicators,
+  ForCarouselNext,
+  ForCarouselPrevious,
+  ForCarouselSlide,
+  ForCarouselTrack,
+  ForCarouselViewport,
+} from 'forty-cdk/carousel';
+
+interface Slide {
+  readonly id: number;
+  readonly label: string;
+}
 
-  <div forCarouselViewport>
-    <div forCarouselTrack>
-      @for (product of products(); track product.id) {
-      <div forCarouselSlide>{{ product.name }}</div>
-      }
+@Component({
+  selector: 'app-carousel-default-example',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    ForCarousel,
+    ForCarouselViewport,
+    ForCarouselTrack,
+    ForCarouselSlide,
+    ForCarouselPrevious,
+    ForCarouselNext,
+    ForCarouselIndicators,
+    ForCarouselIndicator,
+  ],
+  template: `
+    <div
+      forCarousel
+      class="car"
+      [(activeIndex)]="activeIndex"
+      loop
+      orientation="horizontal"
+      align="start"
+      ariaLabel="Featured slides"
+    >
+      <div class="car-controls-row">
+        <button forCarouselPrevious class="car-btn" aria-label="Previous slide">
+          <svg viewBox="0 0 24 24" aria-hidden="true">
+            <path
+              d="m15.75 19.5-7.5-7.5 7.5-7.5"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="1.75"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+            />
+          </svg>
+        </button>
+        <button forCarouselNext class="car-btn" aria-label="Next slide">
+          <svg viewBox="0 0 24 24" aria-hidden="true">
+            <path
+              d="m8.25 4.5 7.5 7.5-7.5 7.5"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="1.75"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+            />
+          </svg>
+        </button>
+      </div>
+
+      <div forCarouselViewport class="car-viewport">
+        <div forCarouselTrack class="car-track">
+          @for (slide of slides; track slide.id; let i = $index) {
+            <div forCarouselSlide class="car-slide" [class]="'car-slide--' + (i + 1)">
+              <span class="car-slide-label">{{ slide.label }}</span>
+            </div>
+          }
+        </div>
+      </div>
+
+      <div forCarouselIndicators class="car-indicators" ariaLabel="Choose slide to display">
+        @for (slide of slides; track slide.id; let i = $index) {
+          <button
+            forCarouselIndicator
+            class="car-dot"
+            [attr.aria-label]="'Go to slide ' + (i + 1)"
+          ></button>
+        }
+      </div>
     </div>
-  </div>
+  `,
+})
+export class CarouselDefaultExample {
+  protected readonly slides: readonly Slide[] = [
+    { id: 1, label: 'Slide 1' },
+    { id: 2, label: 'Slide 2' },
+    { id: 3, label: 'Slide 3' },
+    { id: 4, label: 'Slide 4' },
+    { id: 5, label: 'Slide 5' },
+  ];
+
+  protected readonly activeIndex = signal(0);
+}
+```
 
-  <button forCarouselNext aria-label="Next slide">›</button>
+### Multiple slides per view
 
-  <div forCarouselIndicators ariaLabel="Choose slide to display">
-    @for (product of products(); track product.id; let i = $index) {
-    <button forCarouselIndicator [attr.aria-label]="'Go to slide ' + (i + 1)"></button>
-    }
-  </div>
-</div>
-```
+Set `slidesPerView` above `1` to show several slides at once. Each slide is `flex: 0 0 calc(100% / var(--for-carousel-slides-per-view))`; `loop` wraps once the last visible set is reached.
 
-### Indicators map 1:1 to slides
+### Autoplay with pause control
 
-The picker assumes **one `[forCarouselIndicator]` per `[forCarouselSlide]`**: the
-indicator at DOM index `i` targets slide `i`. Iterate the same collection that
-drives the slides (as above) so the counts always match. A mismatched count
-desynchronizes the active-indicator state and is dev-guarded by a `console.warn`
-in development builds. Grouped or summarized indicators (fewer dots than slides)
-are not supported.
+`[forCarouselRotationControl]` is the first focusable child (APG / WCAG 2.2.2). Rotation pauses on hover, on keyboard focus inside the carousel, and while the tab is backgrounded; an explicit stop is sticky. Under `prefers-reduced-motion` it does not auto-start.
+
+### Drag / swipe
+
+Add the opt-in `[forCarouselDrag]` directive to the viewport for pointer drag and touch swipe. The track follows the finger 1:1 via `--for-carousel-swipe-movement-x/y`, then snaps to the nearest slide on release.
 
 ## Autoplay
 
@@ -82,11 +182,38 @@ focusable child** of the carousel to enable automatic slide rotation.
 ```html
 <div forCarousel autoplay [autoplayInterval]="4000" ariaLabel="Featured products">
   <button forCarouselRotationControl>
-    <!-- swap icon with [data-playing] in your CSS -->
+    <svg class="icon-play" viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
+      <path d="M6.75 5.25 17.25 12 6.75 18.75z" fill="currentColor" />
+    </svg>
+    <svg class="icon-pause" viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
+      <path d="M8.25 5.25h3v13.5h-3zM12.75 5.25h3v13.5h-3z" fill="currentColor" />
+    </svg>
+  </button>
+  <button forCarouselPrevious aria-label="Previous slide">
+    <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
+      <path
+        d="m15.75 19.5-7.5-7.5 7.5-7.5"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.75"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      />
+    </svg>
   </button>
-  <button forCarouselPrevious aria-label="Previous slide">‹</button>
   <div forCarouselViewport>…</div>
-  <button forCarouselNext aria-label="Next slide">›</button>
+  <button forCarouselNext aria-label="Next slide">
+    <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
+      <path
+        d="m8.25 4.5 7.5 7.5-7.5 7.5"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.75"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      />
+    </svg>
+  </button>
   <div forCarouselIndicators ariaLabel="Choose slide to display">…</div>
 </div>
 ```
@@ -128,6 +255,8 @@ an `aria-label` overriding it.
 <div forCarousel #car="forCarousel" autoplay>…</div>
 ```
 
+<!-- snippet: fragment -->
+
 ```ts
 car.play(); // start (explicit, sticky)
 car.pause(); // stop (explicit, sticky)
@@ -214,6 +343,8 @@ indicator's is `"Go to slide N"`, and the rotation control's swaps between
 all centrally with `provideForCarouselDefaults` instead of setting `ariaLabel` on
 every slide and indicator:
 
+<!-- snippet: fragment -->
+
 ```ts
 providers: [
   provideForCarouselDefaults({
@@ -231,6 +362,15 @@ rest of the defaults. A per-element `ariaLabel` on `[forCarouselSlide]` /
 `[forCarouselIndicator]` still takes precedence over the localized default, as do
 `[startLabel]` / `[stopLabel]` on `[forCarouselRotationControl]`.
 
+## Indicators map 1:1 to slides
+
+The picker assumes **one `[forCarouselIndicator]` per `[forCarouselSlide]`**: the
+indicator at DOM index `i` targets slide `i`. Iterate the same collection that
+drives the slides so the counts always match. A mismatched count
+desynchronizes the active-indicator state and is dev-guarded by a `console.warn`
+in development builds. Grouped or summarized indicators (fewer dots than slides)
+are not supported.
+
 ## API
 
 ### `ForCarousel`
@@ -376,12 +516,16 @@ children, unless noted otherwise:
 
 ### Autoplay styling hooks
 
+Render both icons inside the control and let `data-playing` pick which one shows — the
+control keeps its own accessible name either way, so the icons stay `aria-hidden`.
+
 ```css
-[forCarouselRotationControl]::before {
-  content: '▶';
+[forCarouselRotationControl] .icon-pause,
+[forCarouselRotationControl][data-playing] .icon-play {
+  display: none;
 }
-[forCarouselRotationControl][data-playing]::before {
-  content: '⏸';
+[forCarouselRotationControl][data-playing] .icon-pause {
+  display: revert;
 }
 ```
 

package/checkbox/README.md

@@ -31,31 +31,34 @@ Use the one that matches your semantics. `ForCheckbox` and `ForSwitch` are inten
 
 ## Examples
 
-### Stand-alone
+Tick it with the pointer or `Space` and watch `data-state` move between `checked` and `unchecked` — the box is a `<button>`, so its whole appearance is your CSS.
 
 ```ts
-import { Component, signal } from '@angular/core';
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
 import { ForCheckbox } from 'forty-cdk/checkbox';
 
 @Component({
-  selector: 'demo-terms',
+  selector: 'app-checkbox-default-example',
+  changeDetection: ChangeDetectionStrategy.OnPush,
   imports: [ForCheckbox],
   template: `
-    <label>
-      <button forCheckbox class="checkbox" [(checked)]="agreed">
-        <span class="indicator"></span>
-      </button>
+    <button forCheckbox class="cb-row" [(checked)]="checked">
+      <span class="cb">
+        <span class="cb-check" aria-hidden="true"></span>
+      </span>
       I agree to the terms
-    </label>
+    </button>
   `,
 })
-export class DemoTerms {
-  readonly agreed = signal(false);
+export class CheckboxDefaultExample {
+  protected readonly checked = signal(false);
 }
 ```
 
 ### Tri-state ("select all")
 
+A parent checkbox reflects `indeterminate` when only some children are selected. Activating it selects or clears them all at once, matching native inputs.
+
 ```ts
 import { Component, computed, signal } from '@angular/core';
 import { ForCheckbox } from 'forty-cdk/checkbox';
@@ -96,8 +99,14 @@ export class DemoSelectAll {
 }
 ```
 
+### States
+
+One class and one directive, three states. `disabled` and `readonly` both keep the box focusable and announced (per APG) while click and `Space` are a no-op; they reflect `data-disabled` and `data-readonly`, which is all the example's stylesheet keys on.
+
 ### Signal Forms
 
+`forCheckbox` implements `FormCheckboxControl`, so a single `[formField]` binding wires the binary `checked` value into the form and pulls validity back out. The box is required: blur it unchecked and it reflects `data-invalid` / `data-touched`.
+
 ```ts
 import { Component, signal } from '@angular/core';
 import { form, required } from '@angular/forms/signals';