@pastweb/components-core 2.0.0 → 2.2.0

package/dist/Carousel/README.md

@@ -0,0 +1,204 @@
+# Carousel
+
+Carousel presents one item from an ordered collection and provides controls for
+moving through the collection. Its web contract follows the WAI-ARIA carousel
+pattern.
+
+## When to use
+
+Use a carousel only when the content has a meaningful sequence and users can
+understand the page without seeing every slide.
+
+## Carousel props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and state classes. |
+| `ariaLabel` | `string` | no | `'Carousel'` | Names the carousel region. Supply a content-specific label. |
+| `className` | `string` | no | `""` | Adds classes to the carousel. |
+| `current` | `number` | no | `0` | Sets the current slide index. |
+| `disabled` | `boolean` | no | - | Prevents navigation and disables controls. |
+| `id` | `string` | no | generated | Supplies the carousel ID. Generated IDs use the `carousel` prefix. |
+| `showCommands` | `boolean` | no | `true` | Renders navigation controls. |
+| `prevAriaLabel` | `string` | no | `'Previous slide'` | Names the previous control. |
+| `nextAriaLabel` | `string` | no | `'Next slide'` | Names the next control. |
+| `onCurrentChange` | `(current: number) => void` | no | - | Reports navigation changes. |
+
+## CarouselItem props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves item classes. |
+| `className` | `string` | no | `""` | Adds classes to the slide. |
+| `disabled` | `boolean` | no | - | Disables the slide and exposes its disabled state. |
+
+## Mediator state
+
+`carouselMediator` exposes renderer-ready state for the root semantics and
+track presentation:
+
+| State | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized carousel name. |
+| `ariaLive` | `'off' \| 'polite'` | Live-region mode for slide changes. |
+| `ariaRoleDescription` | `'carousel' \| undefined` | Carousel role description when the root is named. |
+| `className` | `string` | Complete root class name. |
+| `current` | `number` | Current slide index. |
+| `isDisabled` | `true \| undefined` | Renderer-ready disabled and ARIA value. |
+| `itemsCount` | `number` | Number of registered CarouselItem instances. |
+| `prevAriaLabel` / `nextAriaLabel` | `string` | Normalized navigation-control names. |
+| `role` | `'region' \| undefined` | Region role when the root is named. |
+| `transform` | `string` | Renderer-ready track transform. |
+
+`carouselItemMediator` reads the Carousel context internally and exposes the
+following renderer-ready state:
+
+| State | Type | Description |
+|---|---|---|
+| `ariaHidden` | `true \| undefined` | Hides an inactive slide from the accessibility tree. |
+| `ariaLabel` | `string` | One-based position label in the form `n of total`. |
+| `ariaRoleDescription` | `'slide'` | Renderer-ready slide role description. |
+| `className` | `string` | Complete item class name, including active and disabled state classes. |
+| `index` | `number` | Stable zero-based registration index. |
+| `inert` | `true \| undefined` | Prevents interaction with descendants of an inactive slide. |
+| `isActive` | `boolean` | Whether this item matches the current Carousel index. |
+| `isDisabled` | `true \| undefined` | Normalized local or inherited disabled state. |
+| `role` | `'group'` | Renderer-ready slide group role. |
+
+## Carousel mediator context
+
+`carouselMediator.getContext()` exposes live state and stable commands for
+`CarouselItem` and custom descendant controls. Framework renderers publish this
+contract through `CAROUSEL_CONTEXT_KEY`; command slots do not receive mediator
+state or methods as slot props.
+
+| Property or method | Type | Description |
+|---|---|---|
+| `current` | `number` | Live current slide index. |
+| `isDisabled` | `true \| undefined` | Live normalized Carousel disabled state. |
+| `itemsCount` | `number` | Live number of registered CarouselItem descendants. |
+| `prev` | `() => void` | Selects the previous enabled position when navigation is available. |
+| `next` | `() => void` | Selects the next enabled position when navigation is available. |
+| `registerItem` | `() => number` | Registers a CarouselItem and returns its stable zero-based index. |
+
+## Slots
+
+| SlotName | Description | Access |
+|---|---|---|
+| default | Supplies `CarouselItem` children. | - |
+| `commands` | Replaces the navigation controls while preserving behavior. | Carousel context |
+
+## Utility classes
+
+The Carousel does not currently define component-specific utility classes.
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Carousel_root_default_max-width` | `root` | `default` | `max-width` | `800px` | Maximum carousel width. | Web, Capacitor |
+| `--pw_Carousel_root_disabled_opacity` | `root` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Disabled carousel opacity. | Web, Capacitor, NativeScript |
+| `--pw_Carousel_track_default_transition-duration` | `track` | `default` | `transition-duration` | `0.5s` | Slide movement duration. | Web, Capacitor; NativeScript adapter |
+| `--pw_Carousel_control_default_background-color` | `control` | `default` | `background-color` | `rgba(0,0,0,.6)` | Control background. | Web, Capacitor, NativeScript |
+| `--pw_Carousel_control_hover_background-color` | `control` | `hover` | `background-color` | `rgba(0,0,0,.8)` | Hover background. | Web, Capacitor |
+| `--pw_Carousel_control_default_color` | `control` | `default` | `color` | `white` | Control foreground. | Web, Capacitor, NativeScript |
+| `--pw_Carousel_control_default_padding` | `control` | `default` | `padding` | `0.75em 1em` | Control spacing. | Web, Capacitor, NativeScript |
+| `--pw_Carousel_control_default_font-size` | `control` | `default` | `font-size` | `1.25em` | Control icon size. | Web, Capacitor, NativeScript |
+| `--pw_Carousel_control_default_border-radius` | `control` | `default` | `border-radius` | `var(--pw_border-radius)` | Control corner radius. | Web, Capacitor, NativeScript |
+| `--pw_Carousel_control_default_transition-duration` | `control` | `default` | `transition-duration` | `0.3s` | Control state duration. | Web, Capacitor |
+| `--pw_CarouselItem_root_default_min-height` | `root` | `default` | `min-height` | `300px` | Minimum slide height. | Web, Capacitor, NativeScript |
+| `--pw_CarouselItem_root_default_transition-duration` | `root` | `default` | `transition-duration` | `0.5s` | Slide visual transition duration. | Web, Capacitor; NativeScript adapter |
+| `--pw_CarouselItem_root_disabled_opacity` | `root` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Disabled slide opacity. | Web, Capacitor, NativeScript |
+
+```xts
+import { setContext, useBeforeMount, useBeforeUnmount, useMediator, withDefaultProps } from '@pastweb/x';
+import {
+  carouselItemMediator,
+  carouselMediator,
+  CAROUSEL_CONTEXT_KEY,
+  DEFAULT_CAROUSEL_ITEM_PROPS,
+  DEFAULT_PROPS,
+} from '@pastweb/components-core/Carousel';
+
+export function Carousel(props: CarouselProps) {
+  const p = withDefaultProps<CarouselDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<CarouselMediator>(carouselMediator, p);
+  const s = m.state;
+  const c = m.getContext();
+
+  setContext(CAROUSEL_CONTEXT_KEY, c);
+
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <div
+      id={m.id}
+      class={s.className}
+      role={s.role}
+      aria-roledescription={s.ariaRoleDescription}
+      aria-label={s.ariaLabel}
+      aria-disabled={s.isDisabled}
+      @keydown={m.onKeyDown}
+    >
+      <div class={p.cls('carouselInner')} #style={{ transform: s.transform }} aria-live={s.ariaLive}>
+        {p.children}
+      </div>
+      <slot #if={p.showCommands} name="commands">
+        <button class={p.cls('prev')} type="button" @click={m.prev} disabled={s.isDisabled} aria-disabled={s.isDisabled} aria-label={s.prevAriaLabel}>
+          <span aria-hidden="true">◄</span>
+        </button>
+        <button class={p.cls('next')} type="button" @click={m.next} disabled={s.isDisabled} aria-disabled={s.isDisabled} aria-label={s.nextAriaLabel}>
+          <span aria-hidden="true">►</span>
+        </button>
+      </slot>
+    </div>
+  );
+}
+
+export function CarouselItem(props: CarouselItemProps) {
+  const p = withDefaultProps<CarouselItemDefaultProps>(props, DEFAULT_CAROUSEL_ITEM_PROPS);
+  const m = useMediator<CarouselItemMediator>(carouselItemMediator, p);
+  const s = m.state;
+
+  useBeforeMount(m.useBeforeMount);
+
+  return (
+    <div
+      class={s.className}
+      role={s.role}
+      aria-roledescription={s.ariaRoleDescription}
+      aria-label={s.ariaLabel}
+      aria-hidden={s.ariaHidden}
+      aria-disabled={s.isDisabled}
+      inert={s.inert}
+    >
+      <slot />
+    </div>
+  );
+}
+```
+
+## Keyboard interaction
+
+- `Tab` and `Shift+Tab` move through the carousel and its native controls in document order.
+- `ArrowLeft` and `ArrowRight` move to the previous and next slides when the carousel is focused.
+- Collapsed or inactive slide content is inert and removed from sequential focus.
+
+## Accessibility notes
+
+- The carousel is a labelled region with `aria-roledescription="carousel"`.
+- Slides use `role="group"`, expose their position, and inactive slides are
+  `aria-hidden` and inert.
+- The default `ariaLabel` is `"Carousel"`. An explicit empty string omits the
+  root label, region role, and carousel role description.
+- A disabled Carousel passes the same normalized `true` value to its
+  `is-disabled` class, control `disabled`/`aria-disabled` attributes, root
+  `aria-disabled`, and inherited CarouselItem state.
+- Left and Right Arrow navigate; native buttons remain in normal tab order.
+- Shared styles honor `prefers-reduced-motion` and `forced-colors`.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Carousel pattern: https://www.w3.org/WAI/ARIA/apg/patterns/carousel/
+- GOV.UK guidance: https://design-system.service.gov.uk/components/

package/dist/Checkbox/README.md

@@ -0,0 +1,140 @@
+# Checkbox
+
+Checkbox renders a native binary choice with a visible label or explicit
+accessible name. Its rendering contract follows the WAI-ARIA Checkbox pattern
+and targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use a checkbox when users may independently select or clear one option. Provide
+a concise visible label that describes the choice. Do not use a checkbox when
+exactly one option must be selected from a group; use radio buttons then.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and state classes. |
+| `ariaLabel` | `string` | no | `"Checkbox"` | Names the checkbox when no visible `label` is supplied. Pass an empty string to omit the accessible name. |
+| `checkChar` | `string` | no | `✔` | Supplies the default checked mark. |
+| `className` | `string` | no | `""` | Adds classes to the wrapper. |
+| `id` | `string` | no | generated | Supplies the native input ID. Generated IDs use the `checkbox` prefix. |
+| `disabled` | `boolean` | no | - | Makes the choice unavailable. |
+| `label` | `string` | no | `""` | Supplies the visible accessible label. |
+| `labelPlacement` | `Placement` | no | `'top-start'` | Places the visible label around the box. |
+| `name` | `string` | no | - | Supplies the form field name. |
+| `value` | `boolean` | no | - | Controls the checked state. |
+| `tabIndex` | `number` | no | `0` | Controls sequential focus order. Prefer the default document order. |
+| `onChange` | `(checked: boolean) => void` | no | noop | Reports checked-state changes. |
+
+## Mediator API
+
+| Property | Type | Description |
+|---|---|---|
+| `id` | `string` | Resolved input ID. Generated IDs use the `checkbox` prefix; an explicit `id` is exposed as `_${id}`. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized accessible name when no visible `label` is present. Empty labels are omitted. |
+| `isDisabled` | `true \| undefined` | Is `true` when the checkbox is disabled; otherwise omitted. Renderers use this value directly for `.is-disabled`, `disabled`, and `aria-disabled`. |
+| `value` | `boolean` | Checked state consumed as `.is-checked` and the native `checked` property. |
+
+## Slots
+
+| SlotName | Description | Default content | Props |
+|---|---|---|---|
+| `check` | Replaces the decorative checked mark. | `<span>{checkChar}</span>` | `{ checkChar }` |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Checkbox_root_default_margin` | `root` | `default` | `margin` | shared margins | Component spacing. | Web, Capacitor, NativeScript |
+| `--pw_Checkbox_root_disabled_opacity` | `root` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Disabled opacity. | Web, Capacitor, NativeScript |
+| `--pw_Checkbox_root_default_size` | `root` | `default` | `size` | line-height plus padding and border | Box width and height, with a 44px web minimum. | Web, Capacitor, NativeScript |
+| `--pw_Checkbox_root_default_background-color` | `root` | `default` | `background-color` | `var(--pw_control_background-color)` | Box background. | Web, Capacitor, NativeScript |
+| `--pw_Checkbox_root_default_border-color` | `root` | `default` | `border-color` | `var(--pw_border-color)` | Box border colour. | Web, Capacitor, NativeScript |
+| `--pw_Checkbox_root_default_border-width` | `root` | `default` | `border-width` | `var(--pw_border-width)` | Box border width. | Web, Capacitor, NativeScript |
+| `--pw_Checkbox_root_default_border-style` | `root` | `default` | `border-style` | `var(--pw_border-style)` | Box border style. | Web, Capacitor, NativeScript |
+| `--pw_Checkbox_root_default_border-radius` | `root` | `default` | `border-radius` | `var(--pw_border-radius)` | Box corner radius. | Web, Capacitor, NativeScript |
+| `--pw_Checkbox_check_default_size` | `check` | `default` | `font-size` | `1.5em` | Checked mark size. | Web, Capacitor, NativeScript |
+| `--pw_Checkbox_label_default_color` | `label` | `default` | `color` | `var(--pw_label_text_color)` | Label colour. | Web, Capacitor, NativeScript |
+
+```xts
+import { useBeforeUnmount, useMediator, withDefaultProps } from '@pastweb/x';
+import { checkboxMediator } from '@pastweb/components-core/Checkbox';
+import { DEFAULT_PROPS } from './constants';
+
+export function Checkbox(props: CheckboxProps) {
+  const p = withDefaultProps<CheckboxDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<CheckboxMediator>(checkboxMediator, p);
+  const s = m.state;
+
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <div
+      class={p.cls('Checkbox', `label-${p.labelPlacement}`, p.className, {
+        'is-disabled': s.isDisabled,
+        'is-checked': s.value,
+      })}
+    >
+      <label class={p.cls('control')}>
+        <span class={p.cls('box')}>
+          <input
+            type="checkbox"
+            class={p.cls('input')}
+            id={m.id}
+            name={p.name}
+            checked={s.value}
+            disabled={s.isDisabled}
+            aria-disabled={s.isDisabled}
+            aria-label={s.ariaLabel}
+            tabIndex={p.tabIndex}
+            @change={event => m.onChange(event.target.checked)}
+          />
+          <slot name="check" props={{ checkChar: p.checkChar }}>
+            <span class={p.cls('check')} aria-hidden="true">{p.checkChar}</span>
+          </slot>
+        </span>
+        <span #if={p.label} class={p.cls('label', p.labelPlacement)}>{p.label}</span>
+      </label>
+    </div>
+  );
+}
+```
+
+## Keyboard interaction
+
+- `Tab` and `Shift+Tab` move focus to and from the native checkbox in document order.
+- `Space` toggles the checked state through native checkbox behavior.
+
+## Accessibility notes
+
+- The input remains a native checkbox. One wrapping label supplies the visible
+  accessible name, avoiding multiple labels for the same control.
+- When visible label text is absent, the mediator exposes `ariaLabel`. The
+  default name is `Checkbox`. An explicit empty string omits the name.
+- Disabled checkboxes use the native `disabled` property, `aria-disabled="true"`,
+  and the `is-disabled` class.
+- Checked state is exposed through the native `checked` property and the
+  `is-checked` class.
+- The decorative check is hidden from assistive technology. Replacement `check`
+  slot content must remain decorative.
+- Shared web styles provide at least a 44 by 44 CSS-pixel target, visible focus,
+  forced-colours treatment, and reduced-motion behavior.
+
+## Known limitations
+
+- The custom checked mark is visual only. Do not place interactive content in
+  the `check` slot.
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Checkbox pattern: https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/
+- GOV.UK Checkboxes guidance: https://design-system.service.gov.uk/components/checkboxes/

