@open-mercato/core 0.7.1-develop.7178.1.ab93fbaf4e → 0.7.1-develop.7180.1.9717fbbb43

package/src/modules/staff/lib/time-tracking-ui/timesheetTargets.ts

@@ -0,0 +1,93 @@
+/**
+ * What a timesheet line logs against — a project, or a project **and** a task.
+ *
+ * The spec's second grid upgrade ("rows can be project or project + task, so
+ * grid entries carry `taskId` like every other entry") and screen 12's quick-add
+ * row are the same question asked twice, so they share one model. A target is
+ * addressed by a single opaque key, because the grid's dirty map, its row list
+ * and the list view's `<select>` all need one string that identifies a line
+ * without pretending a project row and a task row are different kinds of thing.
+ */
+
+export type TimesheetLogTarget = {
+  /** `<projectId>` for a project row, `<projectId>:<taskId>` for a task row. */
+  key: string
+  timeProjectId: string
+  taskId: string | null
+  projectName: string
+  projectCode: string | null
+  projectColor: string | null
+  taskTitle: string | null
+}
+
+export type TimesheetProjectRef = {
+  id: string
+  name: string
+  code: string | null
+  color: string | null
+}
+
+export type TimesheetTaskRef = {
+  id: string
+  title: string
+  timeProjectId: string
+}
+
+export function buildTargetKey(timeProjectId: string, taskId: string | null | undefined): string {
+  return taskId ? `${timeProjectId}:${taskId}` : timeProjectId
+}
+
+export function parseTargetKey(key: string): { timeProjectId: string; taskId: string | null } {
+  const separator = key.indexOf(':')
+  if (separator < 0) return { timeProjectId: key, taskId: null }
+  return { timeProjectId: key.slice(0, separator), taskId: key.slice(separator + 1) || null }
+}
+
+export function projectTarget(project: TimesheetProjectRef): TimesheetLogTarget {
+  return {
+    key: buildTargetKey(project.id, null),
+    timeProjectId: project.id,
+    taskId: null,
+    projectName: project.name,
+    projectCode: project.code,
+    projectColor: project.color,
+    taskTitle: null,
+  }
+}
+
+export function taskTarget(project: TimesheetProjectRef, task: TimesheetTaskRef): TimesheetLogTarget {
+  return {
+    key: buildTargetKey(project.id, task.id),
+    timeProjectId: project.id,
+    taskId: task.id,
+    projectName: project.name,
+    projectCode: project.code,
+    projectColor: project.color,
+    taskTitle: task.title,
+  }
+}
+
+/**
+ * Every loggable line for a set of projects: the project itself, then its tasks.
+ * Tasks of a project the caller cannot see are dropped rather than rendered
+ * without a project name — a row whose project is unknown cannot be saved.
+ */
+export function buildLogTargets(
+  projects: readonly TimesheetProjectRef[],
+  tasks: readonly TimesheetTaskRef[],
+): TimesheetLogTarget[] {
+  const targets: TimesheetLogTarget[] = []
+  for (const project of projects) {
+    targets.push(projectTarget(project))
+    for (const task of tasks) {
+      if (task.timeProjectId !== project.id) continue
+      targets.push(taskTarget(project, task))
+    }
+  }
+  return targets
+}
+
+/** `Nordvik — migracja B2B · Mapowanie cen` — one line for a picker or a row header. */
+export function targetLabel(target: TimesheetLogTarget): string {
+  return target.taskTitle ? `${target.projectName} · ${target.taskTitle}` : target.projectName
+}

package/src/modules/staff/lib/time-tracking-ui/useBoardFilters.ts

