@byline/admin 6.0.1 → 6.0.2

package/src/modules/admin-preferences/schemas.test.node.ts

@@ -6,11 +6,14 @@
  * Copyright (c) Infonomic Company Limited
  */
 
+import { ANALYTICS_DASHBOARD_PERIODS } from '@byline/analytics/config'
 import { describe, expect, it } from 'vitest'
 
 import {
+  analyticsViewPreferenceValueSchema,
   listViewPreferenceValueSchema,
   preferenceScopeSchema,
+  resolvePreferenceValueSchema,
   setPreferenceRequestSchema,
 } from './schemas.js'
 
@@ -52,6 +55,49 @@ describe('listViewPreferenceValueSchema', () => {
   })
 })
 
+describe('analyticsViewPreferenceValueSchema', () => {
+  it('accepts every period the dashboard offers', () => {
+    for (const period of ANALYTICS_DASHBOARD_PERIODS) {
+      expect(analyticsViewPreferenceValueSchema.safeParse({ period }).success).toBe(true)
+    }
+  })
+
+  it('rejects periods the dashboard does not offer', () => {
+    expect(analyticsViewPreferenceValueSchema.safeParse({ period: 45 }).success).toBe(false)
+    // The URL carries `?period=30`; the stored value is the parsed number.
+    expect(analyticsViewPreferenceValueSchema.safeParse({ period: '30' }).success).toBe(false)
+    expect(analyticsViewPreferenceValueSchema.safeParse({ period: 'lifetime' }).success).toBe(false)
+  })
+
+  it('rejects an empty payload and unknown keys', () => {
+    expect(analyticsViewPreferenceValueSchema.safeParse({}).success).toBe(false)
+    expect(analyticsViewPreferenceValueSchema.safeParse({ period: 7, page_size: 30 }).success).toBe(
+      false
+    )
+  })
+})
+
+describe('resolvePreferenceValueSchema', () => {
+  it('routes each registered scope family to its own value schema', () => {
+    expect(resolvePreferenceValueSchema('collections.docs.list')).toBe(
+      listViewPreferenceValueSchema
+    )
+    expect(resolvePreferenceValueSchema('collections.media-items.list')).toBe(
+      listViewPreferenceValueSchema
+    )
+    expect(resolvePreferenceValueSchema('analytics.dashboard')).toBe(
+      analyticsViewPreferenceValueSchema
+    )
+  })
+
+  it('returns undefined for an unregistered scope family', () => {
+    expect(resolvePreferenceValueSchema('collections.docs')).toBeUndefined()
+    expect(resolvePreferenceValueSchema('collections.docs.list.extra')).toBeUndefined()
+    expect(resolvePreferenceValueSchema('analytics')).toBeUndefined()
+    expect(resolvePreferenceValueSchema('made.up.scope')).toBeUndefined()
+  })
+})
+
 describe('setPreferenceRequestSchema', () => {
   it('requires both scope and a non-empty value', () => {
     expect(
@@ -64,4 +110,32 @@ describe('setPreferenceRequestSchema', () => {
       setPreferenceRequestSchema.safeParse({ scope: 'collections.docs.list', value: {} }).success
     ).toBe(false)
   })
+
+  it('validates the value against the schema its scope selects', () => {
+    expect(
+      setPreferenceRequestSchema.safeParse({
+        scope: 'analytics.dashboard',
+        value: { period: 'ytd' },
+      }).success
+    ).toBe(true)
+    // Each family rejects the other's keys — the point of keying by scope.
+    expect(
+      setPreferenceRequestSchema.safeParse({
+        scope: 'collections.docs.list',
+        value: { period: 'ytd' },
+      }).success
+    ).toBe(false)
+    expect(
+      setPreferenceRequestSchema.safeParse({
+        scope: 'analytics.dashboard',
+        value: { page_size: 30 },
+      }).success
+    ).toBe(false)
+  })
+
+  it('refuses to mint rows for an unregistered scope family', () => {
+    expect(
+      setPreferenceRequestSchema.safeParse({ scope: 'made.up.scope', value: { period: 7 } }).success
+    ).toBe(false)
+  })
 })

package/src/modules/admin-preferences/schemas.ts

@@ -12,12 +12,19 @@
  * Self-service, like admin-account: none of the request schemas accept a
  * user id — the command resolves the target from `actor.id`.
  *
- * The `value` payload is validated against the list-view shape because
- * that is the only registered scope family today
- * (`collections.<path>.list`). When a second scope family arrives, this
- * becomes a scope-keyed selection of value schemas.
+ * The `value` payload is validated against a schema chosen by the scope
+ * key, so each registered family enforces its own shape: a list scope
+ * takes only list keys, the analytics dashboard takes only a period. A
+ * scope matching no registered family is rejected on write, so a
+ * scripted caller cannot mint junk rows even under its own actor id.
+ * Reads are deliberately unconstrained — `getPreference` on an unknown
+ * scope simply finds nothing.
+ *
+ * Registering a third family is two lines: a value schema, and an entry
+ * in `PREFERENCE_VALUE_SCHEMAS`.
  */
 
+import { ANALYTICS_DASHBOARD_PERIODS } from '@byline/analytics/config'
 import { z } from 'zod'
 
 /** Dot-separated segment key, e.g. `collections.docs.list`. */
@@ -43,15 +50,85 @@ export const listViewPreferenceValueSchema = z
   .strict()
   .refine((v) => Object.keys(v).length > 0, { message: 'value cannot be empty' })
 
+/**
+ * Sticky analytics-dashboard keys. The period list is sourced from
+ * `@byline/analytics/config` rather than restated, so the stored value
+ * can only ever be one the dashboard actually offers — adding a sixth
+ * period there admits it here with no edit.
+ *
+ * Note the stored `period` is the *parsed* value (`30`, `'ytd'`), not
+ * the `?period=30` URL string the route validates on the way in.
+ */
+export const analyticsViewPreferenceValueSchema = z
+  .object({
+    period: z.union([
+      z.literal(ANALYTICS_DASHBOARD_PERIODS[0]),
+      z.literal(ANALYTICS_DASHBOARD_PERIODS[1]),
+      z.literal(ANALYTICS_DASHBOARD_PERIODS[2]),
+      z.literal(ANALYTICS_DASHBOARD_PERIODS[3]),
+      z.literal(ANALYTICS_DASHBOARD_PERIODS[4]),
+    ]),
+  })
+  .strict()
+
+/**
+ * The registered scope families, each a matcher over the scope key. A
+ * list scope carries the collection path as its middle segment, so it
+ * matches by shape; the analytics dashboard is a singleton and matches
+ * literally.
+ */
+const PREFERENCE_VALUE_SCHEMAS: ReadonlyArray<{
+  matches: (scope: string) => boolean
+  schema: z.ZodType
+}> = [
+  {
+    matches: (scope) => {
+      const segments = scope.split('.')
+      return segments.length === 3 && segments[0] === 'collections' && segments[2] === 'list'
+    },
+    schema: listViewPreferenceValueSchema,
+  },
+  {
+    matches: (scope) => scope === 'analytics.dashboard',
+    schema: analyticsViewPreferenceValueSchema,
+  },
+]
+
+/**
+ * The value schema a scope selects, or `undefined` when the scope
+ * belongs to no registered family. Exported so callers (and tests) can
+ * ask the same question the write path asks.
+ */
+export function resolvePreferenceValueSchema(scope: string): z.ZodType | undefined {
+  return PREFERENCE_VALUE_SCHEMAS.find((family) => family.matches(scope))?.schema
+}
+
 export const getPreferenceRequestSchema = z.object({
   scope: preferenceScopeSchema,
 })
 export type GetPreferenceRequest = z.infer<typeof getPreferenceRequestSchema>
 
-export const setPreferenceRequestSchema = z.object({
-  scope: preferenceScopeSchema,
-  value: listViewPreferenceValueSchema,
-})
+export const setPreferenceRequestSchema = z
+  .object({
+    scope: preferenceScopeSchema,
+    value: z.record(z.string(), z.unknown()),
+  })
+  .superRefine((input, ctx) => {
+    const schema = resolvePreferenceValueSchema(input.scope)
+    if (schema == null) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['scope'],
+        message: 'scope does not belong to a registered preference family',
+      })
+      return
+    }
+    const result = schema.safeParse(input.value)
+    if (result.success) return
+    for (const issue of result.error.issues) {
+      ctx.addIssue({ ...issue, path: ['value', ...issue.path] })
+    }
+  })
 export type SetPreferenceRequest = z.infer<typeof setPreferenceRequestSchema>
 
 /** `value` is `null` when the user has no stored preference for the scope. */