package/dist/DateTimePicker/README.md

@@ -0,0 +1,125 @@
+# DateTimePicker
+
+`DateTimePicker` is a framework-neutral calendar and time-selection mediator. Renderers provide the target and popup integration; the mediator owns value normalization, single/multiple/range selection, calendar navigation, date rules, and keyboard intent.
+
+## Features
+
+- Single, multiple, and range date selection.
+- Optional time selection, calendar-only, and time-only modes.
+- Controlled or uncontrolled popup visibility and selected values.
+- Keyboard calendar navigation, date rules, localized labels, and accessible IDs.
+- A renderer-neutral target-props context for custom trigger implementations.
+
+```xts
+<DateTimePicker
+  mode="range"
+  enableTime
+  minDate={today}
+  disable={[weekends]}
+  locale={{ months, weekdays, clear: 'Clear' }}
+  onChange={value => booking.dates = value}
+/>
+```
+
+## Values
+
+Use a `Date`, an array of `Date` values, or `null`. `single` returns one date in an array internally and `multiple`/`range` return arrays. The public change callback uses `Date | Date[] | null` so consumers can preserve the same value shape they provide.
+
+```xts
+<DateTimePicker value={departure} onChange={value => departure = value} />
+<DateTimePicker mode="multiple" defaultValue={[firstDate, secondDate]} />
+<DateTimePicker mode="range" value={stay} />
+```
+
+## Calendar rules and language
+
+`minDate`, `maxDate`, `disable`, and `enable` constrain selection. Rules accept a date, an inclusive `{ from, to }` range, or a predicate returning `true` when it matches.
+
+The component does not read an application i18n service. Supply the calendar words directly with `locale` when a language is required.
+
+```xts
+<DateTimePicker
+  minDate={today}
+  disable={[date => date.getDay() === 0 || date.getDay() === 6]}
+  locale={{
+    months: italianMonths,
+    weekdays: italianWeekdays,
+    previousMonth: 'Mese precedente',
+    nextMonth: 'Mese successivo',
+  }}
+/>
+```
+
+## Rendering modes
+
+The default picker is positioned locally, like `Select`. Set `inline` for an always-visible calendar that does not open and close.
+
+```xts
+<DateTimePicker inline weekNumbers showMonths={1} />
+<DateTimePicker enableTime noCalendar minuteIncrement={15} />
+```
+
+## Calendar presentation
+
+Set `yearSelect` to render a compact year selector beside the month name. Its range follows `minDate` and `maxDate`, or otherwise surrounds the viewed year.
+
+`workingWeekDays` counts working days from Monday (default `5` for Monday–Friday). Remaining days receive the `is-free-day` state. Saturdays and Sundays always receive `is-sat` and `is-sun`; dates listed in `holidaysDates` receive `is-holiday`. Use `getDayClassName` for application-specific states.
+
+```xts
+<DateTimePicker
+  yearSelect
+  workingWeekDays={4}
+  holidaysDates={[companyHoliday]}
+  getDayClassName={date => date.toDateString() === releaseDay.toDateString() ? 'is-release-day' : undefined}
+/>
+```
+
+## Target and accessibility labels
+
+Renderers use their default target when no `target` slot is supplied. The default target displays date and time values as `<date> - <time>`, caps its width at `20rem`, and horizontally scrolls long multiple selections while keeping the arrow visible. Override the width through `--pw_DateTimePicker_target_default_max-width`.
+
+Set `label` and `labelPlacement` to render a visible label using the same placement utilities as `Select`. `labelPlacement` defaults to `'top-start'` and accepts the standard placement values such as `'bottom'`, `'left-end'`, and `'right-start'`. A visible label is linked to the default target through `aria-labelledby`.
+
+```xts
+<DateTimePicker label="Appointment" labelPlacement="left" />
+```
+
+Provide `ariaLabel`, `previousMonthAriaLabel`, `nextMonthAriaLabel`, `yearSelectAriaLabel`, `selectTimeAriaLabel`, and `backToCalendarAriaLabel` when the default English labels do not fit the product vocabulary.
+
+```xts
+<DateTimePicker
+  ariaLabel="Appointment date and time"
+  previousMonthAriaLabel="Show previous appointment month"
+  selectTimeAriaLabel="Choose appointment time"
+/>
+```
+
+## Renderer integration
+
+Renderers own their target, calendar, and time-toggle references, then provide
+them together after mounting. This keeps the mediator independent of framework
+ref objects and slot mechanisms.
+
+```xts
+const triggerReference = getTriggerElement();
+const calendarReference = getCalendarElement();
+const timeToggleReference = getTimeToggleElement();
+
+mediator.useMounted(
+  triggerReference,
+  calendarReference,
+  timeToggleReference,
+);
+```
+
+Custom targets consume renderer-provided bindings from the shared
+`DATETIME_PICKER_TRIGGER_PROPS_CONTEXT_KEY`. The core
+`DateTimePickerTriggerProps` contract provides the ID, role, tab index, ARIA
+attributes, and click/keyboard handlers. Each renderer adapts only its own ref
+and event types.
+
+## Summary
+
+Use DateTimePicker when users need to choose a date, date range, or time with
+calendar guidance. Use a native date input when the browser-provided control is
+sufficient and a richer calendar interface is unnecessary.