@@ -0,0 +1,107 @@
+"use client"
+
+import * as React from 'react'
+import { EMPTY_BOARD_FILTERS, normalizeBoardFilters, type BoardFilters } from './boardFilters'
+
+/**
+ * Persisted board chrome (T3.8) — the spec's "Persistent context" principle applied to
+ * screen 6: a filter you set is still set when you come back to the board.
+ *
+ * Storage follows `timesheets-projects-ui/useProjectsViewMode.ts` verbatim rather than
+ * introducing a second mechanism for the same job: `localStorage`, guarded reads and
+ * writes, an optional `userKey` segment, and a lazy first read so a remount restores
+ * without a round-trip. Filters are additionally scoped by project, because "assigned to
+ * me on Nordvik" is not a statement about any other project's board.
+ */
+
+const FILTERS_STORAGE_KEY_PREFIX = 'staff.time_tracking.board.filters'
+const VIEW_STORAGE_KEY_PREFIX = 'staff.time_tracking.board.viewMode'
+
+export type BoardViewMode = 'board' | 'list'
+
+function storageKey(prefix: string, ...segments: Array<string | null | undefined>): string {
+  const parts = [prefix]
+  for (const segment of segments) {
+    if (segment) parts.push(segment)
+  }
+  return parts.join(':')
+}
+
+function readStored(key: string): unknown {
+  if (typeof window === 'undefined') return null
+  try {
+    const raw = window.localStorage.getItem(key)
+    if (!raw) return null
+    return JSON.parse(raw) as unknown
+  } catch {
+    return null
+  }
+}
+
+function writeStored(key: string, value: unknown): void {
+  if (typeof window === 'undefined') return
+  try {
+    window.localStorage.setItem(key, JSON.stringify(value))
+  } catch {
+    // ignore — quota errors etc. are non-critical
+  }
+}
+
+export function useBoardFilters({
+  timeProjectId,
+  userKey,
+}: {
+  timeProjectId: string | null | undefined
+  userKey?: string | null
+}): [BoardFilters, (next: BoardFilters) => void] {
+  const key = storageKey(FILTERS_STORAGE_KEY_PREFIX, timeProjectId, userKey)
+  const [filters, setFilters] = React.useState<BoardFilters>(() =>
+    normalizeBoardFilters(readStored(key)),
+  )
+  const keyRef = React.useRef(key)
+
+  React.useEffect(() => {
+    if (keyRef.current === key) return
+    keyRef.current = key
+    // Switching project (or identity) swaps which saved set is in force — it never
+    // carries the previous project's chips over.
+    setFilters(normalizeBoardFilters(readStored(key)))
+  }, [key])
+
+  const update = React.useCallback(
+    (next: BoardFilters) => {
+      const normalized = normalizeBoardFilters(next)
+      setFilters(normalized)
+      writeStored(key, normalized)
+    },
+    [key],
+  )
+
+  return [filters, update]
+}
+
+export function useBoardViewMode({
+  userKey,
+  fallback = 'board',
+}: {
+  userKey?: string | null
+  fallback?: BoardViewMode
+} = {}): [BoardViewMode, (next: BoardViewMode) => void] {
+  const key = storageKey(VIEW_STORAGE_KEY_PREFIX, userKey)
+  const [mode, setMode] = React.useState<BoardViewMode>(() => {
+    const stored = readStored(key)
+    return stored === 'board' || stored === 'list' ? stored : fallback
+  })
+
+  const update = React.useCallback(
+    (next: BoardViewMode) => {
+      setMode(next)
+      writeStored(key, next)
+    },
+    [key],
+  )
+
+  return [mode, update]
+}
+
+export { EMPTY_BOARD_FILTERS }

package/src/modules/staff/lib/time-tracking-ui/useTimesheetPreferences.ts