package/src/modules/analytics/components/dashboard.test.node.ts

@@ -14,6 +14,7 @@ import {
   bucketAnalyticsTimeseries,
   buildAnalyticsColumns,
   resolveAnalyticsChartGranularity,
+  resolveHoverCardPlacement,
 } from './timeseries.js'
 
 function day(date: string, views: number, visitors: number): AnalyticsSummaryDay {
@@ -191,3 +192,53 @@ describe('partialCoverageFrom', () => {
     expect(partialCoverageFrom('2025-01-01', null)).toBeUndefined()
   })
 })
+
+describe('resolveHoverCardPlacement', () => {
+  /** Columns as `buildAnalyticsColumns` lays them out, for `count` buckets. */
+  const columnsFor = (count: number, views: number[]) =>
+    buildAnalyticsColumns(views.map((v, i) => day(`2026-08-${10 + i}`, v, 0)).slice(0, count))
+
+  it('centres the card on an interior column', () => {
+    const columns = columnsFor(5, [10, 10, 10, 10, 10])
+    const placement = resolveHoverCardPlacement(columns[2]!)
+    // Third of five columns: centre of the plot.
+    expect(placement.leftPercent).toBeCloseTo(50)
+    expect(placement.align).toBe('center')
+  })
+
+  it('anchors the leading and trailing columns to the plot edges', () => {
+    const columns = columnsFor(5, [10, 10, 10, 10, 10])
+    expect(resolveHoverCardPlacement(columns[0]!).align).toBe('start')
+    expect(resolveHoverCardPlacement(columns[4]!).align).toBe('end')
+  })
+
+  it('centres a lone column rather than treating it as an edge', () => {
+    const columns = columnsFor(1, [10])
+    const placement = resolveHoverCardPlacement(columns[0]!)
+    expect(placement.leftPercent).toBeCloseTo(50)
+    expect(placement.align).toBe('center')
+  })
+
+  it('sits above a short column and flips below a tall one', () => {
+    // Against a ceiling of 100, a 10-view column is short and a 100-view
+    // column reaches the top of the plot — where a card above would clip.
+    const columns = columnsFor(3, [10, 100, 55])
+    expect(resolveHoverCardPlacement(columns[0]!).side).toBe('above')
+    expect(resolveHoverCardPlacement(columns[1]!).side).toBe('below')
+  })
+
+  it('reports the bar top as a percentage of plot height', () => {
+    const columns = columnsFor(2, [50, 100])
+    // Half-height column: its top is halfway down the plot.
+    expect(resolveHoverCardPlacement(columns[0]!).topPercent).toBeCloseTo(50)
+    // Full-height column: its top is the top of the plot.
+    expect(resolveHoverCardPlacement(columns[1]!).topPercent).toBeCloseTo(0)
+  })
+
+  it('keeps a zero-value column anchored on the baseline', () => {
+    const columns = columnsFor(2, [0, 10])
+    const placement = resolveHoverCardPlacement(columns[0]!)
+    expect(placement.topPercent).toBeCloseTo(100)
+    expect(placement.side).toBe('above')
+  })
+})

