diff --git a/NOTICE b/NOTICE index 43bcc1da..38fc591e 100644 --- a/NOTICE +++ b/NOTICE @@ -21,6 +21,12 @@ M3 Expressive carousel keylines (resources/js/carousel.js) Ported from androidx Compose Material 3 (carousel/*.kt), as recorded at the top of the file. Copyright The Android Open Source Project. Apache License 2.0. +M3 time picker (resources/js/timepicker.js, resources/css/components/timepicker.css) + Behaviour and geometry ported from androidx Compose Material 3 (TimePicker.kt, + TimePickerDialog.kt, tokens/TimePickerTokens.kt, tokens/TimeInputTokens.kt), as recorded at + the top of resources/js/timepicker.js. + Copyright The Android Open Source Project. Apache License 2.0. + Google Sans Flex (resources/fonts/google-sans-flex) Copyright Google LLC. SIL Open Font License 1.1 (resources/fonts/google-sans-flex/OFL.txt). Subset: Latin and Latin Extended, weight 400–700, roundness 0–100. diff --git a/resources/boost/skills/livewire-material-development/SKILL.md b/resources/boost/skills/livewire-material-development/SKILL.md index afe1af0b..3c202962 100644 --- a/resources/boost/skills/livewire-material-development/SKILL.md +++ b/resources/boost/skills/livewire-material-development/SKILL.md @@ -463,6 +463,28 @@ M3 Expressive's slider on native ``s (one per handle), so th Other attributes go to the input(s). A `wire:model.live` slider sends while it is dragged, and a server render never moves a handle under the pointer (the drawing is `wire:ignore`); a value the server sets moves the handle after the morph. The binding gets `.number`, so values arrive as numbers. Its width is the container's unless a `w-*` class is passed. +### `` + +M3's time picker in a modal dialog, opened from a read-only text field (a press, Enter, Space, ArrowDown or its clock icon). The dial picks the hour, then the minutes, by press or drag; a 24-hour clock puts 12–23 on the inner ring. The keyboard icon switches to two text fields. The arrow keys change the focused dial's value, Home and End go to the ends, Enter confirms; Escape, Cancel or the scrim close it unchanged and give focus back to the field. In a landscape window the dial lies on its side. + +```blade + + +``` + +| Prop | Default | | +|---|---|---| +| `wire:model` / `x-model` | | the time as `H:i`, null until chosen; `H:i:s` (a `time` column) is read and written back as `H:i`; nothing is written until OK | +| `format` | the locale's | `12` or `24`; otherwise the hour cycle of `locale` as `Intl.DateTimeFormat` reports it | +| `locale` | app locale | the hour cycle, and how the field writes the time | +| `step` | `1` | minutes between choices (a tap picks fives, or steps when five is not a multiple of the step) | +| `min`, `max` | | `H:i`, inclusive; `min` later than `max` spans midnight. Outside values are greyed out and refused in the picker — validate on the server as well | +| `clearable` | `false` | a button that empties the field | +| `name` | | posts the value from a hidden input | +| `label`, `hint`, `icon`, `variant`, `size` | | the field's; `required`, `disabled` and `placeholder` reach its input | + +Errors under the `wire:model` name replace the hint. The dialog is `wire:ignore`: a Livewire render leaves an open picker open with its draft. Never name a Livewire property `$slot`: it renders empty in the component's view. + ### `` Choosing from a list, with typed values (an array of integers stays integers). `options` (`id`, `name`, `disabled`; `option-value`, `option-label`), `label`, `hint`, `single`. Errors for the property and its items replace the hint. diff --git a/resources/css/components/timepicker.css b/resources/css/components/timepicker.css new file mode 100644 index 00000000..f08c012b --- /dev/null +++ b/resources/css/components/timepicker.css @@ -0,0 +1,460 @@ +/* + * M3's time picker (resources/views/components/timepicker.blade.php, resources/js/timepicker.js): + * the dial, the input variant, and the dialog around them. + * + * Sizes and roles are androidx Compose Material 3's (TimePickerTokens, TimeInputTokens, TimePicker.kt + * and TimePickerDialog.kt at commit 27cf9a7d5788aa0f5f2d8b6699ce279560daf326, Apache-2.0): + * + * [data-timepicker-surface] surface-container-high, extra-large corner, elevation 3; 24px in + * [data-timepicker-title] label-medium, on-surface-variant, 20px above the content + * [data-timepicker-picker] the dial variant + * [data-timepicker-display] the time selector: hour and minute boxes 96×80 (display-large, + * small corner; primary-container when selected, otherwise + * surface-container-highest), a 24px separator, and the period + * selector 52×80 beside them, 4px away + * [data-timepicker-dial] 256px, surface-container-highest; numbers in body-large at radius + * 101 (the 24-hour inner ring at 69), a primary selector — a 2px line, + * an 8px centre and a 48px handle — with the number under the handle + * in on-primary; 36px below the display, 24px above the actions + * [data-timepicker-inputs] the input variant: fields 96×72 in display-medium, "Hour" and + * "Minute" (or the error) below in body-small, the period 52×72 + * [data-timepicker-actions] a 48px row: the mode toggle, then Cancel and OK + * + * The period selector is Compose's current one (ComposeMaterial3Flags.isUpdatedTimepickerToggleEnabled, + * on by default): two toggle buttons 4px apart, round and surface-container-lowest when off, a 12px + * corner and primary-container with a bold label when on, not the outlined pair of the tokens. + * + * In a landscape window the dial variant lies on its side, as Compose's HorizontalTimePicker does + * whenever the screen is wider than it is tall: the display with the period selector (216×38, 16px + * under it) on the start side, the dial 36px after it, the actions under both; and the dial shrinks + * to 238 or 200px when the window is short (ClockFaceSizeModifier). The input variant always stands. + * + * The selector's angle is a registered property, so a single transition turns the line, carries the + * handle round and moves the clip that inks the number under it, on the default spatial spring. The + * numbers cross-fade between hours and minutes on the default effects spring. + */ + +@property --timepicker-angle { + syntax: ''; + inherits: true; + initial-value: 0deg; +} + +@layer components { + [data-timepicker-field] .field-control { + cursor: pointer; + caret-color: transparent; + } + + [data-timepicker-dialog] { + max-width: calc(100vw - 2rem); + max-height: calc(100dvh - 2rem); + } + + [data-timepicker-surface] { + display: grid; + grid-template-columns: max-content; + justify-content: center; + padding: 1.5rem; + border-radius: var(--md-sys-shape-corner-xl); + background-color: var(--md-sys-color-surface-container-high); + box-shadow: var(--md-sys-elevation-3); + color: var(--md-sys-color-on-surface); + } + + [data-timepicker-title] { + padding-bottom: 1.25rem; + color: var(--md-sys-color-on-surface-variant); + font: var(--md-sys-typescale-label-md); + letter-spacing: var(--md-sys-typescale-label-md-tracking); + } + + [data-timepicker-picker] { + display: flex; + flex-direction: column; + align-items: center; + } + + /* The mode is an attribute rather than x-show, which shows only on the next frame: focus moves + into the variant that was just switched to within the same tick. */ + [data-timepicker-surface]:not([data-mode="input"]) :is([data-timepicker-typing], [data-timepicker-when="input"]), + [data-timepicker-surface][data-mode="input"] :is([data-timepicker-picker], [data-timepicker-when="dial"]) { + display: none; + } + + [data-timepicker-when] { + display: contents; + } + + /* ---- The time selector and the period selector ------------------------------------------ */ + + [data-timepicker-display] { + display: flex; + margin-bottom: 2.25rem; + } + + [data-timepicker-numbers], + [data-timepicker-inputs] { + display: flex; + align-items: flex-start; + direction: ltr; + } + + [data-timepicker-box] { + display: grid; + place-items: center; + width: 6rem; + height: 5rem; + border-radius: var(--md-sys-shape-corner-sm); + background-color: var(--md-sys-color-surface-container-highest); + color: var(--md-sys-color-on-surface); + font: var(--md-sys-typescale-display-lg); + letter-spacing: var(--md-sys-typescale-display-lg-tracking); + font-variant-numeric: tabular-nums; + cursor: pointer; + transition-property: background-color, color; + transition-duration: var(--md-sys-motion-effects-fast-duration); + transition-timing-function: var(--md-sys-motion-effects-fast); + } + + [data-timepicker-box][aria-pressed="true"] { + background-color: var(--md-sys-color-primary-container); + color: var(--md-sys-color-on-primary-container); + } + + [data-timepicker-separator] { + display: grid; + place-items: center; + width: 1.5rem; + height: 5rem; + color: var(--md-sys-color-on-surface); + font: var(--md-sys-typescale-display-lg); + translate: 0 -0.25rem; + user-select: none; + } + + [data-timepicker-period] { + display: flex; + flex-direction: column; + gap: 0.25rem; + width: 3.25rem; + height: 5rem; + margin-inline-start: 0.25rem; + } + + [data-timepicker-period] > button { + flex: 1 1 0%; + min-width: 0; + border-radius: var(--md-sys-shape-corner-full); + background-color: var(--md-sys-color-surface-container-lowest); + color: var(--md-sys-color-on-surface-variant); + font: var(--md-sys-typescale-title-md); + letter-spacing: var(--md-sys-typescale-title-md-tracking); + cursor: pointer; + transition-property: border-radius, background-color, color; + transition-duration: var(--md-sys-motion-spatial-fast-duration); + transition-timing-function: var(--md-sys-motion-spatial-fast); + } + + [data-timepicker-period] > button:active, + [data-timepicker-period] > button[aria-pressed="true"] { + border-radius: 0.75rem; + } + + [data-timepicker-period] > button[aria-pressed="true"] { + background-color: var(--md-sys-color-primary-container); + color: var(--md-sys-color-on-primary-container); + font-weight: var(--md-ref-typeface-weight-bold); + } + + [data-timepicker-period] > button:disabled { + cursor: default; + color: color-mix(in srgb, var(--md-sys-color-on-surface) 38%, transparent); + background-color: color-mix(in srgb, var(--md-sys-color-on-surface) 10%, transparent); + } + + /* ---- The dial ----------------------------------------------------------------------------- */ + + [data-timepicker-dial] { + --dial: 16rem; + --unit: calc(var(--dial) / 256); + --outer: calc(101 * var(--unit)); + --inner: calc(69 * var(--unit)); + --handle: calc(48 * var(--unit)); + --reach: var(--outer); + + position: relative; + flex: none; + width: var(--dial); + height: var(--dial); + margin-bottom: 1.5rem; + border-radius: var(--md-sys-shape-corner-full); + background-color: var(--md-sys-color-surface-container-highest); + color: var(--md-sys-color-on-surface); + font: var(--md-sys-typescale-body-lg); + letter-spacing: var(--md-sys-typescale-body-lg-tracking); + cursor: pointer; + touch-action: none; + user-select: none; + -webkit-user-select: none; + -webkit-tap-highlight-color: transparent; + outline: none; + direction: ltr; + transition: --timepicker-angle var(--md-sys-motion-spatial-default-duration) var(--md-sys-motion-spatial-default); + } + + [data-timepicker-dial]:focus-visible { + outline: 3px solid var(--md-sys-color-secondary); + outline-offset: 2px; + } + + /* A drag keeps the handle under the pointer; the spring only settles it on release. */ + [data-timepicker-dial][data-dragging] { + transition: none; + } + + [data-timepicker-dial][data-inner] { + --reach: var(--inner); + } + + [data-timepicker-labels], + [data-timepicker-ink], + [data-timepicker-set] { + position: absolute; + inset: 0; + } + + [data-timepicker-set] { + transition-property: opacity, visibility; + transition-duration: var(--md-sys-motion-effects-default-duration); + transition-timing-function: var(--md-sys-motion-effects-default); + } + + [data-timepicker-dial]:not([data-cycle="24"]) [data-timepicker-set="hour24"], + [data-timepicker-dial][data-cycle="24"] [data-timepicker-set="hour12"] { + display: none; + } + + [data-timepicker-dial][data-view="minute"] :is([data-timepicker-set="hour12"], [data-timepicker-set="hour24"]), + [data-timepicker-dial]:not([data-view="minute"]) [data-timepicker-set="minute"] { + opacity: 0; + visibility: hidden; + } + + [data-timepicker-set] > span { + --ring: var(--outer); + + position: absolute; + left: calc(50% + var(--x) * var(--ring)); + top: calc(50% + var(--y) * var(--ring)); + display: grid; + place-items: center; + width: 3rem; + height: 3rem; + translate: -50% -50%; + border-radius: var(--md-sys-shape-corner-full); + font-variant-numeric: tabular-nums; + } + + [data-timepicker-set] > span[data-inner] { + --ring: var(--inner); + } + + [data-timepicker-set] > span[data-disabled] { + color: color-mix(in srgb, var(--md-sys-color-on-surface) 38%, transparent); + } + + /* The selector: the line from the centre to the handle's edge, the centre dot, the handle. */ + [data-timepicker-selector] { + position: absolute; + inset: 0; + pointer-events: none; + } + + [data-timepicker-track] { + position: absolute; + left: calc(50% - 1px); + bottom: 50%; + width: 2px; + height: calc(var(--reach) - var(--handle) / 2); + background-color: var(--md-sys-color-primary); + transform-origin: 50% 100%; + rotate: var(--timepicker-angle); + } + + [data-timepicker-centre], + [data-timepicker-handle] { + position: absolute; + translate: -50% -50%; + border-radius: var(--md-sys-shape-corner-full); + background-color: var(--md-sys-color-primary); + } + + [data-timepicker-centre] { + left: 50%; + top: 50%; + width: 0.5rem; + height: 0.5rem; + } + + [data-timepicker-handle] { + left: calc(50% + sin(var(--timepicker-angle)) * var(--reach)); + top: calc(50% - cos(var(--timepicker-angle)) * var(--reach)); + width: var(--handle); + height: var(--handle); + } + + /* The numbers again, in on-primary, cut to the handle: what Compose draws with BlendMode.DstOver. */ + [data-timepicker-ink] { + color: var(--md-sys-color-on-primary); + pointer-events: none; + clip-path: circle(calc(var(--handle) / 2) at calc(50% + sin(var(--timepicker-angle)) * var(--reach)) calc(50% - cos(var(--timepicker-angle)) * var(--reach))); + } + + [data-timepicker-ink] [data-timepicker-set] > span[data-disabled] { + color: inherit; + } + + /* ---- The input variant -------------------------------------------------------------------- */ + + [data-timepicker-inputs] [data-timepicker-separator] { + height: 4.5rem; + } + + [data-timepicker-inputs] [data-timepicker-period] { + height: 4.5rem; + } + + [data-timepicker-column] { + width: 6rem; + } + + [data-timepicker-input] { + display: block; + width: 6rem; + height: 4.5rem; + padding: 0; + border: 0; + border-radius: var(--md-sys-shape-corner-sm); + outline: none; + background-color: var(--md-sys-color-surface-container-highest); + color: var(--md-sys-color-on-surface); + caret-color: var(--md-sys-color-primary); + font: var(--md-sys-typescale-display-md); + letter-spacing: var(--md-sys-typescale-display-md-tracking); + font-variant-numeric: tabular-nums; + text-align: center; + transition-property: background-color, color, box-shadow; + transition-duration: var(--md-sys-motion-effects-fast-duration); + transition-timing-function: var(--md-sys-motion-effects-fast); + } + + [data-timepicker-input]:focus { + background-color: var(--md-sys-color-primary-container); + color: var(--md-sys-color-on-primary-container); + box-shadow: inset 0 0 0 2px var(--md-sys-color-primary); + } + + [data-timepicker-input][aria-invalid="true"] { + background-color: var(--md-sys-color-error-container); + color: var(--md-sys-color-error); + caret-color: var(--md-sys-color-error); + box-shadow: inset 0 0 0 1px var(--md-sys-color-error); + } + + [data-timepicker-input][aria-invalid="true"]:focus { + box-shadow: inset 0 0 0 2px var(--md-sys-color-error); + } + + /* SupportingText: two lines' room, 7px under the field; the error in its place. */ + [data-timepicker-support] { + min-height: 2rem; + padding-top: 0.4375rem; + color: var(--md-sys-color-on-surface-variant); + font: var(--md-sys-typescale-body-sm); + letter-spacing: var(--md-sys-typescale-body-sm-tracking); + } + + [data-timepicker-support][data-error], + [data-timepicker-range-error] { + color: var(--md-sys-color-error); + } + + [data-timepicker-range-error] { + max-width: 17rem; + padding-bottom: 0.5rem; + font: var(--md-sys-typescale-body-sm); + letter-spacing: var(--md-sys-typescale-body-sm-tracking); + } + + [data-timepicker-actions] { + display: flex; + align-items: center; + gap: 0.5rem; + min-height: 3rem; + } + + [data-timepicker-actions] > [data-timepicker-spacer] { + flex: 1 1 0%; + } + + /* ---- Landscape ---------------------------------------------------------------------------- */ + + @media (orientation: landscape) and (min-width: 37rem) { + [data-timepicker-surface][data-mode="dial"] { + grid-template-columns: 13.5rem auto; + grid-template-areas: + "display dial" + "actions actions"; + column-gap: 2.25rem; + padding: 1rem 1.5rem 0.5rem; + } + + [data-timepicker-surface][data-mode="dial"] [data-timepicker-title] { + grid-area: display; + align-self: start; + margin-top: 0.5rem; + padding: 0; + } + + [data-timepicker-surface][data-mode="dial"] [data-timepicker-picker] { + display: contents; + } + + [data-timepicker-surface][data-mode="dial"] [data-timepicker-display] { + grid-area: display; + flex-direction: column; + align-self: center; + margin: 0; + } + + [data-timepicker-surface][data-mode="dial"] [data-timepicker-display] [data-timepicker-period] { + flex-direction: row; + width: 13.5rem; + height: 2.375rem; + margin: 1rem 0 0; + } + + [data-timepicker-surface][data-mode="dial"] [data-timepicker-dial] { + grid-area: dial; + margin: 0; + } + + [data-timepicker-surface][data-mode="dial"] [data-timepicker-actions] { + grid-area: actions; + margin-top: 0.25rem; + } + } + + @media (orientation: landscape) and (min-width: 37rem) and (max-height: 22.75rem) { + [data-timepicker-surface][data-mode="dial"] [data-timepicker-dial] { + --dial: 14.875rem; + } + } + + @media (orientation: landscape) and (min-width: 37rem) and (max-height: 21.625rem) { + [data-timepicker-surface][data-mode="dial"] [data-timepicker-dial] { + --dial: 12.5rem; + } + } +} diff --git a/resources/css/material.css b/resources/css/material.css index 6f9aa261..69a0cb8b 100644 --- a/resources/css/material.css +++ b/resources/css/material.css @@ -26,6 +26,7 @@ @import './components/menu.css'; @import './components/selection.css'; @import './components/search.css'; +@import './components/timepicker.css'; @import './components/tabs.css'; @import './components/app-bar.css'; @import './components/toolbar.css'; diff --git a/resources/js/material.js b/resources/js/material.js index 770f394a..cb248e1f 100644 --- a/resources/js/material.js +++ b/resources/js/material.js @@ -20,6 +20,7 @@ import './carousel.js' import './chips.js' import './field.js' import './search.js' +import './timepicker.js' import './slider.js' import './tabs.js' import './app-bar.js' diff --git a/resources/js/timepicker.js b/resources/js/timepicker.js new file mode 100644 index 00000000..9c4b69bb --- /dev/null +++ b/resources/js/timepicker.js @@ -0,0 +1,684 @@ +/** + * `materialTimepicker(value, config)`: the behaviour of `` — a field that opens M3's + * time picker in a modal ``, as a clock dial or as two text fields. + * + * The picker edits a draft, `hour` (0–23) and `minute`; only OK writes it to `value` as `H:i`. + * Cancel, Escape and a press on the scrim leave `value` alone, and every close hands focus back to + * the field. Whether the hours run 1–12 with AM and PM or 0–23 comes from `config.format` or, without + * one, from the locale (`Intl.DateTimeFormat(locale, { hour: 'numeric' })`'s hour cycle). + * + * The dial: + * - A press sets the value where it lands, and the selector turns there on the default spatial + * spring; a drag makes the handle follow the pointer and settles on the nearest value when + * released. Hours then move on to minutes, as Compose does after a tap (100ms later) or a drag. + * - On a 24-hour dial the inner ring holds 12–23 and the outer 00–11: a press nearer the centre than + * 74dp (scaled with the dial) is on the inner ring. + * - A tap picks minutes in fives (or in `step`s, when `step` is not a divisor of five); a drag in ones + * (or `step`s). + * - The dial is a slider for the keyboard: the arrows change the hour or minute it shows, Home and End + * go to the first and last allowed, Enter confirms. The keyboard never moves on to minutes by + * itself; the hour and minute boxes above the dial switch between them. + * + * `min` and `max` (`H:i`, inclusive; `min` later than `max` is a range across midnight) and `step` + * (minutes) limit what can be chosen: a tap on a number outside them does nothing, a drag and the + * arrows skip to the nearest allowed value, a period switch that would leave them lands on the + * nearest allowed time, and typed values outside them are errors. They are a + * convenience for the person choosing, not validation — validate on the server too. + * + * The selector's angle is a registered custom property (`--timepicker-angle`, components/ + * timepicker.css), so one CSS transition turns the line, moves the handle, and moves the clip that + * shows the number under the handle in on-primary, all on the same spring. + * + * --------------------------------------------------------------------------------------- + * Behaviour and geometry follow androidx Compose Material 3 (https://github.com/androidx/androidx), + * commit 27cf9a7d5788aa0f5f2d8b6699ce279560daf326: + * + * compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/TimePicker.kt + * (AnalogTimePickerState.rotateTo, endValueForAnimation, moveSelector, onTap, ClockDialNode, + * selectorPos, TimeInputImpl, shouldSwitchFocusToMinute, the ring and distance constants) + * + * Copyright 2022-2026 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * --------------------------------------------------------------------------------------- + */ + +/** ClockDialContainerSize: the dial's own coordinate space. */ +const DIAL = 256 + +/** MaxDistance: nearer the centre than this, a 24-hour dial is on its inner ring. */ +const INNER_REACH = 74 + +/** onTap's delay(100) before a tapped hour moves on to minutes. */ +const MOVE_ON_MS = 100 + +/** How far a pointer moves before a press on the dial is a drag. */ +const DRAG_SLOP = 4 + +const pad = (number) => String(number).padStart(2, '0') + +/** "1–12" stays on one line in a 96px column: word joiners either side of a dash between numbers. */ +const keepRange = (text) => text.replace(/(\d)\s*([–-])\s*(\d)/g, '$1\u2060$2\u2060$3') + +/** The shortest way round from one angle to another, in degrees. */ +const turn = (from, to) => ((((to - from) % 360) + 540) % 360) - 180 + +function parse(value) { + const match = /^(\d{1,2}):(\d{2})/.exec(typeof value === 'string' ? value : '') + + if (!match) { + return null + } + + const hour = Number(match[1]) + const minute = Number(match[2]) + + return hour < 24 && minute < 60 ? hour * 60 + minute : null +} + +document.addEventListener('alpine:init', () => { + window.Alpine.data('materialTimepicker', (value = null, config = {}) => ({ + value, + open: false, + mode: 'dial', + view: 'hour', + hour: 0, + minute: 0, + angle: 0, + dragging: false, + scrimPressed: false, + hourText: '', + minuteText: '', + attempted: false, + is24: false, + step: 1, + earliest: null, + latest: null, + moveOn: null, + formatter: null, + periods: ['AM', 'PM'], + + init() { + const locale = config.locale || undefined + + try { + this.is24 = config.format ? Number(config.format) === 24 : ['h23', 'h24'].includes(new Intl.DateTimeFormat(locale, { hour: 'numeric' }).resolvedOptions().hourCycle) + this.formatter = new Intl.DateTimeFormat(locale, { hour: 'numeric', minute: '2-digit', hourCycle: this.is24 ? 'h23' : 'h12' }) + const dayPeriod = (hour) => new Intl.DateTimeFormat(locale, { hour: 'numeric', hourCycle: 'h12' }).formatToParts(new Date(2000, 0, 1, hour)).find((part) => part.type === 'dayPeriod')?.value + this.periods = [dayPeriod(9) ?? config.strings.am, dayPeriod(21) ?? config.strings.pm] + } catch { + this.is24 = Number(config.format) === 24 + this.formatter = null + this.periods = [config.strings.am, config.strings.pm] + } + + this.step = Math.min(Math.max(Math.trunc(Number(config.step) || 1), 1), 60) + this.earliest = parse(config.min) + this.latest = parse(config.max) + }, + + // ---- What is shown --------------------------------------------------------------------- + + get display() { + const time = parse(this.value) + + return time === null ? '' : this.format(time) + }, + + format(time) { + const date = new Date(2000, 0, 1, Math.floor(time / 60), time % 60) + + return this.formatter ? this.formatter.format(date) : `${pad(date.getHours())}:${pad(date.getMinutes())}` + }, + + get isPm() { + return this.hour >= 12 + }, + + get hourLabel() { + return this.is24 ? pad(this.hour) : pad(this.hour % 12 || 12) + }, + + get minuteLabel() { + return pad(this.minute) + }, + + /** selectorPos: a 24-hour dial's afternoon hours are on the inner ring. */ + get inner() { + return this.is24 && this.view === 'hour' && this.hour >= 12 + }, + + get valueText() { + const strings = config.strings + + if (this.view === 'minute') { + return strings.minutes.replace(':minute', this.minute) + } + + return this.is24 ? strings.hours.replace(':hour', this.hour) : `${strings.oclock.replace(':hour', this.hour % 12 || 12)} ${this.periods[this.isPm ? 1 : 0]}` + }, + + // ---- What may be chosen ---------------------------------------------------------------- + + inRange(time) { + const { earliest, latest } = this + + if (earliest !== null && latest !== null && earliest > latest) { + return time >= earliest || time <= latest + } + + return (earliest === null || time >= earliest) && (latest === null || time <= latest) + }, + + allowed(hour, minute) { + return minute % this.step === 0 && this.inRange(hour * 60 + minute) + }, + + hourAllowed(hour) { + for (let minute = 0; minute < 60; minute += this.step) { + if (this.allowed(hour, minute)) { + return true + } + } + + return false + }, + + minuteAllowed(minute) { + return this.allowed(this.hour, minute) + }, + + periodAllowed(pm) { + for (let hour = pm ? 12 : 0; hour < (pm ? 24 : 12); hour++) { + if (this.hourAllowed(hour)) { + return true + } + } + + return false + }, + + /** The allowed time nearest to one that is not, searching outwards a minute at a time. */ + nearest(time) { + for (let distance = 0; distance <= 720; distance++) { + for (const candidate of [time - distance, time + distance]) { + const wrapped = (candidate + 1440) % 1440 + + if (this.allowed(Math.floor(wrapped / 60), wrapped % 60)) { + return wrapped + } + } + } + + return null + }, + + /** The minute nearest to this one that the current hour allows. */ + nearestMinute(minute) { + for (let distance = 0; distance <= 30; distance++) { + for (const candidate of [minute - distance, minute + distance]) { + const wrapped = (candidate + 60) % 60 + + if (this.minuteAllowed(wrapped)) { + return wrapped + } + } + } + + return null + }, + + /** The hour nearest to this one on its own ring (period), then on the other. */ + nearestHour(hour) { + const base = hour >= 12 ? 12 : 0 + + for (const ring of [base, 12 - base]) { + for (let distance = 0; distance <= 6; distance++) { + for (const candidate of [hour - distance, hour + distance]) { + const inRing = ring + ((((candidate - base) % 12) + 12) % 12) + + if (this.hourAllowed(inRing)) { + return inRing + } + } + } + + if (!this.is24) { + return null + } + } + + return null + }, + + settle(time) { + const allowed = this.allowed(Math.floor(time / 60), time % 60) ? time : this.nearest(time) + + if (allowed !== null) { + this.hour = Math.floor(allowed / 60) + this.minute = allowed % 60 + } + }, + + /** An hour chosen: keep the minute if the new hour allows it, otherwise the nearest one it does. */ + setHour(hour) { + this.hour = hour + + if (!this.minuteAllowed(this.minute)) { + this.minute = this.nearestMinute(this.minute) ?? this.minute + } + }, + + // ---- The dialog ------------------------------------------------------------------------ + + show() { + if (this.open || this.$refs.input.disabled) { + return + } + + const now = new Date() + const time = parse(this.value) ?? now.getHours() * 60 + Math.round(now.getMinutes() / this.step) * this.step + + this.settle(time % 1440) + this.view = 'hour' + this.attempted = false + this.fillText() + this.angle = this.angleFor() + this.open = true + + // After Alpine has drawn the draft, so nothing animates from the last time it was open. + this.$nextTick(() => { + this.$refs.dialog.showModal() + this.focusMode() + }) + }, + + cancel() { + this.$refs.dialog.close() + }, + + confirm() { + if (this.mode === 'input' && !this.readText()) { + return + } + + if (!this.allowed(this.hour, this.minute)) { + return + } + + this.value = `${pad(this.hour)}:${pad(this.minute)}` + this.$refs.dialog.close() + }, + + closed() { + clearTimeout(this.moveOn) + this.open = false + this.dragging = false + this.$refs.input.focus({ preventScroll: true }) + }, + + focusMode() { + if (this.mode === 'input') { + const field = this.view === 'minute' ? this.$refs.minuteInput : this.$refs.hourInput + + field.focus() + field.select() + } else { + this.$refs.dial.focus({ preventScroll: true }) + } + }, + + toggleMode() { + clearTimeout(this.moveOn) + + if (this.mode === 'dial') { + this.mode = 'input' + this.attempted = false + this.fillText() + } else { + this.mode = 'dial' + this.angle = this.angleFor() + } + + this.$nextTick(() => this.focusMode()) + }, + + /** The hour or minute box above the dial. */ + choose(view) { + clearTimeout(this.moveOn) + this.view = view + this.aim() + }, + + setPeriod(pm) { + if (this.isPm === pm || !this.periodAllowed(pm)) { + return + } + + const hour = this.hour + (pm ? 12 : -12) + + if (this.hourAllowed(hour)) { + this.setHour(hour) + } else { + const time = this.nearestInPeriod(pm, hour * 60 + this.minute) + + this.hour = Math.floor(time / 60) + this.minute = time % 60 + } + + this.fillText() + this.aim() + }, + + /** The allowed time in a period nearest to `time` (periodAllowed has said there is one). */ + nearestInPeriod(pm, time) { + let best = null + + for (let candidate = pm ? 720 : 0; candidate < (pm ? 1440 : 720); candidate++) { + if (this.allowed(Math.floor(candidate / 60), candidate % 60) && (best === null || Math.abs(candidate - time) < Math.abs(best - time))) { + best = candidate + } + } + + return best ?? time + }, + + // ---- The dial -------------------------------------------------------------------------- + + angleFor() { + return this.view === 'hour' ? (this.hour % 12) * 30 : this.minute * 6 + }, + + /** endValueForAnimation: turn the short way round, so 11 to 1 never spins backwards. */ + aim(degrees = this.angleFor()) { + this.angle += turn(this.angle, degrees) + }, + + press(event) { + if (event.button !== 0 || !event.isPrimary) { + return + } + + event.preventDefault() + clearTimeout(this.moveOn) + + const dial = this.$refs.dial + const startX = event.clientX + const startY = event.clientY + let dragged = false + + dial.focus({ preventScroll: true }) + + try { + dial.setPointerCapture(event.pointerId) + } catch { + // A pointer the browser does not know (a synthetic event) cannot be captured. + } + + const move = (moveEvent) => { + if (!dragged && Math.hypot(moveEvent.clientX - startX, moveEvent.clientY - startY) < DRAG_SLOP) { + return + } + + dragged = true + this.dragging = true + this.pick(moveEvent, false) + } + + const release = (upEvent, cancelled = false) => { + dial.removeEventListener('pointermove', move) + dial.removeEventListener('pointerup', release) + dial.removeEventListener('pointercancel', abandon) + this.dragging = false + + if (cancelled) { + this.aim() + + return + } + + if (dragged) { + this.aim() + } else if (!this.pick(upEvent, true)) { + return + } + + if (this.view === 'hour') { + this.moveOn = setTimeout(() => this.choose('minute'), dragged ? 0 : MOVE_ON_MS) + } + } + + const abandon = (cancelEvent) => release(cancelEvent, true) + + dial.addEventListener('pointermove', move) + dial.addEventListener('pointerup', release) + dial.addEventListener('pointercancel', abandon) + }, + + /** + * The value under the pointer. A tap turns the selector to the value it chose; a drag keeps the + * handle under the pointer (rotateTo without animation) until it is released. + */ + pick(event, tap) { + const box = this.$refs.dial.getBoundingClientRect() + const x = event.clientX - (box.left + box.width / 2) + const y = event.clientY - (box.top + box.height / 2) + const degrees = ((Math.atan2(x, -y) * 180) / Math.PI + 360) % 360 + + if (this.view === 'hour') { + let hour = Math.round(degrees / 30) % 12 + + if (this.is24 ? Math.hypot(x, y) < (INNER_REACH * box.width) / DIAL : this.isPm) { + hour += 12 + } + + // A tap on a number outside the limits does nothing; a drag settles on the nearest allowed. + hour = this.hourAllowed(hour) ? hour : tap ? null : this.nearestHour(hour) + + if (hour === null) { + return false + } + + this.setHour(hour) + } else { + const unit = tap && 5 % this.step === 0 ? 5 : this.step + let minute = (Math.round(degrees / 6 / unit) * unit) % 60 + + minute = this.minuteAllowed(minute) ? minute : tap ? null : this.nearestMinute(minute) + + if (minute === null) { + return false + } + + this.minute = minute + } + + this.aim(tap ? this.angleFor() : degrees) + + return true + }, + + key(event) { + const moves = { ArrowUp: 1, ArrowRight: 1, ArrowDown: -1, ArrowLeft: -1 } + + if (event.key === 'Enter') { + event.preventDefault() + this.confirm() + } else if (event.key in moves) { + event.preventDefault() + this.nudge(moves[event.key]) + } else if (event.key === 'Home' || event.key === 'End') { + event.preventDefault() + this.extreme(event.key === 'End') + } + }, + + nudge(direction) { + clearTimeout(this.moveOn) + + if (this.view === 'hour') { + for (let offset = 1; offset <= 24; offset++) { + const hour = (((this.hour + direction * offset) % 24) + 24) % 24 + + if (this.hourAllowed(hour)) { + this.setHour(hour) + break + } + } + } else { + const aligned = Math.round(this.minute / this.step) * this.step + + for (let offset = aligned === this.minute ? 1 : 0; offset <= 60; offset++) { + const minute = (((aligned + direction * offset * this.step) % 60) + 60) % 60 + + if (this.minuteAllowed(minute)) { + this.minute = minute + break + } + } + } + + this.aim() + }, + + extreme(last) { + const values = this.view === 'hour' + ? [...Array(24).keys()].filter((hour) => this.hourAllowed(hour)) + : [...Array(60).keys()].filter((minute) => this.minuteAllowed(minute)) + + if (values.length === 0) { + return + } + + if (this.view === 'hour') { + this.setHour(last ? values.at(-1) : values[0]) + } else { + this.minute = last ? values.at(-1) : values[0] + } + + this.aim() + }, + + // ---- The text fields ------------------------------------------------------------------- + + fillText() { + this.hourText = this.hourLabel + this.minuteText = this.minuteLabel + }, + + get hourTextValid() { + const number = Number(this.hourText) + + return /^\d{1,2}$/.test(this.hourText) && (this.is24 ? number <= 23 : number >= 1 && number <= 12) + }, + + get minuteTextValid() { + return /^\d{1,2}$/.test(this.minuteText) && Number(this.minuteText) <= 59 + }, + + get minuteTextOnStep() { + return !this.minuteTextValid || Number(this.minuteText) % this.step === 0 + }, + + get hourError() { + if (this.hourTextValid || (this.hourText === '' && !this.attempted)) { + return null + } + + return keepRange(this.is24 ? config.strings.hourError24 : config.strings.hourError12) + }, + + get minuteError() { + if (this.minuteText === '' && !this.attempted) { + return null + } + + if (!this.minuteTextValid) { + return keepRange(config.strings.minuteError) + } + + return this.minuteTextOnStep ? null : config.strings.stepError.replace(':step', this.step) + }, + + get rangeError() { + if (this.earliest === null && this.latest === null) { + return null + } + + if (this.mode !== 'input' || !this.hourTextValid || !this.minuteTextValid || this.inRange(this.hour * 60 + this.minute)) { + return null + } + + const strings = config.strings + + if (this.earliest !== null && this.latest !== null) { + return strings.between.replace(':min', this.format(this.earliest)).replace(':max', this.format(this.latest)) + } + + return this.earliest !== null ? strings.after.replace(':min', this.format(this.earliest)) : strings.before.replace(':max', this.format(this.latest)) + }, + + typeHour(event) { + const text = event.target.value.replace(/\D/g, '').slice(0, 2) + + event.target.value = text + this.hourText = text + + if (this.hourTextValid) { + const number = Number(text) + + this.hour = this.is24 ? number : (number % 12) + (this.isPm ? 12 : 0) + } + + // shouldSwitchFocusToMinute: two valid digits typed at the end move on to the minute. + if (event.inputType?.startsWith('insert') && text.length === 2 && this.hourTextValid && event.target.selectionStart === 2) { + this.view = 'minute' + this.$refs.minuteInput.focus() + this.$refs.minuteInput.select() + } + }, + + typeMinute(event) { + const text = event.target.value.replace(/\D/g, '').slice(0, 2) + + event.target.value = text + this.minuteText = text + + if (this.minuteTextValid) { + this.minute = Number(text) + } + }, + + /** Reads both fields for OK; on an error, says so and puts focus on the field to fix. */ + readText() { + this.attempted = true + + const invalid = !this.hourTextValid + ? this.$refs.hourInput + : !this.minuteTextValid || !this.minuteTextOnStep + ? this.$refs.minuteInput + : !this.inRange(this.hour * 60 + this.minute) + ? this.$refs.hourInput + : null + + if (invalid) { + invalid.focus() + invalid.select() + + return false + } + + return true + }, + })) +}) diff --git a/resources/views/components/timepicker.blade.php b/resources/views/components/timepicker.blade.php new file mode 100644 index 00000000..ce411127 --- /dev/null +++ b/resources/views/components/timepicker.blade.php @@ -0,0 +1,362 @@ +{{-- A time: M3's time picker, opened from a text field. + + + + + The field is read-only and opens the picker in a modal `` on a press, Enter, Space or + ArrowDown (the clock icon at its end opens it too). The picker is M3's dial: the hour and minute + boxes on top, AM and PM beside them on a 12-hour clock, the clock face below. A press or a drag + on the dial picks the hour, then it moves on to the minutes; the arrow keys change the value on + the focused dial, Home and End go to the ends, Enter confirms, and Escape, Cancel or a press on + the scrim close it without a change, handing focus back to the field. The keyboard icon swaps + the dial for M3's input variant: two text fields, with the error under a field that holds + something impossible. In a landscape window the dial lies on its side, as Compose lays it out. + + `wire:model` (or `x-model`) holds the time as `H:i`, and null until one is chosen; a value with + seconds (`09:30:00`, from a `time` column) is read, and written back as `H:i`. Nothing is written + until OK. The draft starts at the bound time, or now. Errors are read from the bag under the + `wire:model` name and replace the hint. + + `format` is `12` or `24`; without it the hour cycle is the locale's (`locale`, the app locale by + default) as `Intl.DateTimeFormat` reports it, and the field shows the time as the locale writes + it. `step` is the minute step (a tap on the minute dial picks fives, or steps when five is not a + multiple of the step; a drag and the arrows move by the step). `min` and `max` (`H:i`, inclusive; + a `min` later than `max` spans midnight) grey out and skip what lies outside them and turn typed + values outside them into errors — validate on the server as well. `clearable` adds a button that + empties the field; `name` posts the value from a hidden input. `label`, `hint`, `icon`, `variant` + and `size` are the field's; other attributes (`required`, `disabled`, `placeholder`) reach the + field's input. + + From androidx Compose Material 3 at commit 27cf9a7d5788aa0f5f2d8b6699ce279560daf326 (Apache-2.0): + TimePickerTokens and TimeInputTokens — a surface-container-high dialog with an extra-large + corner and elevation 3, a 256dp surface-container-highest dial with body-large numbers, a primary + selector with a 48dp handle, a 2dp line and an 8dp centre, 96×80 time selector boxes in + display-large (primary-container when selected), 96×72 time fields in display-medium — and + TimePicker.kt and TimePickerDialog.kt for the layout, the 24-hour inner ring (12–23, at 69dp; + 00–11 outside at 101dp, as Material Components for Android labels them too), the gestures, the + move on to minutes and the error texts. The period selector is Compose's current default + (`isUpdatedTimepickerToggleEnabled`): two separate shape-morphing toggle buttons in + primary-container, not the outlined pair its tokens still describe. The dial's numbers are + aria-hidden; the dial is a `slider` whose value text names the hour or minute. The dialog is + `wire:ignore`, so a Livewire render never closes an open picker or resets its draft. --}} + +@props([ + 'label' => null, + 'hint' => null, + 'icon' => null, + 'variant' => null, + 'size' => 'md', + 'format' => null, + 'locale' => null, + 'min' => null, + 'max' => null, + 'step' => 1, + 'value' => null, + 'name' => null, + 'clearable' => false, +]) + +@php + $model = $attributes->wire('model')->value() ?: null; + $messages = $model !== null && isset($errors) ? \Illuminate\Support\Arr::flatten($errors->get($model)) : []; + $id = $attributes->get('id') ?? 'timepicker-'.substr(md5($model.'|'.$label.'|'.$name.'|timepicker'), 0, 12); + + $cycle = in_array((string) $format, ['12', '24'], true) ? (int) $format : null; + $locale = str_replace('_', '-', filled($locale) ? $locale : app()->getLocale()); + $interval = is_numeric($step) && (int) $step >= 1 && (int) $step <= 60 ? (int) $step : 1; + $clock = fn (mixed $time): ?string => is_string($time) && preg_match('/^([01]?\d|2[0-3]):([0-5]\d)/', $time, $parts) === 1 + ? sprintf('%02d:%02d', $parts[1], $parts[2]) + : null; + $earliest = $clock($min); + $latest = $clock($max); + + // Rendered as the bound property already says, so the field is not empty until Alpine starts. + $current = $value; + if ($model !== null && ($component = \Livewire\Livewire::current()) !== null) { + $current = data_get($component, $model); + } + $current = $clock($current); + + // The first frame writes the time as the browser will; ICU decides the hour cycle on both sides. + $display = ''; + if ($current !== null) { + $time = \Carbon\CarbonImmutable::createFromFormat('!H:i', $current, 'UTC'); + $shown = $cycle; + + if (class_exists(\IntlDatePatternGenerator::class)) { + $generator = new \IntlDatePatternGenerator(str_replace('-', '_', $locale)); + $shown ??= preg_match('/[hK]/', preg_replace("/'[^']*'/", '', (string) $generator->getBestPattern('j'))) === 1 ? 12 : 24; + $pattern = $generator->getBestPattern($shown === 12 ? 'hmm' : 'Hmm'); + $display = (string) (new \IntlDateFormatter(str_replace('-', '_', $locale), \IntlDateFormatter::NONE, \IntlDateFormatter::NONE, 'UTC', null, $pattern))->format($time); + } else { + $display = $shown === 12 ? $time->format('g:i A') : $time->format('H:i'); + } + } + + $config = [ + 'locale' => $locale, + 'format' => $cycle, + 'min' => $earliest, + 'max' => $latest, + 'step' => $interval, + 'strings' => [ + 'am' => __('AM'), + 'pm' => __('PM'), + 'oclock' => __(':hour o\'clock'), + 'hours' => __(':hour hours'), + 'minutes' => __(':minute minutes'), + 'hourError12' => __('Hour must be 1–12'), + 'hourError24' => __('Hour must be 0–23'), + 'minuteError' => __('Minute must be 0–59'), + 'stepError' => __('Minute must be a multiple of :step'), + 'between' => __('Choose a time from :min to :max'), + 'after' => __('Choose :min or later'), + 'before' => __('Choose :max or earlier'), + ], + ]; + + $constrained = $earliest !== null || $latest !== null || $interval > 1; + + // The dial's numbers, placed round the ring from twelve o'clock (TimePicker.kt's CircularLayout). + $spot = fn (int $index): string => sprintf('--x: %.4F; --y: %.4F', sin(deg2rad($index * 30)), -cos(deg2rad($index * 30))); + $sets = [ + 'hour12' => array_map(fn (int $index): array => ['value' => $index ?: 12, 'text' => $index ?: 12, 'index' => $index, 'inner' => false, 'allowed' => "hourAllowed({$index} + (isPm ? 12 : 0))"], range(0, 11)), + 'hour24' => [ + ...array_map(fn (int $index): array => ['value' => $index, 'text' => $index === 0 ? '00' : $index, 'index' => $index, 'inner' => false, 'allowed' => "hourAllowed({$index})"], range(0, 11)), + ...array_map(fn (int $index): array => ['value' => $index + 12, 'text' => $index + 12, 'index' => $index, 'inner' => true, 'allowed' => 'hourAllowed('.($index + 12).')'], range(0, 11)), + ], + 'minute' => array_map(fn (int $index): array => ['value' => $index * 5, 'text' => $index === 0 ? '00' : $index * 5, 'index' => $index, 'inner' => false, 'allowed' => 'minuteAllowed('.($index * 5).')'], range(0, 11)), + ]; + + $inputAttributes = $attributes->whereDoesntStartWith(['wire:model', 'x-model'])->except(['class', 'id', 'wire:key', 'placeholder']); + $disabled = (bool) $attributes->get('disabled'); + $described = $messages !== [] || filled($hint); +@endphp + +
only(['class', 'wire:key', 'x-model']) }} + x-data="materialTimepicker(@if ($model !== null) @entangle($attributes->wire('model')) @else @js($current) @endif, @js($config))" + @if ($model === null) x-modelable="value" @endif +> + + + + + @if ($clearable) + + @endif + + + + + + @if (filled($name)) + + @endif + + +
+

{{ __('Select time') }}

+ +
+
+
+ + + +
+ +
+ @foreach ([false => 'am', true => 'pm'] as $pm => $period) + + @endforeach +
+
+ +
+ @foreach (['labels', 'ink'] as $layer) + @if ($layer === 'ink') + + @endif + + + @endforeach +
+
+ +
+
+ @foreach (['hour' => __('Hour'), 'minute' => __('Minute')] as $part => $partLabel) + @if ($part === 'minute') + + @endif + +
+ +

{{ $partLabel }}

+
+ @endforeach + +
+ @foreach ([false => 'am', true => 'pm'] as $pm => $period) + + @endforeach +
+
+ +

+
+ +
+ + + + + + + + + +
+
+ +
diff --git a/resources/views/showcase/index.blade.php b/resources/views/showcase/index.blade.php index 1ec61d2b..8853ccfb 100644 --- a/resources/views/showcase/index.blade.php +++ b/resources/views/showcase/index.blade.php @@ -21,6 +21,7 @@ @include('livewire-material::showcase.sections.fields') @include('livewire-material::showcase.sections.chips') @include('livewire-material::showcase.sections.sliders') + @include('livewire-material::showcase.sections.timepickers') @include('livewire-material::showcase.sections.bars') @include('livewire-material::showcase.sections.data') diff --git a/resources/views/showcase/layout.blade.php b/resources/views/showcase/layout.blade.php index 45d5ab3f..fb77bd73 100644 --- a/resources/views/showcase/layout.blade.php +++ b/resources/views/showcase/layout.blade.php @@ -18,7 +18,7 @@ Livewire Material diff --git a/resources/views/showcase/sections/timepickers.blade.php b/resources/views/showcase/sections/timepickers.blade.php new file mode 100644 index 00000000..4a780e99 --- /dev/null +++ b/resources/views/showcase/sections/timepickers.blade.php @@ -0,0 +1,44 @@ +@php + $examples = [ + 'Time pickers: 12 and 24 hours, outlined and filled' => <<<'BLADE' +
+
+ + + +
+ +
+ + + +
+
+ BLADE, + 'Time pickers: steps and limits' => <<<'BLADE' +
+
+ + +
+ +
+ +

Stored as

+
+
+ BLADE, + ]; +@endphp + +
+

Time pickers

+ +

+ <x-timepicker> — M3's dial and input time picker in a modal dialog, opened from a text field. +

+ + @foreach ($examples as $title => $code) + + @endforeach +
diff --git a/tests/Browser/TimepickerTest.php b/tests/Browser/TimepickerTest.php new file mode 100644 index 00000000..97c8c2cd --- /dev/null +++ b/tests/Browser/TimepickerTest.php @@ -0,0 +1,339 @@ +renders++; + } + + public function render(): string + { + return <<<'BLADE' +
+

meeting: {{ $meeting ?? 'null' }}

+

alarm: {{ $alarm ?? 'null' }}

+

appointment: {{ $appointment ?? 'null' }}

+

renders: {{ $renders }}

+ + + + +
+ BLADE; + } +} + +function timeProbe() +{ + Livewire::component('time-probe', TimeProbe::class); + + Route::middleware('web')->get('/time-probe', fn () => Blade::render(<<<'BLADE' + + + + + @vite(config('livewire-material.showcase.vite')) + @livewireStyles + + + + @livewireScripts + + + BLADE)); + + return visit('/time-probe')->waitForEvent('networkidle') + ->assertScript("document.readyState === 'complete' && typeof window.Alpine !== 'undefined' && typeof window.Livewire !== 'undefined'"); +} + +/** A JavaScript expression for an element inside the named picker's dialog. */ +function inPicker(string $id, string $selector): string +{ + return "document.querySelector('#{$id}-dialog {$selector}')"; +} + +/** A JavaScript expression for the text under a time field, without its word joiners. */ +function supportText(string $id): string +{ + return "document.querySelector('#{$id}-support').textContent.replaceAll('\\u2060', '')"; +} + +it('opens the dial on the hour, as the bound time says', function () { + timeProbe() + ->assertValue('#meeting', '9:30 AM') + ->click('#meeting') + ->assertScript("document.querySelector('#meeting-dialog').open") + ->assertAttribute('#meeting', 'aria-expanded', 'true') + ->assertSeeIn('#meeting-title', 'Select time') + ->assertAttribute('#meeting-dialog [data-timepicker-box="hour"]', 'aria-pressed', 'true') + ->assertSeeIn('#meeting-dialog [data-timepicker-box="hour"]', '09') + ->assertSeeIn('#meeting-dialog [data-timepicker-box="minute"]', '30') + ->assertAttribute('#meeting-dialog [data-timepicker-display] [data-timepicker-period-option="am"]', 'aria-pressed', 'true') + ->assertAttribute('#meeting-dialog [data-timepicker-dial]', 'aria-valuenow', '9') + ->assertScript('document.activeElement === '.inPicker('meeting', '[data-timepicker-dial]')); +}); + +it('writes the hour and the minute pressed on the dial to Livewire on OK', function () { + $dial = inPicker('meeting', '[data-timepicker-dial]'); + + $page = timeProbe() + ->click('#meeting') + ->click('#meeting-dialog [data-timepicker-label="hour12"][data-value="3"]') + ->assertSeeIn('#meeting-dialog [data-timepicker-box="hour"]', '03') + ->assertAttribute('#meeting-dialog [data-timepicker-dial]', 'data-view', 'minute') + ->assertAttribute('#meeting-dialog [data-timepicker-box="minute"]', 'aria-pressed', 'true') + // The selector turns to the value it chose: the handle ends over the number. + ->assertScript(<< { + const handle = {$dial}.querySelector('[data-timepicker-handle]').getBoundingClientRect(); + const label = {$dial}.querySelector('[data-timepicker-label="minute"][data-value="30"]').getBoundingClientRect(); + + return Math.abs(handle.x - label.x) < 1 && Math.abs(handle.y - label.y) < 1; + })() + JS); + + $page->click('#meeting-dialog [data-timepicker-label="minute"][data-value="45"]') + ->assertSeeIn('#meeting-dialog [data-timepicker-box="minute"]', '45') + ->assertSeeIn('#meeting-value', '09:30') + ->click('#meeting-dialog [data-timepicker-confirm]') + ->assertSeeIn('#meeting-value', '03:45') + ->assertValue('#meeting', '3:45 AM') + ->assertScript("! document.querySelector('#meeting-dialog').open") + ->assertAttribute('#meeting', 'aria-expanded', 'false'); +}); + +it('leaves the time alone when the picker is cancelled', function () { + timeProbe() + ->click('#meeting') + ->click('#meeting-dialog [data-timepicker-label="hour12"][data-value="7"]') + ->assertSeeIn('#meeting-dialog [data-timepicker-box="hour"]', '07') + ->click('#meeting-dialog [data-timepicker-cancel]') + ->assertScript("! document.querySelector('#meeting-dialog').open") + ->assertSeeIn('#meeting-value', '09:30') + ->assertValue('#meeting', '9:30 AM'); +}); + +it('turns three o\'clock into 15 with PM', function () { + timeProbe() + ->click('#meeting') + ->click('#meeting-dialog [data-timepicker-display] [data-timepicker-period-option="pm"]') + ->assertAttribute('#meeting-dialog [data-timepicker-display] [data-timepicker-period-option="pm"]', 'aria-pressed', 'true') + ->click('#meeting-dialog [data-timepicker-label="hour12"][data-value="3"]') + ->click('#meeting-dialog [data-timepicker-label="minute"][data-value="15"]') + ->click('#meeting-dialog [data-timepicker-confirm]') + ->assertSeeIn('#meeting-value', '15:15') + ->assertValue('#meeting', '3:15 PM'); +}); + +it('draws a German dial with 24 hours, 12 to 23 on the inner ring', function () { + $dial = inPicker('alarm', '[data-timepicker-dial]'); + $radius = fn (string $value): string => << { + const dial = {$dial}.getBoundingClientRect(); + const label = {$dial}.querySelector('[data-timepicker-label="hour24"][data-value="{$value}"]').getBoundingClientRect(); + + return Math.round(Math.hypot(label.x + label.width / 2 - dial.x - dial.width / 2, label.y + label.height / 2 - dial.y - dial.height / 2)); + })() + JS; + + $page = timeProbe() + ->click('#alarm') + ->assertAttribute('#alarm-dialog [data-timepicker-dial]', 'data-cycle', '24') + ->assertScript("getComputedStyle(document.querySelector('#alarm-dialog [data-timepicker-period]')).display === 'none'") + ->assertScript("{$dial}.querySelector('[data-timepicker-label=\"hour24\"][data-value=\"0\"]').textContent.trim() === '00'") + ->assertScript($radius('0').' === 101') + ->assertScript($radius('11').' === 101') + ->assertScript($radius('12').' === 69') + ->assertScript($radius('13').' === 69') + ->assertScript($radius('23').' === 69'); + + $page->click('#alarm-dialog [data-timepicker-label="hour24"][data-value="15"]') + ->assertSeeIn('#alarm-dialog [data-timepicker-box="hour"]', '15') + ->assertAttribute('#alarm-dialog [data-timepicker-dial]', 'data-view', 'minute') + ->click('#alarm-dialog [data-timepicker-label="minute"][data-value="0"]') + ->click('#alarm-dialog [data-timepicker-confirm]') + ->assertSeeIn('#alarm-value', '15:00') + ->assertValue('#alarm', '15:00'); + + // The outer ring is the morning. + $page->click('#alarm') + ->click('#alarm-dialog [data-timepicker-label="hour24"][data-value="3"]') + ->assertSeeIn('#alarm-dialog [data-timepicker-box="hour"]', '03') + ->click('#alarm-dialog [data-timepicker-label="minute"][data-value="0"]') + ->click('#alarm-dialog [data-timepicker-confirm]') + ->assertSeeIn('#alarm-value', '03:00'); +}); + +it('follows a drag round the dial and settles on the nearest hour', function () { + $dial = inPicker('meeting', '[data-timepicker-dial]'); + + $page = timeProbe()->click('#meeting'); + + // Pointer events built in the page's own realm, from twelve o'clock round to just past four. + $send = fn (string $type, int $degrees): string => << { + const dial = document.querySelector('#meeting-dialog [data-timepicker-dial]'); + const box = dial.getBoundingClientRect(); + const radians = {$degrees} * Math.PI / 180; + + dial.dispatchEvent(new PointerEvent('{$type}', { + bubbles: true, cancelable: true, pointerId: 1, isPrimary: true, button: 0, buttons: 1, + clientX: box.x + box.width / 2 + Math.sin(radians) * 90, + clientY: box.y + box.height / 2 - Math.cos(radians) * 90, + })); + })()`) + JS; + + $page->script($send('pointerdown', 0).';'.$send('pointermove', 20).';'.$send('pointermove', 60).';'.$send('pointermove', 125)); + + // While dragging, the handle stays under the pointer rather than on a number. + $page->assertScript("{$dial}.hasAttribute('data-dragging') && parseFloat(getComputedStyle({$dial}).getPropertyValue('--timepicker-angle')) % 360 === 125") + ->assertSeeIn('#meeting-dialog [data-timepicker-box="hour"]', '04'); + + $page->script($send('pointerup', 125)); + + $page->assertScript("! {$dial}.hasAttribute('data-dragging')") + ->assertAttribute('#meeting-dialog [data-timepicker-dial]', 'data-view', 'minute') + ->assertSeeIn('#meeting-dialog [data-timepicker-box="hour"]', '04'); +}); + +it('changes the focused hour and minute with the arrow keys and confirms with Enter', function () { + $page = timeProbe(); + + $page->script("document.querySelector('#meeting').focus()"); + + $page->keys('#meeting', 'Enter') + ->assertScript('document.activeElement === '.inPicker('meeting', '[data-timepicker-dial]')) + ->keys(':focus', 'ArrowUp') + ->assertAttribute('#meeting-dialog [data-timepicker-dial]', 'aria-valuenow', '10') + ->assertSeeIn('#meeting-dialog [data-timepicker-box="hour"]', '10') + // The keyboard never moves on to the minutes by itself. + ->assertAttribute('#meeting-dialog [data-timepicker-dial]', 'data-view', 'hour'); + + $page->script(inPicker('meeting', '[data-timepicker-box="minute"]').'.focus()'); + + $page->keys(':focus', 'Enter') + ->assertAttribute('#meeting-dialog [data-timepicker-dial]', 'data-view', 'minute'); + + $page->script(inPicker('meeting', '[data-timepicker-dial]').'.focus()'); + + $page->keys(':focus', ['ArrowDown', 'ArrowLeft']) + ->assertAttribute('#meeting-dialog [data-timepicker-dial]', 'aria-valuenow', '28') + ->assertAttribute('#meeting-dialog [data-timepicker-dial]', 'aria-valuetext', '28 minutes') + ->keys(':focus', 'Enter') + ->assertScript("! document.querySelector('#meeting-dialog').open") + ->assertSeeIn('#meeting-value', '10:28'); +}); + +it('takes a typed time in the input variant and says what is wrong with it', function () { + $page = timeProbe() + ->click('#meeting') + ->click('#meeting-dialog [data-timepicker-mode="input"]') + ->assertSeeIn('#meeting-title', 'Enter time') + ->assertScript("document.activeElement.id === 'meeting-hour'") + ->assertValue('#meeting-hour', '09') + ->assertValue('#meeting-minute', '30'); + + $page->type('#meeting-hour', '13') + ->assertAttribute('#meeting-hour', 'aria-invalid', 'true') + // Word joiners keep the range on one line in the narrow column. + ->assertScript(supportText('meeting-hour')." === 'Hour must be 1–12'") + ->click('#meeting-dialog [data-timepicker-confirm]') + ->assertScript("document.querySelector('#meeting-dialog').open") + ->assertSeeIn('#meeting-value', '09:30'); + + $page->clear('#meeting-hour') + ->typeSlowly('#meeting-hour', '11', 20) + ->assertScript("document.activeElement.id === 'meeting-minute'") + ->assertScript(supportText('meeting-hour')." === 'Hour'") + ->assertScript("! document.querySelector('#meeting-hour').hasAttribute('aria-invalid')"); + + $page->clear('#meeting-minute') + ->typeSlowly('#meeting-minute', '75', 20) + ->assertScript(supportText('meeting-minute')." === 'Minute must be 0–59'") + ->clear('#meeting-minute') + ->typeSlowly('#meeting-minute', '05', 20) + ->keys('#meeting-minute', 'Enter') + ->assertScript("! document.querySelector('#meeting-dialog').open") + ->assertSeeIn('#meeting-value', '11:05'); +}); + +it('keeps to the step and the limits', function () { + $dial = inPicker('slot', '[data-timepicker-dial]'); + + $page = timeProbe() + ->click('#slot') + ->assertScript("{$dial}.querySelector('[data-timepicker-label=\"hour24\"][data-value=\"8\"]').hasAttribute('data-disabled')") + ->assertScript("! {$dial}.querySelector('[data-timepicker-label=\"hour24\"][data-value=\"9\"]').hasAttribute('data-disabled')") + ->assertScript("{$dial}.querySelector('[data-timepicker-label=\"hour24\"][data-value=\"18\"]').hasAttribute('data-disabled')") + // An hour outside the limits is not taken. + ->click('#slot-dialog [data-timepicker-label="hour24"][data-value="20"]') + ->assertSeeIn('#slot-dialog [data-timepicker-box="hour"]', '10') + ->click('#slot-dialog [data-timepicker-label="hour24"][data-value="16"]') + ->assertAttribute('#slot-dialog [data-timepicker-dial]', 'data-view', 'minute') + ->assertScript("{$dial}.querySelector('[data-timepicker-label=\"minute\"][data-value=\"20\"]').hasAttribute('data-disabled')") + // A press between the steps lands on the nearest one. + ->click('#slot-dialog [data-timepicker-label="minute"][data-value="20"]') + ->assertSeeIn('#slot-dialog [data-timepicker-box="minute"]', '15'); + + $page->script("{$dial}.focus()"); + + $page->keys(':focus', 'ArrowUp') + ->assertAttribute('#slot-dialog [data-timepicker-dial]', 'aria-valuenow', '30') + ->click('#slot-dialog [data-timepicker-mode="input"]') + ->type('#slot-hour', '18') + ->assertSeeIn('#slot-dialog [data-timepicker-range-error]', 'Choose a time from 09:00 to 17:00') + ->type('#slot-hour', '16') + ->type('#slot-minute', '20') + ->assertSeeIn('#slot-minute-support', 'Minute must be a multiple of 15') + ->click('#slot-dialog [data-timepicker-confirm]') + ->assertScript("document.activeElement.id === 'slot-minute'") + ->type('#slot-minute', '45') + ->click('#slot-dialog [data-timepicker-confirm]') + ->assertSeeIn('#slot-value', '16:45'); +}); + +it('gives focus back to the field on Escape', function () { + $page = timeProbe(); + + $page->script("document.querySelector('#meeting').focus()"); + + $page->keys('#meeting', 'Enter') + ->assertScript("document.querySelector('#meeting-dialog').open") + ->keys(':focus', 'ArrowUp') + ->keys(':focus', 'Escape') + ->assertScript("! document.querySelector('#meeting-dialog').open") + ->assertScript("document.activeElement.id === 'meeting'") + ->assertSeeIn('#meeting-value', '09:30'); +}); + +it('stays open with its draft through a Livewire render', function () { + $page = timeProbe() + ->click('#meeting') + ->click('#meeting-dialog [data-timepicker-label="hour12"][data-value="5"]') + ->assertAttribute('#meeting-dialog [data-timepicker-dial]', 'data-view', 'minute'); + + $page->script('window.eval("Livewire.first().touch()")'); + + $page->assertSeeIn('#renders', '1') + ->assertScript("document.querySelector('#meeting-dialog').open") + ->assertSeeIn('#meeting-dialog [data-timepicker-box="hour"]', '05') + ->assertAttribute('#meeting-dialog [data-timepicker-dial]', 'data-view', 'minute') + ->click('#meeting-dialog [data-timepicker-label="minute"][data-value="10"]') + ->click('#meeting-dialog [data-timepicker-confirm]') + ->assertSeeIn('#meeting-value', '05:10'); +}); diff --git a/tests/Feature/Components/TimepickerTest.php b/tests/Feature/Components/TimepickerTest.php new file mode 100644 index 00000000..e80ba630 --- /dev/null +++ b/tests/Feature/Components/TimepickerTest.php @@ -0,0 +1,171 @@ + + */ +function timepickerConfig(string $html): array +{ + preg_match('/materialTimepicker\((.*?), JSON\.parse\(\'(.*?)\'\)\)"/s', $html, $matches); + + return json_decode((string) json_decode('"'.($matches[2] ?? '{}').'"'), true) ?? []; +} + +it('draws a read-only field that opens the picker in a labelled dialog', function () { + $html = (string) $this->blade(''); + + expect($html) + ->toContain('') + ->toMatch('/]*id="starts"[^>]*readonly/s') + ->toContain('value="14:30"') + ->toContain('aria-haspopup="dialog"') + ->toContain('aria-controls="starts-dialog"') + ->toContain('aria-expanded="false"') + ->toContain('aria-describedby="starts-support"') + ->toContain('

In your time zone

') + ->toContain('x-on:keydown.enter.prevent="show()"') + ->toContain('data-timepicker-open') + ->toContain('aria-label="Choose time"') + ->toContain('toContain('id="starts-dialog"') + ->toContain('wire:ignore') + ->toContain('aria-labelledby="starts-title"') + ->toContain('

toContain('x-modelable="value"') + ->toContain("materialTimepicker( '14:30' ,") + ->not->toContain('aria-invalid="true"') + ->not->toContain('data-invalid'); +}); + +it('draws the dial as a slider, with twelve numbers per ring and M3\'s 24-hour inner ring', function () { + $html = (string) $this->blade(''); + + expect($html) + ->toContain('role="slider"') + ->toContain('x-bind:aria-valuetext="valueText"') + ->and(substr_count($html, 'data-timepicker-label="hour12"'))->toBe(12) + ->and(substr_count($html, 'data-timepicker-label="hour24"'))->toBe(24) + ->and(substr_count($html, 'data-timepicker-label="minute"'))->toBe(12) + ->and($html) + ->toMatch('/data-timepicker-label="hour24" data-value="0"\s+style="--x: 0\.0000; --y: -1\.0000"\s*>00toMatch('/data-timepicker-label="hour24" data-value="12"\s+data-inner\s+style="--x: 0\.0000; --y: -1\.0000"\s*>12toMatch('/data-timepicker-label="hour24" data-value="15"\s+data-inner\s+style="--x: 1\.0000; --y: -0\.0000"\s*>15toMatch('/data-timepicker-label="minute" data-value="0"\s+style="[^"]*"\s*>00toMatch('/data-timepicker-label="hour12" data-value="12"\s+style="--x: 0\.0000; --y: -1\.0000"\s*>12toContain('data-timepicker-handle') + ->toContain('data-timepicker-ink') + ->not->toContain('x-bind:data-disabled'); +}); + +it('offers the input variant, the period selector and the actions', function () { + $html = (string) $this->blade(''); + + expect($html) + ->toContain('id="pickup-hour"') + ->toContain('id="pickup-minute"') + ->toContain('inputmode="numeric"') + ->toContain('aria-describedby="pickup-hour-support"') + ->toContain('aria-describedby="pickup-minute-support"') + ->toContain('data-timepicker-period-option="am"') + ->toContain('data-timepicker-period-option="pm"') + ->toContain('aria-label="Select AM or PM"') + ->toContain('aria-label="Switch to text input mode"') + ->toContain('aria-label="Switch to clock mode"') + ->toContain('data-timepicker-cancel') + ->toContain('data-timepicker-confirm') + ->toContain('>Cancel') + ->toContain('>OK'); +}); + +it('passes the format, locale, limits and step to the picker, and drops what it cannot use', function () { + app()->setLocale('de_CH'); + + $config = timepickerConfig((string) $this->blade('')); + + expect($config)->toMatchArray(['locale' => 'de-CH', 'format' => 12, 'min' => '08:00', 'max' => '17:30', 'step' => 15]) + ->and($config['strings'])->toHaveKeys(['hourError12', 'hourError24', 'minuteError', 'stepError', 'between']); + + $fallback = timepickerConfig((string) $this->blade('')); + + expect($fallback)->toMatchArray(['locale' => 'en-GB', 'format' => null, 'min' => null, 'max' => null, 'step' => 1]); +}); + +it('marks what lies outside the limits only when there are limits', function () { + $html = (string) $this->blade(''); + + expect($html) + ->toContain('x-bind:data-disabled="hourAllowed(3 + (isPm ? 12 : 0)) ? null : \'\'"') + ->toContain('x-bind:data-disabled="minuteAllowed(45) ? null : \'\'"'); +}); + +it('writes the first frame as the locale writes the time', function () { + expect((string) $this->blade(''))->toMatch('/value="2:05[\s\x{202F}]PM"/u') + ->and((string) $this->blade(''))->toContain('value="09:05"') + ->and((string) $this->blade(''))->toContain('value="21:40"') + ->and((string) $this->blade(''))->toMatch('/value="9:40[\s\x{202F}]PM"/u') + ->and((string) $this->blade(''))->toMatch('/]*value=""[^>]*x-bind:value="display"/s'); +}); + +it('entangles the time with its Livewire property and shows it before Alpine starts', function () { + Livewire::component('timepicker-probe', new class extends Component + { + public ?string $startsAt = '18:45:00'; + + public function render(): string + { + return '
'; + } + }); + + $html = Livewire::test('timepicker-probe')->html(); + + expect($html) + ->toContain(".entangle('startsAt').live") + ->toContain('value="18:45"') + ->not->toContain('x-modelable') + ->not->toContain('wire:model.live="startsAt"'); +}); + +it('shows the errors for its property in place of the hint', function () { + Livewire::component('timepicker-errors', new class extends Component + { + public ?string $startsAt = null; + + public function mount(): void + { + $this->addError('startsAt', 'Choose a time during opening hours.'); + } + + public function render(): string + { + return '
'; + } + }); + + expect(Livewire::test('timepicker-errors')->html()) + ->toContain('data-invalid') + ->toContain('aria-invalid="true"') + ->toContain('aria-describedby="starts-support"') + ->toContain('Choose a time during opening hours.') + ->not->toContain('Opening hours only'); +}); + +it('puts the field props on the field, its attributes on the input, and posts a name', function () { + $html = (string) $this->blade(''); + + expect($html) + ->toMatch('/^toContain('data-variant="filled"') + ->toContain('data-size="sm"') + ->toContain('data-timepicker-field') + ->toContain('required') + ->toContain('placeholder="hh:mm"') + ->toContain('') + ->toContain('data-field-clear') + ->toMatch('/]*data-timepicker-open[^>]*disabled/s') + ->and(substr_count($html, 'class="field w-60"'))->toBe(0); +});