@linxin666/dsh-usage 0.4.10 → 0.4.11

package/src/client/RangeBubble.tsx

@@ -0,0 +1,164 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/RangeBubble.tsx. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Coarse adjustment for a bounded number: resting the pointer on the control
+ * (or moving focus into it) raises a small bubble holding a slider across the
+ * field's whole range, so a large change is one drag instead of many presses
+ * or a retyped value. The control itself stays the precise entry.
+ *
+ * The bubble belongs to the anchor's subtree, so moving from the control onto
+ * the bubble never counts as leaving. It opens after a short rest and closes a
+ * moment after the pointer and focus have both gone, so crossing the control
+ * on the way elsewhere does not flash it. While a drag is in progress the
+ * bubble stays put even if the pointer strays off it.
+ *
+ * Dragging reports each value through `onInput`, so the field shows it live;
+ * releasing the thumb, or a key press on it, reports `onCommit` once. The
+ * bubble opens on the side of the control that has room inside the nearest
+ * scrolling ancestor, so a row near the top of a settings page does not hang
+ * its bubble under the page edge.
+ */
+
+import { useEffect, useRef, useState, type ChangeEvent, type CSSProperties, type KeyboardEvent, type ReactNode } from 'react'
+import css from './settings-card.module.css'
+
+/** Rest on the control before the bubble opens. */
+const OPEN_DELAY_MS = 220
+/** Grace after pointer and focus have left before the bubble closes. */
+const CLOSE_DELAY_MS = 200
+/** Room the bubble needs between the control and the scroller's edge. */
+const BUBBLE_ROOM_PX = 64
+
+/** Props of {@link RangeBubble}. */
+export interface RangeBubbleProps {
+  /** Lowest value the slider reaches. */
+  min: number
+  /** Highest value the slider reaches. */
+  max: number
+  /** Slider granularity. */
+  step: number
+  /** Current value; a value outside the range parks the thumb at the nearer end. */
+  value: number
+  /** Accessible name of the slider. */
+  label: string
+  /** Disables the bubble along with the control. */
+  disabled?: boolean
+  /** Each value while the thumb moves. */
+  onInput: (value: number) => void
+  /** The value the thumb was released on, once per drag or key press. */
+  onCommit: (value: number) => void
+  /** The precise control the bubble hangs off. */
+  children: ReactNode
+}
+
+/** The nearest ancestor that scrolls vertically, or the viewport's root. */
+function scroller(node: HTMLElement): HTMLElement {
+  for (let parent = node.parentElement; parent !== null; parent = parent.parentElement) {
+    const overflow = getComputedStyle(parent).overflowY
+    if (overflow === 'auto' || overflow === 'scroll') return parent
+  }
+  return node.ownerDocument.documentElement
+}
+
+/**
+ * Render the control with its coarse-adjustment bubble.
+ * @param props - the range, the value and the two report callbacks.
+ * @returns the anchor holding the control and the bubble.
+ */
+export function RangeBubble(props: RangeBubbleProps): ReactNode {
+  const { min, max, step, disabled = false } = props
+  const [open, setOpen] = useState(false)
+  const [side, setSide] = useState<'above' | 'below'>('above')
+  const [live, setLive] = useState<number | null>(null)
+  const anchorRef = useRef<HTMLDivElement | null>(null)
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  const hovered = useRef(false)
+  const focused = useRef(false)
+  const dragging = useRef(false)
+
+  useEffect(() => () => { clearTimeout(timer.current) }, [])
+  useEffect(() => {
+    if (disabled) {
+      clearTimeout(timer.current)
+      setOpen(false)
+    }
+  }, [disabled])
+
+  const show = (): void => {
+    const anchor = anchorRef.current
+    if (anchor !== null) {
+      const room = anchor.getBoundingClientRect().top - scroller(anchor).getBoundingClientRect().top
+      setSide(room >= BUBBLE_ROOM_PX ? 'above' : 'below')
+    }
+    setOpen(true)
+  }
+  const schedule = (): void => {
+    clearTimeout(timer.current)
+    if (disabled) return
+    if (hovered.current || focused.current || dragging.current) {
+      if (!open) timer.current = setTimeout(show, focused.current ? 0 : OPEN_DELAY_MS)
+      return
+    }
+    timer.current = setTimeout(() => { setOpen(false) }, CLOSE_DELAY_MS)
+  }
+
+  const commit = (value: number): void => {
+    dragging.current = false
+    setLive(null)
+    props.onCommit(value)
+    schedule()
+  }
+  const onChange = (event: ChangeEvent<HTMLInputElement>): void => {
+    const value = Number(event.target.value)
+    setLive(value)
+    props.onInput(value)
+  }
+  const onKeyUp = (event: KeyboardEvent<HTMLInputElement>): void => {
+    if (live !== null) commit(live)
+    if (event.key === 'Escape') {
+      clearTimeout(timer.current)
+      setOpen(false)
+    }
+  }
+  const shown = live ?? Math.min(max, Math.max(min, props.value))
+
+  return (
+    <div
+      ref={anchorRef}
+      className={css.rangeAnchor}
+      onPointerEnter={() => { hovered.current = true; schedule() }}
+      onPointerLeave={() => { hovered.current = false; schedule() }}
+      onFocus={() => { focused.current = true; schedule() }}
+      onBlur={(event) => {
+        if (event.currentTarget.contains(event.relatedTarget as Node | null)) return
+        focused.current = false
+        if (live !== null) commit(live)
+        else schedule()
+      }}
+    >
+      {props.children}
+      <div className={css.rangeBubble} data-open={open ? '' : undefined} data-side={side}>
+        <input
+          type="range"
+          className={css.rangeSlider}
+          min={min}
+          max={max}
+          step={step}
+          value={shown}
+          aria-label={props.label}
+          tabIndex={open ? 0 : -1}
+          disabled={disabled}
+          style={{ '--range-fill': `${((shown - min) / (max - min)) * 100}%` } as CSSProperties}
+          onPointerDown={() => { dragging.current = true }}
+          onPointerUp={(event) => { commit(Number(event.currentTarget.value)) }}
+          onPointerCancel={(event) => { commit(Number(event.currentTarget.value)) }}
+          onChange={onChange}
+          onKeyUp={onKeyUp}
+        />
+        <span className={css.rangeEnds} aria-hidden="true">
+          <span>{min}</span>
+          <span>{max}</span>
+        </span>
+      </div>
+    </div>
+  )
+}