package/src/modules/analytics/components/timeseries.module.css

@@ -3,7 +3,9 @@
  *
  * Override handles:
  *   .byline-analytics-timeseries — the chart, axis, and readout as one block
+ *   .byline-analytics-plot       — the plot box (SVG + hover card)
  *   .byline-analytics-chart      — the SVG plot itself
+ *   .byline-analytics-hovercard  — the card shown over the hovered column
  *   .byline-analytics-axis       — first/last day labels beneath the plot
  *   .byline-analytics-readout    — hovered-day figures, or the range hint
  *
@@ -23,6 +25,13 @@
   outline-offset: 4px;
 }
 
+/* Positioning context for the hover card, so the card measures against the
+   plot rather than the whole block (which also holds the axis and readout). */
+.plot,
+:global(.byline-analytics-plot) {
+  position: relative;
+}
+
 .chart,
 :global(.byline-analytics-chart) {
   display: block;
@@ -30,6 +39,159 @@
   height: 11rem;
 }
 
+/* Hover card ------------------------------------------------------------
+   An HTML overlay rather than SVG: the plot is drawn with
+   preserveAspectRatio="none" and stretched to the container, so SVG text
+   inside it would be horizontally distorted (the same reason the axis
+   labels below are HTML).
+
+   Surfaces follow the admin's popover recipe (the tokens @byline/ui's
+   dropdown uses), so the card inherits both themes from the token layer
+   instead of needing its own dark-mode block. */
+.hoverCard,
+:global(.byline-analytics-hovercard) {
+  position: absolute;
+  z-index: 1;
+  display: grid;
+  gap: 0.125rem 0.5rem;
+  padding: 0.4rem 0.55rem;
+  background-color: var(--surface-panel-elevated);
+  border-width: var(--border-width-thin);
+  border-style: var(--border-style-solid);
+  border-color: var(--surface-panel-border);
+  border-radius: var(--border-radius-sm);
+  box-shadow: var(--shadow-sm);
+  font-size: 0.6875rem;
+  font-variant-numeric: tabular-nums;
+  line-height: 1.35;
+  white-space: nowrap;
+  /* The plot owns pointer tracking; the card must never intercept it or
+     hovering would flicker as the pointer crossed the card. */
+  pointer-events: none;
+
+  /* Resting state is hidden-and-just-below; `.hoverCardVisible` is the shown
+     state. The card stays mounted either way, because a transition needs a
+     previous state to animate from.
+
+     The lift rides on `translate` rather than `transform` so it composes with
+     the positioning transforms below instead of overwriting them — the two
+     properties multiply, and keeping them separate means the anchor maths and
+     the animation never have to know about each other.
+
+     The exit curve lives here and the entrance curve on the shown state: a
+     transition is read from the state being entered, so gaining the class
+     animates with the eased-out entrance and losing it with the quicker
+     ease-in exit.
+
+     On durations: the curve matters as much as the number. The popover
+     `cubic-bezier(0.16, 1, 0.3, 1)` puts both y control points at 1, so it is
+     ~88% complete at 30% of its duration — over a short transition that reads
+     as an instant pop no matter what the duration says. A plain `ease-out`
+     spends its time far more evenly (50% progress at ~34% of the time), so
+     the motion is actually visible. */
+  opacity: 0;
+  translate: 0 6px;
+  transition:
+    opacity 160ms ease-in,
+    translate 160ms ease-in;
+}
+
+.hoverCardVisible {
+  opacity: 1;
+  translate: 0 0;
+  transition:
+    opacity 240ms ease-out,
+    translate 240ms ease-out;
+}
+
+/* Horizontal anchoring. Interior columns centre; columns near an edge pin
+   that edge so the card cannot overhang the plot. */
+.hoverCard.center {
+  transform: translateX(-50%);
+}
+
+.hoverCard.start {
+  transform: translateX(-0.5rem);
+}
+
+.hoverCard.end {
+  transform: translateX(calc(-100% + 0.5rem));
+}
+
+/* Vertical side. `top` is the hovered bar's own top edge, so the card sits
+   just clear of the mark it describes. */
+.hoverCard.above {
+  margin-top: -0.5rem;
+}
+
+.hoverCard.above.center {
+  transform: translate(-50%, -100%);
+}
+
+.hoverCard.above.start {
+  transform: translate(-0.5rem, -100%);
+}
+
+.hoverCard.above.end {
+  transform: translate(calc(-100% + 0.5rem), -100%);
+}
+
+.hoverCard.below {
+  margin-top: 0.5rem;
+}
+
+.hoverCardDate {
+  color: var(--text);
+  font-weight: 600;
+  letter-spacing: 0.01em;
+}
+
+.hoverCardRow {
+  display: grid;
+  grid-template-columns: 0.625rem 1fr auto;
+  align-items: center;
+  gap: 0.4rem;
+}
+
+/* A short stroke, not a filled box: at this density a solid swatch is
+   data-weight ink doing a label's job. */
+.keyLine {
+  display: inline-block;
+  width: 0.625rem;
+  height: 2px;
+  border-radius: 1px;
+}
+
+.keyViews {
+  background-color: #38bdf8;
+  /* Matches `.columnActive .views`, not the resting fill: the card is only
+     ever on screen while its column is hovered, so the key should look like
+     the mark actually looks at that moment. A 2px line also carries far less
+     ink than the readout's filled swatch, so the same opacity would read
+     fainter here than it does there. */
+  opacity: 0.62;
+}
+
+.keyVisitors {
+  background-color: #7c3aed;
+}
+
+/* The reader already knows the series; they came for the number — so the
+   value carries the emphasis and the metric name recedes.
+
+   Muted ink here is the same `--gray-*` pair the axis and readout use, not
+   `--text-secondary`: in this theme that token resolves to the amber brand
+   secondary, which reads as emphasis rather than recession. */
+.hoverCardLabel {
+  color: var(--gray-500);
+}
+
+.hoverCardValue {
+  color: var(--text);
+  font-weight: 600;
+  text-align: right;
+}
+
 .gridline {
   stroke: var(--gray-200);
   stroke-width: 1;
@@ -120,7 +282,8 @@
 :is([data-theme="dark"], :global(.dark)) .axis,
 :is([data-theme="dark"], :global(.dark)) :global(.byline-analytics-axis),
 :is([data-theme="dark"], :global(.dark)) .readout,
-:is([data-theme="dark"], :global(.dark)) :global(.byline-analytics-readout) {
+:is([data-theme="dark"], :global(.dark)) :global(.byline-analytics-readout),
+:is([data-theme="dark"], :global(.dark)) .hoverCardLabel {
   color: var(--gray-400);
 }
 
@@ -128,7 +291,8 @@
   fill: #a78bfa;
 }
 
-:is([data-theme="dark"], :global(.dark)) .swatchVisitors {
+:is([data-theme="dark"], :global(.dark)) .swatchVisitors,
+:is([data-theme="dark"], :global(.dark)) .keyVisitors {
   background-color: #a78bfa;
 }
 
@@ -138,9 +302,18 @@
 
 @media (prefers-reduced-motion: reduce) {
   .column,
-  .views {
+  .views,
+  .hoverCard,
+  .hoverCardVisible {
     transition: none;
   }
+
+  /* No transition means the lift would read as a jump rather than motion, so
+     the card simply appears in place. */
+  .hoverCard,
+  .hoverCardVisible {
+    translate: none;
+  }
 }
 
 @media (max-width: 720px) {