@dsh-workbench/shared 0.3.4 → 0.3.5

package/src/lib/react.ts

@@ -2,21 +2,60 @@ import type * as ReactTypes from 'react';
 
 const react = require('react') as typeof ReactTypes;
 
+/**
+ * React 的 `createElement` 换个短名字再导出 —— 这套代码用 `h(...)` 写元素。
+ */
 export const h = react.createElement;
 
+/**
+ * React 的 `Fragment` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const Fragment = react.Fragment;
 
+/**
+ * React 的 `Component` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const Component = react.Component;
 
+/**
+ * React 的 `createContext` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const createContext = react.createContext;
+/**
+ * React 的 `useContext` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useContext = react.useContext;
 
+/**
+ * React 的 `useState` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useState = react.useState;
+/**
+ * React 的 `useEffect` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useEffect = react.useEffect;
+/**
+ * React 的 `useLayoutEffect` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useLayoutEffect = react.useLayoutEffect;
+/**
+ * React 的 `useMemo` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useMemo = react.useMemo;
+/**
+ * React 的 `useCallback` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useCallback = react.useCallback;
+/**
+ * React 的 `useRef` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useRef = react.useRef;
+/**
+ * React 的 `useSyncExternalStore` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useSyncExternalStore = react.useSyncExternalStore;
 
+/**
+ * 从 react 借来的三个类型（`ReactNode` / `CSSProperties` / `ChangeEvent`）—— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export type { ReactNode, CSSProperties, ChangeEvent } from 'react';

package/src/lib/text.ts

@@ -1,7 +1,18 @@
+/**
+ * 把一个值裹成 shell 里的单引号字面量（值里的单引号一并转义），保证元字符按字面量传递。
+ * @param value - 任意值；不是字符串的先 `String()`。
+ * @returns 可安全拼进 `/bin/sh -c` 的一段文本 —— 含空格 / `$()` / `;` / 通配符的值都不会被当成语法。
+ */
 export function quoteShellArg(value: unknown): string {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
 
+/**
+ * 取一段文本的末尾若干行（如命令输出），顺带去掉首尾空白。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @param lines - 最多留几行，默认 6；0 给全篇、负数从开头砍掉那么多行（都是 `slice` 语义），调用方传正数。
+ * @returns 末尾若干行、去首尾空行后的文本；原文行数不够就全给，空输入给空串。
+ */
 export function tailLines(text: string | null | undefined, lines = 6): string {
   const all = String(text ?? '')
     .trim()
@@ -24,6 +35,11 @@ function candidateStarts(raw: string): number[] {
   return starts;
 }
 
+/**
+ * 宽松解析一段前后可能夹着人话的 JSON：整段不通就从行首的 `[` / `{` 起、截到最后一个闭合符再试。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @returns 解析出的值（对象 / 数组 / 标量都原样）；空输入或怎么都解析不出给 `undefined`，调用方据此报「输出认不出」。
+ */
 export function parseJsonLoose(text: string | null | undefined): unknown {
   const raw = String(text ?? '').trim();
   if (!raw) return undefined;
@@ -48,6 +64,12 @@ const MARKDOWN_IMAGE = /!\[[^\]]*\]\([^)]*\)/g;
 const MARKDOWN_LINK = /\[([^\]]*)\]\([^)]*\)/g;
 const MARKDOWN_MARKS = /[*`_>#]/g;
 
+/**
+ * 把一段 Markdown 压成一行纯文本摘要：图片剥掉、链接只留可见文字、标记符号压成空格，超长按字符截断。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @param limit - 摘要最多多少字符，默认 80。
+ * @returns 单行摘要；没超限原样给，超了截到 `limit` 并补省略号（总长 `limit + 1`；第 `limit` 个字符是空白时会被 `trimEnd` 去掉、略短），空输入给空串。
+ */
 export function excerpt(text: string | null | undefined, limit = 80): string {
   const flat = String(text ?? '')
     .replace(MARKDOWN_IMAGE, ' ')

package/src/lib/ui.ts

@@ -1,3 +1,8 @@
+/**
+ * 拼类名：只留真值、用空格连接（`false` / `null` / `undefined` / 空串都丢掉）。
+ * @param parts - 若干类名或条件值。
+ * @returns 拼好的类字符串；一个真值都没有给空串。
+ */
 export function cx(...parts: Array<string | false | null | undefined>): string {
   return parts.filter(Boolean).join(' ');
 }
@@ -8,15 +13,30 @@ const DAY = 24 * HOUR;
 const MONTH = 30 * DAY;
 const YEAR = 365 * DAY;
 
+/**
+ * 时间文案取词：i18n 的 `(key, params) => 文案`；相对时间那几件都从它拿词。
+ */
 export type TimeTranslate = (key: string, params?: Record<string, unknown>) => string;
 
+/**
+ * 相对时间的档位名，对应词表里的 `time.short.*`。
+ */
 export type RelativeTimeUnit = 'now' | 'minutes' | 'hours' | 'days' | 'months' | 'years';
 
+/**
+ * 相对时间的一档：`unit` 是档位，`n` 是这一档的数量（单位随档位，见 `relativeTimeBucket`）。
+ */
 export interface RelativeTimeBucket {
   readonly unit: RelativeTimeUnit;
   readonly n: number;
 }
 
+/**
+ * 把时间戳按 dsh 的分档切成「刚刚 / N 分钟 / N 小时 / N 天 / N 月 / N 年」—— 30 天进月、365 天进年。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 档位与数量；时间戳或基准不是有限数给 `null`，未来时间钳到「刚刚」（`now` / 0）。
+ */
 export function relativeTimeBucket(epochMs: number, now: number = Date.now()): RelativeTimeBucket | null {
   if (!Number.isFinite(epochMs) || !Number.isFinite(now)) return null;
   const diff = Math.max(0, now - epochMs);
@@ -32,11 +52,25 @@ function bucketLabel(bucket: RelativeTimeBucket, t: TimeTranslate): string {
   return bucket.unit === 'now' ? t('time.now') : t(`time.short.${bucket.unit}`, { n: bucket.n });
 }
 
+/**
+ * 行内用的紧凑相对时间（「3 分钟」这种，不带「前」）。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 紧凑文案；时间戳非法给空串。
+ */
 export function relativeTimeCompact(epochMs: number, t: TimeTranslate, now?: number): string {
   const bucket = relativeTimeBucket(epochMs, now);
   return bucket === null ? '' : bucketLabel(bucket, t);
 }
 
+/**
+ * 悬停卡里用的相对时间（「3 分钟前」）；「刚刚」那一档不加「前」。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 带「前」的文案；时间戳非法给空串。
+ */
 export function relativeTimeAgo(epochMs: number, t: TimeTranslate, now?: number): string {
   const bucket = relativeTimeBucket(epochMs, now);
   if (bucket === null) return '';
@@ -44,6 +78,12 @@ export function relativeTimeAgo(epochMs: number, t: TimeTranslate, now?: number)
   return bucket.unit === 'now' ? label : t('time.ago', { t: label });
 }
 
+/**
+ * 会话行那一版相对时间：一小时内按分钟、一天内按小时、七天内按天，再久直接给绝对时间（到秒）。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @returns 文案；时间戳不是有限数给空串，未来时间落「刚刚」，七天及以上给本地化的年月日时分秒。
+ */
 export function relativeTime(epochMs: number, t: TimeTranslate): string {
   if (!Number.isFinite(epochMs)) return '';
   const diff = Date.now() - epochMs;
@@ -61,6 +101,11 @@ export function relativeTime(epochMs: number, t: TimeTranslate): string {
   });
 }
 
+/**
+ * 把 `/Users/<用户名>/…` 缩成 `~/…`，免得会话行里全是一样的长前缀。
+ * @param path - 任意值。
+ * @returns 缩好的路径；不在用户主目录下原样返回，不是字符串给空串。
+ */
 export function shortenPath(path: unknown): string {
   if (typeof path !== 'string') return '';
   const hit = path.match(/^\/Users\/[^/]+/);
@@ -69,6 +114,11 @@ export function shortenPath(path: unknown): string {
 
 const LOCAL_TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})$/;
 
+/**
+ * 解析不带时区的本地时间戳（`YYYY-MM-DD HH:mm:ss`，也接受 `T` 分隔），按本机时区换算。
+ * @param text - 原文；`null` / `undefined` 当空串；首尾空白容忍。
+ * @returns 毫秒时间戳；形态不认识给 `NaN`（调用方据此回退到原始字符串，宁可不换算也不显示错时间）。
+ */
 export function parseLocalTimestamp(text: string | null | undefined): number {
   const raw = String(text ?? '').trim();
   if (!LOCAL_TIMESTAMP.test(raw)) return Number.NaN;