@giraffesyo/timeclock 0.3.0 → 0.4.0

package/README.md

@@ -48,7 +48,7 @@ function HeaderClock() {
 }
 ```
 
-`useClock()` gives the state (`status`, `running`, `projects`, `requireProject`, `locked`, `timeZone`, `busy`), what is being typed (`note`, `setNote`, `projectId`), and what can be done (`start`, `stop`, `chooseProject`, `saveNote`, `resume`). Everything that changes the clock returns a promise that rejects with a `ClockError` when Timeclock refuses.
+`useClock()` gives the state (`status`, `running`, `projects`, `requireProject`, `requireDescription`, `locked`, `timeZone`, `busy`), what is being typed (`note`, `setNote`, `projectId`), and what can be done (`start`, `stop`, `chooseProject`, `saveNote`, `resume`). Everything that changes the clock returns a promise that rejects with a `ClockError` when Timeclock refuses.
 
 ## The store
 

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export interface ClockState {
     projects: Project[];
     /** Whether the organization requires a project on every entry. */
     requireProject: boolean;
+    requireDescription: boolean;
     /** The pay period's timesheet is in, so the clock is off. */
     locked: boolean;
     /** The IANA time zone the person's times are shown in. */

package/dist/index.js

@@ -21,6 +21,7 @@ const initial = {
     running: null,
     projects: [],
     requireProject: false,
+    requireDescription: false,
     locked: false,
     timeZone: 'UTC',
     busy: false,
@@ -74,6 +75,7 @@ export function createClock(options = {}) {
                 running: me.running ?? null,
                 projects: projects.projects ?? [],
                 requireProject: me.settings.requireProject,
+                requireDescription: me.settings.requireDescription ?? false,
                 locked: status === 'submitted' || status === 'approved',
                 timeZone: me.person.timezone || me.settings.timezone,
             });

package/dist/react.d.ts

@@ -74,6 +74,9 @@ export interface ClockBarLabels extends ProjectPickerLabels {
     locked: string;
     /** When the running stretch started, given the time as text. */
     since: (time: string) => string;
+    missingDescription: string;
+    missingProject: string;
+    missingDescriptionAndProject: string;
 }
 /** What the person was doing when something was refused. */
 export type ClockAction = 'start' | 'stop' | 'switch' | 'note';

package/dist/react.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // The clock for React: useClock() is the logic with no look, and ClockBar
 // and ProjectPicker are a look for it, styled by "@giraffesyo/timeclock/styles.css".
-import { useEffect, useId, useRef, useState, useSyncExternalStore, } from 'react';
+import { useEffect, useId, useLayoutEffect, useRef, useState, useSyncExternalStore, } from 'react';
 import { clockFor, projectHue, projectLabel, stopwatch, } from './index.js';
 /** The clock of the Timeclock at a base path, kept current while the component is mounted. */
 export function useClock(options = {}) {
@@ -33,7 +33,10 @@ export function useClock(options = {}) {
             }
             // A note typed just before choosing a project describes the work being
             // moved to, so it goes with the new stretch.
-            return store.switchTo({ projectId, note: noteEdited ? note : '' });
+            return store.switchTo({
+                projectId,
+                note: noteEdited || state.requireDescription || !running.projectId ? note : '',
+            });
         },
         saveNote,
         start: () => store.start({ projectId: current.projectId, note }),
@@ -77,6 +80,7 @@ export function ProjectPicker({ projects, value, onChange, required = false, dis
     const listId = useId();
     const root = useRef(null);
     const trigger = useRef(null);
+    const menu = useRef(null);
     const [open, setOpen] = useState(false);
     const [query, setQuery] = useState('');
     const [cursor, setCursor] = useState(0);
@@ -87,6 +91,41 @@ export function ProjectPicker({ projects, value, onChange, required = false, dis
         ...projects.map((p) => ({ id: p.id, name: p.name, group: p.customerName })),
     ].filter((o) => words.every((w) => `${o.group} ${o.name}`.toLowerCase().includes(w)));
     const at = Math.min(cursor, Math.max(options.length - 1, 0));
+    // A nested native popover escapes a dialog's scrolling/clipping bounds while
+    // remaining its descendant, so selecting a project keeps the editor open.
+    useLayoutEffect(() => {
+        const el = menu.current;
+        const button = trigger.current;
+        if (!open || !el || !button)
+            return;
+        el.showPopover();
+        const position = () => {
+            const rect = button.getBoundingClientRect();
+            const below = window.innerHeight - rect.bottom - 12;
+            const above = rect.top - 12;
+            el.style.maxHeight = `${Math.max(0, Math.max(below, above))}px`;
+            const height = el.offsetHeight;
+            const down = below >= height || below >= above;
+            el.style.maxHeight = `${Math.max(0, down ? below : above)}px`;
+            el.style.left = `${Math.max(8, Math.min(rect.left, window.innerWidth - el.offsetWidth - 8))}px`;
+            el.style.top = `${down ? rect.bottom + 4 : Math.max(8, rect.top - el.offsetHeight - 4)}px`;
+        };
+        position();
+        el.querySelector('input')?.focus({ preventScroll: true });
+        const observer = new ResizeObserver(position);
+        observer.observe(el);
+        const follow = (e) => {
+            if (e.target instanceof Node && !el.contains(e.target))
+                position();
+        };
+        window.addEventListener('resize', position);
+        window.addEventListener('scroll', follow, true);
+        return () => {
+            observer.disconnect();
+            window.removeEventListener('resize', position);
+            window.removeEventListener('scroll', follow, true);
+        };
+    }, [open]);
     // A press outside closes the list.
     useEffect(() => {
         if (!open)
@@ -127,6 +166,7 @@ export function ProjectPicker({ projects, value, onChange, required = false, dis
                 break;
             }
             case 'Escape':
+                e.preventDefault();
                 // The list closes; a dialog around it stays.
                 e.stopPropagation();
                 e.nativeEvent.stopImmediatePropagation();
@@ -144,12 +184,18 @@ export function ProjectPicker({ projects, value, onChange, required = false, dis
                         e.preventDefault();
                         show();
                     }
-                }, children: [_jsx(ProjectDot, { projectId: current?.id }), _jsx("span", { className: cx('tc-picker-value', !current && 'tc-muted'), children: shown }), _jsx("svg", { "aria-hidden": true, className: "tc-chevron", viewBox: "0 0 12 12", fill: "none", stroke: "currentColor", strokeWidth: "1.75", children: _jsx("path", { d: "M2.5 4.5 6 8l3.5-3.5", strokeLinecap: "round", strokeLinejoin: "round" }) })] }), open && (_jsxs("div", { className: "tc-popover", children: [_jsx("input", { className: "tc-search", role: "combobox", "aria-expanded": true, "aria-controls": listId, "aria-activedescendant": options[at] ? `${listId}-${at}` : undefined, "aria-label": labels.search, placeholder: labels.search, value: query, 
-                        // biome-ignore lint/a11y/noAutofocus: opening the list is asking to search it
-                        autoFocus: true, onChange: (e) => {
+                }, children: [_jsx(ProjectDot, { projectId: current?.id }), _jsx("span", { className: cx('tc-picker-value', !current && 'tc-muted'), children: shown }), _jsx("svg", { "aria-hidden": true, className: "tc-chevron", viewBox: "0 0 12 12", fill: "none", stroke: "currentColor", strokeWidth: "1.75", children: _jsx("path", { d: "M2.5 4.5 6 8l3.5-3.5", strokeLinecap: "round", strokeLinejoin: "round" }) })] }), open && (_jsxs("div", { ref: menu, popover: "auto", className: "tc-popover", onToggle: (e) => {
+                    if (e.target === e.currentTarget && e.newState === 'closed')
+                        setOpen(false);
+                }, children: [_jsx("input", { className: "tc-search", role: "combobox", "aria-expanded": true, "aria-controls": listId, "aria-activedescendant": options[at] ? `${listId}-${at}` : undefined, "aria-label": labels.search, placeholder: labels.search, value: query, onChange: (e) => {
                             setQuery(e.target.value);
                             setCursor(0);
-                        }, onKeyDown: onKeyDown }), _jsxs("div", { id: listId, role: "listbox", "aria-label": label ?? labels.project, className: "tc-options", children: [options.length === 0 && _jsx("p", { className: "tc-empty", children: labels.noMatch }), options.map((o, i) => (_jsxs("div", { children: [o.group !== (options[i - 1]?.group ?? '') && _jsx("div", { className: "tc-group", children: o.group }), _jsxs("div", { id: `${listId}-${i}`, role: "option", tabIndex: -1, "aria-selected": o.id === value, className: cx('tc-option', i === at && 'tc-option-active'), onPointerMove: () => setCursor(i), onClick: () => pick(o.id), children: [_jsx(ProjectDot, { projectId: o.id }), _jsx("span", { className: "tc-option-name", children: o.name }), o.id === value && (_jsx("svg", { "aria-hidden": true, className: "tc-check", viewBox: "0 0 12 12", fill: "none", stroke: "currentColor", strokeWidth: "2", children: _jsx("path", { d: "m2.5 6.5 2.5 2.5 4.5-5.5", strokeLinecap: "round", strokeLinejoin: "round" }) }))] })] }, o.id)))] })] }))] }));
+                        }, onKeyDown: onKeyDown }), _jsxs("div", { id: listId, role: "listbox", "aria-label": label ?? labels.project, className: "tc-options", children: [options.length === 0 && _jsx("p", { className: "tc-empty", children: labels.noMatch }), options.map((o, i) => (_jsxs("div", { children: [o.group !== (options[i - 1]?.group ?? '') && _jsx("div", { className: "tc-group", children: o.group }), _jsxs("div", { id: `${listId}-${i}`, role: "option", tabIndex: -1, "aria-selected": o.id === value, className: cx('tc-option', i === at && 'tc-option-active'), onPointerMove: () => setCursor(i), onClick: (e) => {
+                                            // A picker can sit inside a field label. Selecting its row
+                                            // must not activate the labelled trigger and reopen the menu.
+                                            e.preventDefault();
+                                            pick(o.id);
+                                        }, children: [_jsx(ProjectDot, { projectId: o.id }), _jsx("span", { className: "tc-option-name", children: o.name }), o.id === value && (_jsx("svg", { "aria-hidden": true, className: "tc-check", viewBox: "0 0 12 12", fill: "none", stroke: "currentColor", strokeWidth: "2", children: _jsx("path", { d: "m2.5 6.5 2.5 2.5 4.5-5.5", strokeLinecap: "round", strokeLinejoin: "round" }) }))] })] }, o.id)))] })] }))] }));
 }
 const barLabels = {
     ...pickerLabels,
@@ -161,6 +207,9 @@ const barLabels = {
     switchProject: 'Project the clock is running on',
     locked: 'This pay period’s timesheet is submitted, so the clock is off.',
     since: (time) => `Running since ${time}`,
+    missingDescription: 'Add a description to stop the clock and save this time entry.',
+    missingProject: 'Choose a project to stop the clock and save this time entry.',
+    missingDescriptionAndProject: 'Add a description and choose a project to stop the clock and save this time entry.',
 };
 /**
  * The clock as a bar: say what you are working on, pick its project, and
@@ -175,10 +224,22 @@ export function ClockBar({ basePath, store, labels: given, className, onError, o
     const { running } = clock;
     const now = useSecond(!!running);
     const bar = useRef(null);
+    const [stopAttempt, setStopAttempt] = useState(null);
+    const errorId = useId();
     // Whether a press that began inside the bar is under way.
     const pressed = useRef(false);
     if (clock.status !== 'ready')
         return null;
+    const missingDescription = clock.requireDescription && !clock.note.trim();
+    const missingProject = clock.requireProject && !clock.projectId;
+    const missing = missingDescription && missingProject
+        ? labels.missingDescriptionAndProject
+        : missingDescription
+            ? labels.missingDescription
+            : missingProject
+                ? labels.missingProject
+                : null;
+    const stopError = running && stopAttempt === running.id ? missing : null;
     const failed = (action) => (err) => onError?.(err, action);
     const choose = (projectId) => {
         clock
@@ -203,6 +264,11 @@ export function ClockBar({ basePath, store, labels: given, className, onError, o
         : undefined;
     return (_jsxs("form", { ref: bar, "aria-label": labels.clock, className: cx('tc-bar', className), onSubmit: (e) => {
             e.preventDefault();
+            if (running && missing) {
+                setStopAttempt(running.id);
+                return;
+            }
+            setStopAttempt(null);
             if (running)
                 clock.stop().then(onChanged, failed('stop'));
             else
@@ -213,11 +279,11 @@ export function ClockBar({ basePath, store, labels: given, className, onError, o
             pressed.current = false;
         }, onPointerCancelCapture: () => {
             pressed.current = false;
-        }, children: [_jsx("input", { className: "tc-note", value: clock.note, placeholder: clock.locked ? labels.locked : labels.notePlaceholder, "aria-label": labels.noteLabel, disabled: clock.locked, maxLength: 2000, onChange: (e) => clock.setNote(e.target.value), onBlur: running ? leaveNote : undefined, onKeyDown: (e) => {
+        }, children: [_jsx("input", { className: "tc-note", value: clock.note, placeholder: clock.locked ? labels.locked : labels.notePlaceholder, "aria-label": labels.noteLabel, disabled: clock.locked, "aria-required": !!running && clock.requireDescription, "aria-invalid": !!stopError && missingDescription, "aria-describedby": stopError && missingDescription ? errorId : undefined, maxLength: 2000, onChange: (e) => clock.setNote(e.target.value), onBlur: running ? leaveNote : undefined, onKeyDown: (e) => {
                     // While the clock runs, Enter is done with the note; it doesn't stop the clock.
                     if (running && e.key === 'Enter') {
                         e.preventDefault();
                         e.currentTarget.blur();
                     }
-                } }), _jsx(ProjectPicker, { className: "tc-bar-picker", projects: clock.projects, value: clock.projectId, onChange: choose, required: clock.requireProject, disabled: clock.locked || (!!running && clock.busy), label: running ? labels.switchProject : undefined, labels: labels }), running ? (_jsx("span", { className: "tc-time", role: "timer", title: since, children: stopwatch(now - Date.parse(running.startedAt)) })) : (_jsx("span", { "aria-hidden": true, className: "tc-time tc-time-idle", children: stopwatch(0) })), _jsx("button", { type: "submit", "aria-label": running ? labels.stop : labels.start, disabled: clock.locked || clock.busy, className: cx('tc-go', !!running && 'tc-go-stop'), children: _jsx("svg", { "aria-hidden": true, viewBox: "0 0 16 16", fill: "currentColor", children: running ? _jsx("rect", { x: "4", y: "4", width: "8", height: "8", rx: "1" }) : _jsx("path", { d: "M5.5 3.5v9l7-4.5z" }) }) })] }));
+                } }), _jsx(ProjectPicker, { className: "tc-bar-picker", projects: clock.projects, value: clock.projectId, onChange: choose, required: clock.requireProject, disabled: clock.locked || (!!running && clock.busy), label: running ? labels.switchProject : undefined, labels: labels }), running ? (_jsx("span", { className: "tc-time", role: "timer", title: since, children: stopwatch(now - Date.parse(running.startedAt)) })) : (_jsx("span", { "aria-hidden": true, className: "tc-time tc-time-idle", children: stopwatch(0) })), _jsx("button", { type: "submit", "aria-describedby": stopError ? errorId : undefined, "aria-label": running ? labels.stop : labels.start, disabled: clock.locked || clock.busy, className: cx('tc-go', !!running && 'tc-go-stop'), children: _jsx("svg", { "aria-hidden": true, viewBox: "0 0 16 16", fill: "currentColor", children: running ? _jsx("rect", { x: "4", y: "4", width: "8", height: "8", rx: "1" }) : _jsx("path", { d: "M5.5 3.5v9l7-4.5z" }) }) }), stopError && (_jsx("p", { id: errorId, role: "alert", className: "tc-stop-error", children: stopError }))] }));
 }

package/dist/styles.css

@@ -97,6 +97,13 @@
   cursor: not-allowed;
   opacity: 0.5;
 }
+.tc-stop-error {
+  flex: 1 1 100%;
+  margin: 0;
+  padding: 0.25rem 0.75rem;
+  color: var(--tc-fg);
+  font-size: 0.875rem;
+}
 @media (min-width: 40rem) {
   .tc-note {
     flex-basis: 12rem;
@@ -155,13 +162,13 @@
   color: var(--tc-accent);
 }
 .tc-popover {
-  position: absolute;
-  top: 100%;
-  left: 0;
-  z-index: 40;
+  position: fixed;
+  inset: auto;
+  padding: 0;
+  color: var(--tc-fg);
   width: 18rem;
   max-width: calc(100vw - 2rem);
-  margin-top: 0.25rem;
+  margin: 0;
   border: 1px solid var(--tc-border);
   border-radius: 0.625rem;
   background: var(--tc-bg);
@@ -169,7 +176,12 @@
     0 10px 28px -10px rgb(0 0 0 / 0.3),
     0 2px 6px -2px rgb(0 0 0 / 0.12);
 }
+.tc-popover:popover-open {
+  display: flex;
+  flex-direction: column;
+}
 .tc-search {
+  flex-shrink: 0;
   width: 100%;
   padding: 0.5rem 0.75rem;
   border: 0;
@@ -185,6 +197,7 @@
   color: var(--tc-muted);
 }
 .tc-options {
+  min-height: 0;
   max-height: 16rem;
   overflow-y: auto;
   padding: 0.25rem;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giraffesyo/timeclock",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The Timeclock clock for a host application: a headless store and React hook, and a ready-made bar.",
   "license": "Apache-2.0",
   "repository": {