package/src/client/SegmentGroup.tsx

@@ -0,0 +1,93 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/SegmentGroup.tsx. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * The family's segmented control: a quiet track whose options share one
+ * highlight that slides to the pressed option, instead of each option fading
+ * its own background out and the next one in. The settings fields' small
+ * choices and the Web Extensions TAB strip both render through it, so the two
+ * read as one control.
+ *
+ * The caller builds the option buttons and marks the pressed one with
+ * `data-active`; the group measures that button after every render and writes
+ * its box as four custom properties, and the stylesheet draws the highlight
+ * there (`.segmentGroup[data-pill]::before`). Attribute and first placement
+ * land in the same task, so the highlight appears in place and only later
+ * changes slide. A ResizeObserver re-measures when the group or an option
+ * changes size: a longer locale, a font arriving, a container growing, a
+ * strip wrapping onto a second line.
+ */
+
+import { Children, useLayoutEffect, useRef, type HTMLAttributes, type ReactNode } from 'react'
+import css from './settings-card.module.css'
+
+/** The attribute marking a group whose highlight has been placed. */
+const PILL_ATTR = 'data-pill'
+/** The pressed option, relative to the group. */
+const ACTIVE_SELECTOR = ':scope > [data-active]'
+const PILL_PROPERTIES = ['--segment-pill-x', '--segment-pill-y', '--segment-pill-w', '--segment-pill-h'] as const
+
+/** Props of {@link SegmentGroup}: the track's own attributes and the option buttons. */
+export interface SegmentGroupProps extends HTMLAttributes<HTMLDivElement> {
+  /** The option buttons; the pressed one carries `data-active`. */
+  children: ReactNode
+}
+
+/**
+ * Write the highlight's box from the pressed option's box, or take the
+ * highlight off when nothing is pressed or the group has no layout yet.
+ * The two boxes are read in viewport pixels and turned back into the group's
+ * own CSS pixels, so a dialog that opens through a scale transform still
+ * lands the highlight on its option.
+ */
+function placePill(group: HTMLElement): void {
+  const item = group.querySelector<HTMLElement>(ACTIVE_SELECTOR)
+  const box = group.getBoundingClientRect()
+  if (item === null || group.offsetWidth === 0 || box.width === 0) {
+    group.removeAttribute(PILL_ATTR)
+    for (const property of PILL_PROPERTIES) group.style.removeProperty(property)
+    return
+  }
+  const scale = box.width / group.offsetWidth
+  const itemBox = item.getBoundingClientRect()
+  const values = [
+    (itemBox.left - box.left) / scale - group.clientLeft,
+    (itemBox.top - box.top) / scale - group.clientTop,
+    itemBox.width / scale,
+    itemBox.height / scale,
+  ]
+  values.forEach((value, index) => {
+    group.style.setProperty(PILL_PROPERTIES[index], `${Math.round(value * 100) / 100}px`)
+  })
+  if (!group.hasAttribute(PILL_ATTR)) group.setAttribute(PILL_ATTR, '')
+}
+
+/**
+ * Render a segmented track around the caller's option buttons.
+ * @param props - the track's attributes (role, accessible name, key handler) and its options.
+ * @returns the track.
+ */
+export function SegmentGroup(props: SegmentGroupProps): ReactNode {
+  const { children, className, ...rest } = props
+  const group = useRef<HTMLDivElement | null>(null)
+  const count = Children.count(children)
+
+  // Placed before the frame is painted, after every render: a press moves the
+  // pressed mark and the highlight follows it in the same frame.
+  useLayoutEffect(() => {
+    if (group.current !== null) placePill(group.current)
+  })
+
+  useLayoutEffect(() => {
+    const element = group.current
+    if (element === null || typeof ResizeObserver === 'undefined') return undefined
+    const observer = new ResizeObserver(() => { placePill(element) })
+    observer.observe(element)
+    for (const item of Array.from(element.children)) observer.observe(item)
+    return () => { observer.disconnect() }
+  }, [count])
+
+  return (
+    <div {...rest} ref={group} className={className === undefined ? css.segmentGroup : `${css.segmentGroup} ${className}`}>
+      {children}
+    </div>
+  )
+}