@@ -0,0 +1,245 @@
+"use client"
+
+import * as React from 'react'
+import { isTimesheetPeriodKind, type TimesheetPeriodKind } from './timesheetPeriod'
+
+/**
+ * "Filters (project, person, period) are remembered per user and come back next
+ * time" — screen 11 note 4, US-E2.
+ *
+ * Three inputs decide what the timesheet opens on, in this order:
+ *
+ *  1. **The query string** — `?period=` and `?view=` are the documented deep-link
+ *     contract for screens 11 and 12, so a shared URL must beat whatever this
+ *     browser happens to remember. An unparseable value is ignored rather than
+ *     thrown on: a hand-edited link degrades to the remembered preference.
+ *  2. **The remembered preference**, scoped to the signed-in staff member.
+ *  3. **The period-dependent default.**
+ *
+ * `userKey` is the caller's staff member id, which only exists once the page has
+ * resolved it. Reading the unscoped key first and writing BOTH keys keeps that
+ * late arrival free: the unscoped entry is a first-paint hint (whoever wrote
+ * last), the scoped entry is the truth, and for a browser with one user the two
+ * always agree — so the hydration that follows the id is a no-op and costs no
+ * reload. Two people sharing a browser converge on their own entry after the
+ * first render pass instead of sharing one set of filters forever.
+ *
+ * **The anchor day is deliberately NOT persisted.** A remembered week would
+ * reopen the timesheet on whatever week the user last looked at, which is wrong
+ * on Monday morning for everybody. The period *kind* is a preference; the period
+ * *instance* is context, and context starts at today.
+ */
+
+export type TimesheetView = 'calendar' | 'list' | 'grid'
+
+export type TimesheetPreferenceScope = {
+  /** Staff member id the preference belongs to; `null` until the page resolves it. */
+  userKey?: string | null
+}
+
+export type TimesheetPreferenceOptions = TimesheetPreferenceScope & {
+  /** Raw `?period=` / `?view=` value; anything unparseable is ignored. */
+  urlOverride?: string | null
+}
+
+const PERIOD_KEY_PREFIX = 'staff.time_tracking.timesheet.period'
+const VIEW_KEY_PREFIX = 'staff.time_tracking.timesheet.view'
+const PROJECT_KEY_PREFIX = 'staff.time_tracking.timesheet.projectId'
+const PERSON_KEY_PREFIX = 'staff.time_tracking.timesheet.staffMemberId'
+
+export const ALL_OPTION_VALUE = 'all'
+
+function storageKey(prefix: string, ...segments: Array<string | null | undefined>): string {
+  const parts = [prefix]
+  for (const segment of segments) {
+    if (segment) parts.push(segment)
+  }
+  return parts.join(':')
+}
+
+function readStored(key: string): string | null {
+  if (typeof window === 'undefined') return null
+  try {
+    return window.localStorage.getItem(key)
+  } catch {
+    return null
+  }
+}
+
+function writeStored(key: string, value: string): void {
+  if (typeof window === 'undefined') return
+  try {
+    window.localStorage.setItem(key, value)
+  } catch {
+    // ignore — quota errors etc. are non-critical
+  }
+}
+
+function readPreference<T>(
+  scopedKey: string,
+  sharedKey: string,
+  parse: (raw: string | null) => T | null,
+): T | null {
+  const scoped = parse(readStored(scopedKey))
+  if (scoped !== null) return scoped
+  if (scopedKey === sharedKey) return null
+  return parse(readStored(sharedKey))
+}
+
+function writePreference(scopedKey: string, sharedKey: string, value: string): void {
+  writeStored(scopedKey, value)
+  if (scopedKey !== sharedKey) writeStored(sharedKey, value)
+}
+
+export function isTimesheetView(value: unknown): value is TimesheetView {
+  return value === 'calendar' || value === 'list' || value === 'grid'
+}
+
+function parsePeriodKind(raw: string | null): TimesheetPeriodKind | null {
+  return isTimesheetPeriodKind(raw) ? raw : null
+}
+
+function parseView(raw: string | null): TimesheetView | null {
+  return isTimesheetView(raw) ? raw : null
+}
+
+/**
+ * Grid is the default for a week and the calendar for everything longer (the
+ * spec fixes both ends; a quarter and a year read like a month, only more of
+ * it). A week is the period people fill in, so it opens on the fastest surface
+ * for filling it in.
+ */
+export function defaultViewForPeriod(kind: TimesheetPeriodKind): TimesheetView {
+  return kind === 'week' ? 'grid' : 'calendar'
+}
+
+/**
+ * The grid is a bulk-entry surface: one column per day, typed across. That holds
+ * for a week and (tightly) for a month; ninety or three hundred and sixty five
+ * columns is not a grid anybody can fill in, so longer periods simply do not
+ * offer it.
+ */
+export function viewsForPeriod(kind: TimesheetPeriodKind): TimesheetView[] {
+  return kind === 'week' || kind === 'month'
+    ? ['calendar', 'list', 'grid']
+    : ['calendar', 'list']
+}
+
+/** The view actually rendered — a remembered choice the current period cannot honour falls back to its default. */
+export function resolveEffectiveView(kind: TimesheetPeriodKind, stored: TimesheetView): TimesheetView {
+  return viewsForPeriod(kind).includes(stored) ? stored : defaultViewForPeriod(kind)
+}
+
+export function usePersistedPeriodKind(
+  options: TimesheetPreferenceOptions = {},
+): [TimesheetPeriodKind, (next: TimesheetPeriodKind) => void] {
+  const { userKey, urlOverride } = options
+  const key = storageKey(PERIOD_KEY_PREFIX, userKey)
+  const sharedKey = storageKey(PERIOD_KEY_PREFIX)
+  const override = parsePeriodKind(urlOverride ?? null)
+
+  const [kind, setKind] = React.useState<TimesheetPeriodKind>(
+    () => override ?? readPreference(key, sharedKey, parsePeriodKind) ?? 'week',
+  )
+
+  // Back/forward and any other in-place URL change re-assert the link.
+  React.useEffect(() => {
+    if (override === null) return
+    setKind(override)
+  }, [override])
+
+  const keyRef = React.useRef(key)
+  React.useEffect(() => {
+    if (keyRef.current === key) return
+    keyRef.current = key
+    if (override !== null) return
+    setKind(readPreference(key, sharedKey, parsePeriodKind) ?? 'week')
+  }, [key, override, sharedKey])
+
+  const update = React.useCallback(
+    (next: TimesheetPeriodKind) => {
+      setKind(next)
+      writePreference(key, sharedKey, next)
+    },
+    [key, sharedKey],
+  )
+  return [kind, update]
+}
+
+/**
+ * The view is remembered PER PERIOD KIND, because the default is per period
+ * kind. Choosing the list for a month must not silently override the grid a week
+ * opens on, and vice versa.
+ *
+ * That is also why a period switch outranks `?view=`: the parameter described
+ * the period the link was made on, while the remembered choice is specific to
+ * the period now on screen.
+ */
+export function usePersistedView(
+  periodKind: TimesheetPeriodKind,
+  options: TimesheetPreferenceOptions = {},
+): [TimesheetView, (next: TimesheetView) => void] {
+  const { userKey, urlOverride } = options
+  const key = storageKey(VIEW_KEY_PREFIX, periodKind, userKey)
+  const sharedKey = storageKey(VIEW_KEY_PREFIX, periodKind)
+  const override = parseView(urlOverride ?? null)
+
+  const [view, setView] = React.useState<TimesheetView>(
+    () => override ?? readPreference(key, sharedKey, parseView) ?? defaultViewForPeriod(periodKind),
+  )
+
+  React.useEffect(() => {
+    if (override === null) return
+    setView(override)
+  }, [override])
+
+  const keyRef = React.useRef(key)
+  const periodRef = React.useRef(periodKind)
+  React.useEffect(() => {
+    if (keyRef.current === key) return
+    const periodChanged = periodRef.current !== periodKind
+    keyRef.current = key
+    periodRef.current = periodKind
+    if (override !== null && !periodChanged) return
+    setView(readPreference(key, sharedKey, parseView) ?? defaultViewForPeriod(periodKind))
+  }, [key, override, periodKind, sharedKey])
+
+  const update = React.useCallback(
+    (next: TimesheetView) => {
+      setView(next)
+      writePreference(key, sharedKey, next)
+    },
+    [key, sharedKey],
+  )
+  return [view, update]
+}
+
+export function usePersistedFilterValue(
+  kind: 'project' | 'person',
+  options: TimesheetPreferenceScope = {},
+): [string, (next: string) => void] {
+  const { userKey } = options
+  const prefix = kind === 'project' ? PROJECT_KEY_PREFIX : PERSON_KEY_PREFIX
+  const key = storageKey(prefix, userKey)
+  const sharedKey = storageKey(prefix)
+
+  const [value, setValue] = React.useState<string>(
+    () => readPreference(key, sharedKey, (raw) => raw) ?? ALL_OPTION_VALUE,
+  )
+
+  const keyRef = React.useRef(key)
+  React.useEffect(() => {
+    if (keyRef.current === key) return
+    keyRef.current = key
+    setValue(readPreference(key, sharedKey, (raw) => raw) ?? ALL_OPTION_VALUE)
+  }, [key, sharedKey])
+
+  const update = React.useCallback(
+    (next: string) => {
+      setValue(next)
+      writePreference(key, sharedKey, next)
+    },
+    [key, sharedKey],
+  )
+  return [value, update]
+}