@giraffesyo/timeclock 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.
+

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# @giraffesyo/timeclock
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The [Timeclock](https://github.com/giraffesyo/timeclock) clock for a host application: start, stop and move the clock from your own header, without sending people to Timeclock's pages.
+
+It talks to a Timeclock mounted on the same origin (for example at `/timeclock`), as the person your application has signed in. There are three layers; use the lowest one that does what you need.
+
+```sh
+npm install @giraffesyo/timeclock
+```
+
+## The bar
+
+A ready-made bar: what you are working on, the project, the running time, and a start/stop button. It draws nothing until Timeclock has answered, and nothing for someone Timeclock doesn't know.
+
+```tsx
+import { ClockBar } from '@giraffesyo/timeclock/react';
+import '@giraffesyo/timeclock/styles.css';
+
+<ClockBar
+  basePath="/timeclock"
+  onError={(err, action) => notify(`Couldn't ${action}: ${err.message}`)}
+  onSwitched={(entry) => notify('Moved the clock')}
+/>;
+```
+
+- While the clock runs, choosing another project moves the clock to it without stopping: the time so far stays on the project it was on.
+- The note saves when the field is left; a note typed just before choosing a project goes with the new stretch.
+- `labels` replaces any of its words, for another language or voice.
+- Colors come from `--tc-*` custom properties. They default to [@parallelworks/ui](https://www.npmjs.com/package/@parallelworks/ui)'s theme tokens (`--theme-*`) when the page has them, and to plain light values when it doesn't. Set `--tc-bg`, `--tc-fg`, `--tc-muted`, `--tc-border`, `--tc-hover`, `--tc-accent`, `--tc-accent-fg` and `--tc-stop` on an ancestor to fit another look.
+
+`ProjectPicker` and `ProjectDot` are exported too.
+
+## The hook
+
+The clock with no look, to draw your own:
+
+```tsx
+import { useClock } from '@giraffesyo/timeclock/react';
+
+function HeaderClock() {
+  const clock = useClock({ basePath: '/timeclock' });
+  if (clock.status !== 'ready') return null;
+  return clock.running ? (
+    <button onClick={() => clock.stop()}>Stop</button>
+  ) : (
+    <button onClick={() => clock.start()}>Start</button>
+  );
+}
+```
+
+`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.
+
+## The store
+
+No React at all:
+
+```ts
+import { clockFor } from '@giraffesyo/timeclock';
+
+const clock = clockFor('/timeclock');
+const stop = clock.subscribe(() => render(clock.getState()));
+await clock.start({ projectId, note: 'Standup' });
+```
+
+`clockFor(basePath)` is one store for the page, so everything showing the clock agrees. While something is subscribed it asks Timeclock again every minute and whenever the tab comes back, since a clock can be stopped from another tab. `createClock(options)` makes a separate one, with your own `fetch` or polling interval.
+
+## Errors
+
+A `ClockError` carries the HTTP `status`, the problem's stable `code` (such as `project_required` or `period_locked`), a `message` in English, and the RFC 9457 problem itself as `body`.
+
+## Versions
+
+The package follows the server's API under `/api/v1`. A host should run a Timeclock at least as new as the package it uses.

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+/** A stretch of work. `endedAt` is absent while the clock is running. */
+export interface Entry {
+    id: string;
+    personId: string;
+    projectId?: string;
+    startedAt: string;
+    endedAt?: string;
+    note: string;
+}
+/** A project time is recorded on. `customerName` is empty for internal work. */
+export interface Project {
+    id: string;
+    name: string;
+    customerName: string;
+}
+export interface ClockState {
+    /**
+     * `loading` until the first answer; `signed-out` when Timeclock doesn't
+     * know the caller; `unavailable` when it can't be reached.
+     */
+    status: 'loading' | 'ready' | 'signed-out' | 'unavailable';
+    /** The running stretch, if the clock is on. */
+    running: Entry | null;
+    /** The projects that take new time, internal ones first, then by customer. */
+    projects: Project[];
+    /** Whether the organization requires a project on every entry. */
+    requireProject: 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. */
+    timeZone: string;
+    /** A change is on its way. */
+    busy: boolean;
+}
+export interface ClockOptions {
+    /** Where Timeclock is mounted, such as "/timeclock". Empty at the site root. */
+    basePath?: string;
+    /** How to make requests; the page's own fetch by default. */
+    fetch?: typeof fetch;
+    /** How often to ask again while something is listening, in milliseconds. A clock can be stopped from another tab. */
+    pollMs?: number;
+}
+/** What starts or moves the clock: a project and a note, both optional. */
+export interface ClockInput {
+    projectId?: string;
+    note?: string;
+}
+/** A request Timeclock refused. `body` is the RFC 9457 problem it answered with. */
+export declare class ClockError extends Error {
+    readonly status: number;
+    /** The problem's stable code, such as "project_required". */
+    readonly code: string;
+    readonly body: unknown;
+    constructor(status: number, 
+    /** The problem's stable code, such as "project_required". */
+    code: string, message: string, body: unknown);
+}
+export interface ClockStore {
+    getState(): ClockState;
+    /** Calls `listener` after every change. Listening keeps the store fresh; returns how to stop. */
+    subscribe(listener: () => void): () => void;
+    /** Asks Timeclock again. */
+    refresh(): Promise<void>;
+    start(input?: ClockInput): Promise<Entry>;
+    stop(): Promise<Entry>;
+    /**
+     * Moves the running clock to other work without stopping it: the time so
+     * far stays where it was, and the clock goes on from this instant.
+     */
+    switchTo(input: ClockInput): Promise<Entry>;
+    /** Sets the running stretch's note. */
+    saveNote(note: string): Promise<Entry>;
+    /** Starts the clock on what an entry was about; a running clock moves to it. */
+    resume(entry: Pick<Entry, 'projectId' | 'note'>): Promise<Entry>;
+}
+/** Makes a clock store. Most hosts want {@link clockFor}, which shares one per base path. */
+export declare function createClock(options?: ClockOptions): ClockStore;
+/** The clock store for a Timeclock at a base path: one for the page, so everything showing the clock agrees. */
+export declare function clockFor(basePath?: string): ClockStore;
+/** "Customer / Project", or just the project for internal work. */
+export declare function projectLabel(project: Project): string;
+/** A project's hue (0–359), the same wherever its time is shown. */
+export declare function projectHue(projectId: string): number;
+/** Milliseconds as H:MM:SS, for a running clock. */
+export declare function stopwatch(ms: number): string;

package/dist/index.js

@@ -0,0 +1,162 @@
+// The Timeclock clock for a host application, with no look and no framework:
+// a store that knows what is running and can start, stop and move the clock.
+// It talks to a Timeclock mounted on the same origin, as the signed-in person.
+/** A request Timeclock refused. `body` is the RFC 9457 problem it answered with. */
+export class ClockError extends Error {
+    status;
+    code;
+    body;
+    constructor(status, 
+    /** The problem's stable code, such as "project_required". */
+    code, message, body) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.body = body;
+        this.name = 'ClockError';
+    }
+}
+const initial = {
+    status: 'loading',
+    running: null,
+    projects: [],
+    requireProject: false,
+    locked: false,
+    timeZone: 'UTC',
+    busy: false,
+};
+/** Makes a clock store. Most hosts want {@link clockFor}, which shares one per base path. */
+export function createClock(options = {}) {
+    const base = `${(options.basePath ?? '').replace(/\/$/, '')}/api/v1`;
+    const request = options.fetch ?? ((input, init) => fetch(input, init));
+    const pollMs = options.pollMs ?? 60_000;
+    const listeners = new Set();
+    let state = initial;
+    let timer;
+    const set = (patch) => {
+        state = { ...state, ...patch };
+        for (const listener of listeners)
+            listener();
+    };
+    async function call(method, path, body) {
+        const res = await request(base + path, {
+            method,
+            credentials: 'same-origin',
+            headers: body === undefined
+                ? { Accept: 'application/json' }
+                : { Accept: 'application/json', 'Content-Type': 'application/json' },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await res.text();
+        let json;
+        try {
+            json = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            json = undefined;
+        }
+        if (!res.ok) {
+            const problem = (json ?? {});
+            throw new ClockError(res.status, problem.code ?? '', problem.detail || problem.title || res.statusText, json);
+        }
+        return json;
+    }
+    const refresh = async () => {
+        try {
+            const [me, projects, sheet] = await Promise.all([
+                call('GET', '/me'),
+                call('GET', '/projects'),
+                call('GET', '/timesheet'),
+            ]);
+            const status = sheet.timesheet?.status;
+            set({
+                status: 'ready',
+                running: me.running ?? null,
+                projects: projects.projects ?? [],
+                requireProject: me.settings.requireProject,
+                locked: status === 'submitted' || status === 'approved',
+                timeZone: me.person.timezone || me.settings.timezone,
+            });
+        }
+        catch (err) {
+            set({ status: err instanceof ClockError && err.status === 401 ? 'signed-out' : 'unavailable' });
+        }
+    };
+    // One change at a time: the bar shows it is busy, then what is now true.
+    const change = async (run) => {
+        set({ busy: true });
+        try {
+            const entry = await run();
+            set({ running: entry.endedAt ? null : entry });
+            return entry;
+        }
+        finally {
+            set({ busy: false });
+            void refresh();
+        }
+    };
+    const onVisible = () => {
+        if (document.visibilityState === 'visible')
+            void refresh();
+    };
+    const store = {
+        getState: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            if (listeners.size === 1) {
+                void refresh();
+                timer = setInterval(() => void refresh(), pollMs);
+                if (typeof document !== 'undefined')
+                    document.addEventListener('visibilitychange', onVisible);
+            }
+            return () => {
+                listeners.delete(listener);
+                if (listeners.size === 0) {
+                    clearInterval(timer);
+                    if (typeof document !== 'undefined')
+                        document.removeEventListener('visibilitychange', onVisible);
+                }
+            };
+        },
+        refresh,
+        start: (input = {}) => change(() => call('POST', '/clock/in', { projectId: input.projectId || undefined, note: input.note ?? '' })),
+        stop: () => change(() => call('POST', '/clock/out')),
+        switchTo: (input) => change(() => call('POST', '/clock/switch', { projectId: input.projectId || undefined, note: input.note ?? '' })),
+        saveNote: (note) => {
+            const running = state.running;
+            if (!running)
+                return Promise.reject(new ClockError(409, 'clock_not_running', 'the clock is not running', undefined));
+            return change(() => call('PUT', `/entries/${running.id}`, { projectId: running.projectId, startedAt: running.startedAt, note }));
+        },
+        resume: (entry) => (state.running ? store.switchTo(entry) : store.start(entry)),
+    };
+    return store;
+}
+const shared = new Map();
+/** The clock store for a Timeclock at a base path: one for the page, so everything showing the clock agrees. */
+export function clockFor(basePath = '') {
+    let store = shared.get(basePath);
+    if (!store) {
+        store = createClock({ basePath });
+        shared.set(basePath, store);
+    }
+    return store;
+}
+/** "Customer / Project", or just the project for internal work. */
+export function projectLabel(project) {
+    return project.customerName ? `${project.customerName} / ${project.name}` : project.name;
+}
+/** A project's hue (0–359), the same wherever its time is shown. */
+export function projectHue(projectId) {
+    let h = 0;
+    for (let i = 0; i < projectId.length; i++)
+        h = (h * 31 + projectId.charCodeAt(i)) >>> 0;
+    // Steps of the golden angle keep any two projects' hues apart.
+    return Math.round((h % 997) * 137.508) % 360;
+}
+/** Milliseconds as H:MM:SS, for a running clock. */
+export function stopwatch(ms) {
+    const s = Math.max(0, Math.floor(ms / 1000));
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${Math.floor(s / 3600)}:${pad(Math.floor((s % 3600) / 60))}:${pad(s % 60)}`;
+}

package/dist/react.d.ts

@@ -0,0 +1,96 @@
+import { type ClockError, type ClockState, type ClockStore, type Entry, type Project } from './index.js';
+export interface UseClockOptions {
+    /** Where Timeclock is mounted, such as "/timeclock". Ignored when `store` is given. */
+    basePath?: string;
+    /** A store made with createClock(), instead of the page's shared one. */
+    store?: ClockStore;
+}
+/** The clock without a look: what is running, what is being typed, and what can be done about it. */
+export interface Clock extends ClockState {
+    /** The note in the field: the running stretch's, or the one to start with. */
+    note: string;
+    setNote: (note: string) => void;
+    /** Whether the note differs from what is saved on the running stretch. */
+    noteEdited: boolean;
+    /** The project in the picker: the running stretch's, or the one to start on. */
+    projectId: string;
+    /** Picks a project. While the clock runs this moves the clock to it, and answers with the new stretch. */
+    chooseProject: (projectId: string) => Promise<Entry | null>;
+    /** Saves an edited note onto the running stretch. */
+    saveNote: () => Promise<void>;
+    start: () => Promise<Entry>;
+    /** Stops the clock, saving an edited note first. */
+    stop: () => Promise<Entry>;
+    /** Starts the clock on what an entry was about; a running clock moves to it. */
+    resume: (entry: Pick<Entry, 'projectId' | 'note'>) => Promise<Entry>;
+    /** The store underneath, for anything else. */
+    store: ClockStore;
+}
+/** The clock of the Timeclock at a base path, kept current while the component is mounted. */
+export declare function useClock(options?: UseClockOptions): Clock;
+export interface ProjectPickerLabels {
+    /** What the control is: "Project". */
+    project: string;
+    /** Shown when nothing is chosen and nothing has to be. */
+    none: string;
+    /** Shown when a project must be chosen and none is. */
+    choose: string;
+    search: string;
+    noMatch: string;
+}
+/** A project's color, as a dot: the same hue its time has everywhere. */
+export declare function ProjectDot({ projectId, className }: {
+    projectId?: string | null;
+    className?: string;
+}): import("react").JSX.Element;
+/**
+ * Picks the project time is recorded on: a button that opens a list to
+ * search, grouped by customer.
+ */
+export declare function ProjectPicker({ projects, value, onChange, required, disabled, className, id, label, labels: given, }: {
+    /** The projects to choose from. One that is the value but not among them is still shown as chosen. */
+    projects: Project[];
+    value: string;
+    onChange: (projectId: string) => void;
+    /** A project must be chosen: there is no "no project" choice. */
+    required?: boolean;
+    disabled?: boolean;
+    className?: string;
+    id?: string;
+    /** What the control is for, when it isn't simply the project. */
+    label?: string;
+    labels?: Partial<ProjectPickerLabels>;
+}): import("react").JSX.Element;
+export interface ClockBarLabels extends ProjectPickerLabels {
+    /** The bar's name, for assistive tech. */
+    clock: string;
+    notePlaceholder: string;
+    noteLabel: string;
+    start: string;
+    stop: string;
+    /** What the picker is for while the clock runs. */
+    switchProject: string;
+    /** Replaces the note's placeholder when the pay period's timesheet is in. */
+    locked: string;
+    /** When the running stretch started, given the time as text. */
+    since: (time: string) => string;
+}
+/** What the person was doing when something was refused. */
+export type ClockAction = 'start' | 'stop' | 'switch' | 'note';
+/**
+ * The clock as a bar: say what you are working on, pick its project, and
+ * start. While it runs the same bar changes it in place: the note is the
+ * running stretch's own, and another project moves the clock to it without
+ * stopping. It draws nothing until Timeclock has answered, and nothing for
+ * someone Timeclock doesn't know.
+ */
+export declare function ClockBar({ basePath, store, labels: given, className, onError, onSwitched, onChanged, }: UseClockOptions & {
+    labels?: Partial<ClockBarLabels>;
+    className?: string;
+    /** Called when Timeclock refuses something, to tell the person. */
+    onError?: (error: ClockError | unknown, action: ClockAction) => void;
+    /** Called when the running clock moved to another project, with the new stretch. */
+    onSwitched?: (entry: Entry) => void;
+    /** Called after anything the bar did took effect, for a host that shows the same time elsewhere. */
+    onChanged?: () => void;
+}): import("react").JSX.Element | null;

package/dist/react.js

@@ -0,0 +1,223 @@
+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 { 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 = {}) {
+    const store = options.store ?? clockFor(options.basePath);
+    const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+    const { running } = state;
+    // What is typed belongs to one stretch (or to none yet): when the running
+    // stretch changes, the field starts over from the new one's note.
+    const stretch = running?.id ?? '';
+    const [draft, setDraft] = useState({ stretch, note: running?.note ?? '', projectId: '' });
+    const current = draft.stretch === stretch ? draft : { stretch, note: running?.note ?? '', projectId: '' };
+    const note = current.note;
+    const noteEdited = !!running && note.trim() !== running.note;
+    const saveNote = async () => {
+        if (running && noteEdited)
+            await store.saveNote(note);
+    };
+    return {
+        ...state,
+        store,
+        note,
+        setNote: (next) => setDraft({ ...current, note: next }),
+        noteEdited,
+        projectId: running ? (running.projectId ?? '') : current.projectId,
+        chooseProject: async (projectId) => {
+            if (!running) {
+                setDraft({ ...current, projectId });
+                return null;
+            }
+            // 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 : '' });
+        },
+        saveNote,
+        start: () => store.start({ projectId: current.projectId, note }),
+        stop: async () => {
+            await saveNote();
+            return store.stop();
+        },
+        resume: (entry) => store.resume(entry),
+    };
+}
+/** The current time, refreshed every second while enabled. */
+function useSecond(enabled) {
+    const [now, setNow] = useState(() => Date.now());
+    useEffect(() => {
+        if (!enabled)
+            return;
+        setNow(Date.now());
+        const id = setInterval(() => setNow(Date.now()), 1000);
+        return () => clearInterval(id);
+    }, [enabled]);
+    return now;
+}
+const cx = (...parts) => parts.filter(Boolean).join(' ');
+const pickerLabels = {
+    project: 'Project',
+    none: 'No project',
+    choose: 'Choose a project',
+    search: 'Search projects',
+    noMatch: 'No project matches.',
+};
+/** A project's color, as a dot: the same hue its time has everywhere. */
+export function ProjectDot({ projectId, className }) {
+    return (_jsx("span", { "aria-hidden": true, className: cx('tc-dot', !projectId && 'tc-dot-none', className), style: projectId ? { '--tc-hue': projectHue(projectId) } : undefined }));
+}
+/**
+ * Picks the project time is recorded on: a button that opens a list to
+ * search, grouped by customer.
+ */
+export function ProjectPicker({ projects, value, onChange, required = false, disabled, className, id, label, labels: given, }) {
+    const labels = { ...pickerLabels, ...given };
+    const listId = useId();
+    const root = useRef(null);
+    const trigger = useRef(null);
+    const [open, setOpen] = useState(false);
+    const [query, setQuery] = useState('');
+    const [cursor, setCursor] = useState(0);
+    const current = value ? projects.find((p) => p.id === value) : undefined;
+    const words = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+    const options = [
+        ...(required ? [] : [{ id: '', name: labels.none, group: '' }]),
+        ...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 press outside closes the list.
+    useEffect(() => {
+        if (!open)
+            return;
+        const close = (e) => {
+            if (!root.current?.contains(e.target))
+                setOpen(false);
+        };
+        document.addEventListener('pointerdown', close);
+        return () => document.removeEventListener('pointerdown', close);
+    }, [open]);
+    const show = () => {
+        setQuery('');
+        setCursor(Math.max(0, options.findIndex((o) => o.id === value)));
+        setOpen(true);
+    };
+    const pick = (projectId) => {
+        setOpen(false);
+        trigger.current?.focus();
+        if (projectId !== value)
+            onChange(projectId);
+    };
+    const onKeyDown = (e) => {
+        switch (e.key) {
+            case 'ArrowDown':
+                e.preventDefault();
+                setCursor(Math.min(at + 1, options.length - 1));
+                break;
+            case 'ArrowUp':
+                e.preventDefault();
+                setCursor(Math.max(at - 1, 0));
+                break;
+            case 'Enter': {
+                e.preventDefault();
+                const o = options[at];
+                if (o)
+                    pick(o.id);
+                break;
+            }
+            case 'Escape':
+                // The list closes; a dialog around it stays.
+                e.stopPropagation();
+                e.nativeEvent.stopImmediatePropagation();
+                setOpen(false);
+                trigger.current?.focus();
+                break;
+            case 'Tab':
+                setOpen(false);
+                break;
+        }
+    };
+    const shown = current ? projectLabel(current) : required ? labels.choose : labels.none;
+    return (_jsxs("div", { ref: root, className: cx('tc-picker', className), children: [_jsxs("button", { ref: trigger, id: id, type: "button", className: "tc-picker-button", "aria-haspopup": "listbox", "aria-expanded": open, "aria-label": `${label ?? labels.project}: ${shown}`, disabled: disabled, onClick: () => (open ? setOpen(false) : show()), onKeyDown: (e) => {
+                    if (!open && (e.key === 'ArrowDown' || e.key === 'ArrowUp')) {
+                        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) => {
+                            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)))] })] }))] }));
+}
+const barLabels = {
+    ...pickerLabels,
+    clock: 'Clock',
+    notePlaceholder: 'What are you working on?',
+    noteLabel: 'What you are working on',
+    start: 'Start the clock',
+    stop: 'Stop the clock',
+    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}`,
+};
+/**
+ * The clock as a bar: say what you are working on, pick its project, and
+ * start. While it runs the same bar changes it in place: the note is the
+ * running stretch's own, and another project moves the clock to it without
+ * stopping. It draws nothing until Timeclock has answered, and nothing for
+ * someone Timeclock doesn't know.
+ */
+export function ClockBar({ basePath, store, labels: given, className, onError, onSwitched, onChanged, }) {
+    const labels = { ...barLabels, ...given };
+    const clock = useClock({ basePath, store });
+    const { running } = clock;
+    const now = useSecond(!!running);
+    const bar = useRef(null);
+    // Whether a press that began inside the bar is under way.
+    const pressed = useRef(false);
+    if (clock.status !== 'ready')
+        return null;
+    const failed = (action) => (err) => onError?.(err, action);
+    const choose = (projectId) => {
+        clock
+            .chooseProject(projectId)
+            .then((next) => {
+            if (next) {
+                onSwitched?.(next);
+                onChanged?.();
+            }
+        })
+            .catch(failed('switch'));
+    };
+    const leaveNote = (e) => {
+        // Moving on to the project picker isn't done with the note yet. Safari
+        // doesn't focus a button that is clicked, so the press is noted as well.
+        if (pressed.current || bar.current?.contains(e.relatedTarget))
+            return;
+        clock.saveNote().then(onChanged, failed('note'));
+    };
+    const since = running
+        ? labels.since(new Intl.DateTimeFormat(undefined, { hour: 'numeric', minute: '2-digit', timeZone: clock.timeZone }).format(new Date(running.startedAt)))
+        : undefined;
+    return (_jsxs("form", { ref: bar, "aria-label": labels.clock, className: cx('tc-bar', className), onSubmit: (e) => {
+            e.preventDefault();
+            if (running)
+                clock.stop().then(onChanged, failed('stop'));
+            else
+                clock.start().then(onChanged, failed('start'));
+        }, onPointerDownCapture: () => {
+            pressed.current = true;
+        }, onPointerUpCapture: () => {
+            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) => {
+                    // 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" }) }) })] }));
+}

package/dist/styles.css

@@ -0,0 +1,236 @@
+/* The look of @giraffesyo/timeclock's ClockBar and ProjectPicker. Colors come
+ * from the --tc-* properties, which default to @parallelworks/ui's theme
+ * contract (--theme-*) and, without it, to plain light values. Set --tc-*
+ * on any ancestor to fit another look. */
+.tc-bar,
+.tc-picker {
+  --tc-bg: var(--theme-panel-bg, #fff);
+  --tc-fg: var(--theme-panel, #16181d);
+  --tc-muted: var(--theme-muted-text-color, #5d6370);
+  --tc-border: var(--theme-border, #d9dce3);
+  --tc-hover: var(--theme-hover, #eef0f4);
+  --tc-accent: var(--theme-accent, #474fd4);
+  --tc-accent-fg: var(--theme-accent-text, #fff);
+  --tc-stop: var(--danger, #d92d20);
+  --tc-radius: 0.5rem;
+  box-sizing: border-box;
+  color: var(--tc-fg);
+  font-variant-numeric: tabular-nums;
+}
+.tc-bar *,
+.tc-picker * {
+  box-sizing: border-box;
+}
+
+.tc-bar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.375rem 0.75rem;
+}
+.tc-note {
+  flex: 1 1 100%;
+  min-width: 0;
+  height: 2.5rem;
+  padding: 0 0.75rem;
+  border: 1px solid transparent;
+  border-radius: var(--tc-radius);
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  font-size: 1rem;
+}
+.tc-note::placeholder {
+  color: var(--tc-muted);
+}
+.tc-note:hover,
+.tc-note:focus-visible {
+  border-color: var(--tc-border);
+}
+.tc-bar-picker {
+  flex: 1 1 0;
+  min-width: 0;
+  height: 2.5rem;
+}
+.tc-time {
+  width: 6rem;
+  text-align: right;
+  font-size: 1.25rem;
+  font-weight: 600;
+  letter-spacing: -0.02em;
+}
+.tc-time-idle {
+  display: none;
+  color: color-mix(in oklab, var(--tc-muted) 60%, transparent);
+}
+.tc-go {
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  width: 2.5rem;
+  height: 2.5rem;
+  border: 0;
+  border-radius: 9999px;
+  background: var(--tc-accent);
+  color: var(--tc-accent-fg);
+  cursor: pointer;
+  transition:
+    scale 120ms ease-out,
+    opacity 120ms ease-out;
+}
+.tc-go svg {
+  width: 1.25rem;
+  height: 1.25rem;
+}
+.tc-go-stop {
+  background: var(--tc-stop);
+  color: var(--tc-bg);
+}
+.tc-go:hover:enabled {
+  opacity: 0.9;
+}
+.tc-go:active:enabled {
+  scale: 0.95;
+}
+.tc-go:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+@media (min-width: 40rem) {
+  .tc-note {
+    flex-basis: 12rem;
+  }
+  .tc-bar-picker {
+    flex: 0 0 15rem;
+  }
+  .tc-time-idle {
+    display: block;
+  }
+}
+
+.tc-picker {
+  position: relative;
+  min-height: 2.25rem;
+}
+.tc-picker-button {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  width: 100%;
+  height: 100%;
+  min-height: 2.25rem;
+  padding: 0 0.75rem;
+  border: 1px solid var(--tc-border);
+  border-radius: var(--tc-radius);
+  background: var(--tc-bg);
+  color: inherit;
+  font: inherit;
+  font-size: 0.875rem;
+  text-align: left;
+  cursor: pointer;
+}
+.tc-picker-button:disabled {
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+.tc-picker-value {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.tc-muted {
+  color: var(--tc-muted);
+}
+.tc-chevron,
+.tc-check {
+  flex-shrink: 0;
+  width: 0.875rem;
+  height: 0.875rem;
+  color: var(--tc-muted);
+}
+.tc-check {
+  color: var(--tc-accent);
+}
+.tc-popover {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  z-index: 40;
+  width: 18rem;
+  max-width: calc(100vw - 2rem);
+  margin-top: 0.25rem;
+  border: 1px solid var(--tc-border);
+  border-radius: 0.625rem;
+  background: var(--tc-bg);
+  box-shadow:
+    0 10px 28px -10px rgb(0 0 0 / 0.3),
+    0 2px 6px -2px rgb(0 0 0 / 0.12);
+}
+.tc-search {
+  width: 100%;
+  padding: 0.5rem 0.75rem;
+  border: 0;
+  border-bottom: 1px solid var(--tc-border);
+  border-radius: 0.625rem 0.625rem 0 0;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  font-size: 0.875rem;
+  outline: none;
+}
+.tc-search::placeholder {
+  color: var(--tc-muted);
+}
+.tc-options {
+  max-height: 16rem;
+  overflow-y: auto;
+  padding: 0.25rem;
+}
+.tc-group {
+  padding: 0.5rem 0.5rem 0.25rem;
+  font-size: 0.75rem;
+  font-weight: 500;
+  color: var(--tc-muted);
+}
+.tc-option {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.375rem 0.5rem;
+  border-radius: 0.375rem;
+  font-size: 0.875rem;
+  cursor: pointer;
+}
+.tc-option-active {
+  background: var(--tc-hover);
+}
+.tc-option-name {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.tc-empty {
+  margin: 0;
+  padding: 0.75rem 0.5rem;
+  text-align: center;
+  font-size: 0.875rem;
+  color: var(--tc-muted);
+}
+
+.tc-dot {
+  display: inline-block;
+  flex-shrink: 0;
+  width: 0.5rem;
+  height: 0.5rem;
+  border-radius: 9999px;
+  background: oklch(0.64 0.15 var(--tc-hue));
+}
+.tc-dot-none {
+  background: transparent;
+  box-shadow: inset 0 0 0 1.5px var(--tc-muted);
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@giraffesyo/timeclock",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.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": {
+    "type": "git",
+    "url": "git+https://github.com/giraffesyo/timeclock.git",
+    "directory": "web/packages/timeclock"
+  },
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc6 -p tsconfig.build.json && cp src/styles.css dist/styles.css",
+    "typecheck": "tsc6 -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "react": "^19.3.0",
+    "typescript": "npm:@typescript/typescript6@^6.0.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}