package/src/client/UsagePage.tsx

@@ -0,0 +1,108 @@
+/**
+ * The usage page's card chrome: the family settings card whose header holds
+ * the plugin switch, and the display rows the body closes with.
+ * @module @linxin666/dsh-usage/client/UsagePage
+ */
+
+import type { ReactNode } from 'react'
+import { t } from './locales.ts'
+import styles from './usage.module.css'
+import { ChoiceField, PluginSettingsCard, ToggleSwitch, ValueField } from './PluginSettingsCard.tsx'
+import { POLL_INTERVAL_RANGE, SPEND_CURRENCIES, type UsageSettingsCardFace, type UsageSettingsCardState } from './usage-settings-card.ts'
+
+/**
+ * The page's card: the plugin switch in the header, the statistics and the
+ * display rows in the body. A switched-off plugin keeps only the header, whose
+ * line says how to bring it back; a refused write keeps the body, so the
+ * failure line under the rows stays readable.
+ */
+export function UsagePage(props: { card: UsageSettingsCardState; face: UsageSettingsCardFace; enabled: boolean; children: ReactNode }): ReactNode {
+  const { card, face, enabled } = props
+  return (
+    <ul className={styles.sectionList} data-dsh-plugin="usage">
+      <PluginSettingsCard
+        t={t}
+        titleKey="usage.title"
+        titleId="settings-usage-title"
+        descriptionKey={enabled ? 'usage.description' : 'usage.disabled'}
+        headerAction={card.exposed
+          ? (
+            <ToggleSwitch
+              labelledBy="settings-usage-title"
+              checked={enabled}
+              disabled={!card.writable}
+              onChange={(next) => { face.edit('enabled', String(next)) }}
+            />
+          )
+          : undefined}
+        headerOnly={!enabled && !card.failed}
+        state={card}
+        alwaysOpen
+        renderChildrenWhenNotExposed
+        hideNotExposedNotice
+        onSave={face.save}
+        onDiscard={face.discard}
+      >
+        {props.children}
+        {card.exposed ? <SettingsRows card={card} face={face} /> : null}
+      </PluginSettingsCard>
+    </ul>
+  )
+}
+
+/**
+ * The display rows under the statistics. Each control writes through the card
+ * form: the currency pick at once, a typed number after a pause or on Enter.
+ * The rate only matters while spend shows in dollars, so it appears then.
+ */
+function SettingsRows(props: { card: UsageSettingsCardState; face: UsageSettingsCardFace }): ReactNode {
+  const { card, face } = props
+  const fieldProps = {
+    overriddenLabel: t('settings.overridden'),
+    resetLabel: t('settings.reset'),
+    invalidLabel: t('settings.invalidNumber'),
+    disabled: !card.writable,
+  }
+  return (
+    <section className={styles.settingsGroup} aria-labelledby="settings-usage-display-title" data-dsh-part="settings-rows">
+      <h3 className={styles.groupTitle} id="settings-usage-display-title">{t('usage.config.title')}</h3>
+      <ValueField
+        id="settings-usage-poll-interval"
+        label={t('usage.config.pollIntervalSec')}
+        hint={t('usage.config.pollIntervalHint')}
+        numeric
+        range={POLL_INTERVAL_RANGE}
+        {...fieldProps}
+        {...card.pollIntervalSec}
+        onEdit={(text) => { face.edit('pollIntervalSec', text) }}
+        onReset={() => { face.resetField('pollIntervalSec') }}
+      />
+      <ChoiceField
+        id="settings-usage-spend-currency"
+        label={t('usage.config.spendCurrency')}
+        hint={t('usage.config.spendCurrencyHint')}
+        inheritLabel={t('settings.inherit')}
+        presentation="segment"
+        choices={SPEND_CURRENCIES.map(currency => ({ value: currency, label: currency }))}
+        {...fieldProps}
+        {...card.spendCurrency}
+        onEdit={(text) => { face.edit('spendCurrency', text) }}
+        onReset={() => { face.resetField('spendCurrency') }}
+      />
+      {card.spendCurrency.text === 'USD'
+        ? (
+          <ValueField
+            id="settings-usage-cny-per-usd"
+            label={t('usage.config.cnyPerUsd')}
+            hint={t('usage.config.cnyPerUsdHint')}
+            numeric
+            {...fieldProps}
+            {...card.cnyPerUsd}
+            onEdit={(text) => { face.edit('cnyPerUsd', text) }}
+            onReset={() => { face.resetField('cnyPerUsd') }}
+          />
+        )
+        : null}
+    </section>
+  )
+}