@monkey-mini-app/ui 0.1.0 → 0.1.4

package/dist/src/composites/date-range-picker.tsx

@@ -5,6 +5,9 @@ import { format, isSameMonth, isSameYear, type Locale } from "date-fns"
 import type { DateRange } from "react-day-picker"
 import { ChevronDown } from "lucide-react"
 
+// Re-exported so mini-app authors (bare `@monkey-mini-app/ui` only) can type the value.
+export type { DateRange }
+
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 import { useDateLocale, useLabels } from "@monkey-mini-app/ui/i18n/context"
 import { Button } from "@monkey-mini-app/ui/components/button"
@@ -41,6 +44,7 @@ function rangeLabel(value: DateRange, locale: Locale) {
  * @when Filters needing from/to calendar days
  * @example
  * <DateRangePicker value={range} onChange={setRange} />
+ * @family Calendar & date
  */
 export function DateRangePicker({
   value,

package/dist/src/composites/date-time-picker.tsx

@@ -32,6 +32,13 @@ export type DateTimePickerProps = {
   className?: string
 }
 
+/**
+ * Date + time, optional timezone.
+ * @when Scheduling moments, not days.
+ * @example
+ * <DateTimePicker value={d} onChange={(v) => set(v)} />
+ * @family Calendar & date
+ */
 export function DateTimePicker({
   value,
   onChange,

package/dist/src/composites/date-time-range-picker.tsx

@@ -7,6 +7,13 @@ import { useLabels } from "@monkey-mini-app/ui/i18n/context"
 
 export type DateTimeRange = { start?: Date; end?: Date }
 
+/**
+ * From/to moments, all-day toggle.
+ * @when Run windows, on-call shifts.
+ * @example
+ * <DateTimeRangePicker onChange={(r) => set(r)} />
+ * @family Calendar & date
+ */
 export function DateTimeRangePicker({
   value,
   onChange,

package/dist/src/composites/duration-input.tsx

@@ -81,6 +81,13 @@ function Segment({
   )
 }
 
+/**
+ * Duration text field (e.g. `1h30m`) with minutes.
+ * @when Timeouts/estimates where you store minutes but type human units.
+ * @example
+ * <DurationInput value="45m" onChange={(v, min) => set(min)} />
+ * @family Calendar & date
+ */
 export function DurationInput({
   value,
   onChange,

package/dist/src/composites/mini-calendar.tsx

@@ -3,6 +3,13 @@
 import { Calendar } from "@monkey-mini-app/ui/components/calendar"
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Compact month grid, day cell only.
+ * @when Inside a popover or sidebar. Full page with events → `EventCalendar`.
+ * @example
+ * <MiniCalendar value={d} onChange={(v) => set(v)} />
+ * @family Calendar & date
+ */
 export function MiniCalendar({
   value,
   onChange,

package/dist/src/composites/number-field.tsx

@@ -5,6 +5,13 @@ import { Input } from "@monkey-mini-app/ui/components/input"
 import { Minus, Plus } from "lucide-react"
 import { useLabels } from "@monkey-mini-app/ui/i18n/context"
 
+/**
+ * Numeric input with min/max/step + steppers.
+ * @when Any number the user edits — keeps NaN out of your state.
+ * @example
+ * <NumberField min={0} max={100} value={n} onChange={(v) => set(v)} />
+ * @family Form
+ */
 export function NumberField({
   value = 0,
   onChange,

package/dist/src/composites/password-field.tsx

@@ -11,6 +11,13 @@ import {
 } from "@monkey-mini-app/ui/components/input-group"
 import { useLabels } from "@monkey-mini-app/ui/i18n/context"
 
+/**
+ * Secret input with reveal toggle.
+ * @when Typing a token/password into your own state. **Never** persist it to storage.
+ * @example
+ * <PasswordField value={p} onChange={(v) => set(v)} />
+ * @family Form
+ */
 export function PasswordField({
   value,
   onChange,

package/dist/src/composites/phone-input.tsx

@@ -2,6 +2,13 @@
 
 import { Input } from "@monkey-mini-app/ui/components/input"
 
+/**
+ * Phone number input with formatting.
+ * @when CN/mobile numbers.
+ * @example
+ * <PhoneInput value={t} onChange={(v) => set(v)} />
+ * @family Form
+ */
 export function PhoneInput({
   value,
   onChange,

package/dist/src/composites/rating.tsx

@@ -4,6 +4,13 @@ import { Star } from "lucide-react"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Star rating.
+ * @when Feedback/score capture, 1–max.
+ * @example
+ * <Rating value={r} onChange={(v) => set(v)} />
+ * @family Form
+ */
 export function Rating({
   value = 0,
   onChange,

package/dist/src/composites/relative-date-picker.tsx

@@ -18,6 +18,13 @@ function rangeFor(id: RelativePreset): DateRange | undefined {
   return undefined
 }
 
+/**
+ * Preset ranges (today / last 7 days) → a concrete date range.
+ * @when Dashboard filters where “last 7 days” beats two calendars.
+ * @example
+ * <RelativeDatePicker onChange={(range, preset) => set(range)} />
+ * @family Calendar & date
+ */
 export function RelativeDatePicker({
   preset = "7d",
   value,

package/dist/src/composites/search-input.tsx

@@ -10,6 +10,13 @@ import {
 } from "@monkey-mini-app/ui/components/input-group"
 import { useLabels } from "@monkey-mini-app/ui/i18n/context"
 
+/**
+ * Search box with debounce.
+ * @when Filter-as-you-type against `DataGrid`/lists — use `onDebouncedChange` for network calls.
+ * @example
+ * <SearchInput onDebouncedChange={(q) => call("list", { q })} />
+ * @family Form
+ */
 export function SearchInput({
   value,
   onChange,

package/dist/src/composites/slider-range.tsx

@@ -2,6 +2,13 @@
 
 import { Slider } from "@monkey-mini-app/ui/components/slider"
 
+/**
+ * Two-thumb range slider.
+ * @when min/max numeric filters.
+ * @example
+ * <SliderRange min={0} max={100} value={[10, 40]} onChange={(v) => set(v)} />
+ * @family Form
+ */
 export function SliderRange({
   value = [20, 80],
   onChange,

package/dist/src/composites/tag-input.tsx

@@ -7,6 +7,13 @@ import { Badge } from "@monkey-mini-app/ui/components/badge"
 import { Input } from "@monkey-mini-app/ui/components/input"
 import { useLabels } from "@monkey-mini-app/ui/i18n/context"
 
+/**
+ * Chip-style multi-value text input.
+ * @when Labels/owners where free values are allowed (`Transfer` when choosing from a fixed pool).
+ * @example
+ * <TagInput value={tags} onChange={(v) => set(v)} />
+ * @family Form
+ */
 export function TagInput({
   value = [],
   onChange,

package/dist/src/composites/time-picker.tsx

@@ -26,6 +26,11 @@ function parseTime(value: string) {
   }
 }
 
+/**
+ * Column wheel for picking a time value.
+ * @family Calendar & date
+ * @when Inside a time picker where tapping a list beats typing. Prefer `TimePicker` for a normal field.
+ */
 export function TimeWheel({
   values,
   value,
@@ -140,7 +145,12 @@ export type TimePickerProps = {
   className?: string
 }
 
-/** `value` is `HH:mm` (24h). */
+/** `value` is `HH:mm` (24h).
+ * @when Clock-only fields. `value` is a string, not a Date.
+ * @example
+ * <TimePicker value="09:30" onChange={(v) => set(v)} />
+ * @family Calendar & date
+ */
 export function TimePicker({
   value = "",
   onChange,

package/dist/src/composites/time-range-picker.tsx

@@ -5,6 +5,13 @@ import { useLabels } from "@monkey-mini-app/ui/i18n/context"
 
 export type TimeRange = { start: string; end: string }
 
+/**
+ * From/to time of day.
+ * @when Daily windows (maintenance 02:00–04:00).
+ * @example
+ * <TimeRangePicker onChange={(r) => set(r)} />
+ * @family Calendar & date
+ */
 export function TimeRangePicker({
   value,
   onChange,

package/dist/src/composites/timezone-select.tsx

@@ -141,6 +141,13 @@ function ZoneItem({
   )
 }
 
+/**
+ * IANA timezone dropdown.
+ * @when Pair with `DateTimePicker` when data is UTC.
+ * @example
+ * <TimezoneSelect value={tz} onChange={(v) => set(v)} />
+ * @family Calendar & date
+ */
 export function TimezoneSelect({
   value,
   onChange,

package/dist/src/composites/transfer.tsx

@@ -4,6 +4,13 @@ import { Button } from "@monkey-mini-app/ui/components/button"
 
 export type TransferItem = { id: string; label: string }
 
+/**
+ * Two-panel move-between-lists picker.
+ * @when Selecting many items from a known pool (assign users to a shift).
+ * @example
+ * <Transfer items={[{ id: "u1", label: "张三" }]} onChange={(ids) => set(ids)} />
+ * @family Form
+ */
 export function Transfer({
   items,
   value = [],

package/dist/src/composites/user-picker.tsx

@@ -6,6 +6,13 @@ import { useLabels } from "@monkey-mini-app/ui/i18n/context"
 
 export type UserOption = { id: string; name: string }
 
+/**
+ * Pick a user from a list (avatar + name).
+ * @when Assignee/owner fields; you supply the user list.
+ * @example
+ * <UserPicker users={[{ id: "u1", name: "张三" }]} onChange={(id) => set(id)} />
+ * @family Form
+ */
 export function UserPicker({
   users,
   value,

package/dist/src/hooks/use-html-dark.ts

@@ -0,0 +1,37 @@
+"use client"
+
+import { useEffect, useState } from "react"
+
+/** True when the iframe/host document is in dark mode (class, data-theme, or --background). */
+export function htmlIsDark(el?: HTMLElement | null): boolean {
+  if (typeof document === "undefined") return false
+  const root = el ?? document.documentElement
+  if (root.classList.contains("dark")) return true
+  if (root.classList.contains("light")) return false
+  const theme = root.getAttribute("data-theme")
+  if (theme === "dark") return true
+  if (theme === "light") return false
+  try {
+    const bg =
+      root.style.getPropertyValue("--background").trim() ||
+      getComputedStyle(root).getPropertyValue("--background").trim()
+    const oklch = bg.match(/oklch\(\s*([0-9.]+)/i)
+    if (oklch) return Number(oklch[1]) < 0.5
+  } catch {
+    /* jsdom */
+  }
+  return false
+}
+
+export function useHtmlDark(): boolean {
+  const [dark, setDark] = useState(() => htmlIsDark())
+  useEffect(() => {
+    const el = document.documentElement
+    const read = () => setDark(htmlIsDark(el))
+    read()
+    const obs = new MutationObserver(read)
+    obs.observe(el, { attributes: true, attributeFilter: ["class", "data-theme", "style"] })
+    return () => obs.disconnect()
+  }, [])
+  return dark
+}

package/dist/src/hooks/use-mobile.ts

@@ -6,6 +6,9 @@ export function useIsMobile() {
   const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
 
   React.useEffect(() => {
+    // SSR, node-render harnesses and bare jsdom have no matchMedia; a layout hook must not be
+    // the reason a view throws. Treat "unknown" as wide.
+    if (typeof window.matchMedia !== "function") return
     const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
     const onChange = () => {
       setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)

package/dist/src/i18n/en.ts

@@ -79,13 +79,39 @@ export const en = {
     month: "Month",
     week: "Week",
     day: "Day",
+    year: "Year",
+    agenda: "Agenda",
+    noEvents: "No events in this range",
+    happeningNow: "Happening now",
+    noAppointments: "No appointments or consultations at the moment",
     allDay: "All day",
     newEvent: "New event",
     editEvent: "Edit event",
+    addEvent: "Add Event",
     eventTitle: "Event title",
+    titlePlaceholder: "Title",
+    descriptionPlaceholder: "Description",
+    start: "Start",
+    end: "End",
     save: "Save",
+    saveChanges: "Save Changes",
+    createEvent: "Create Event",
     delete: "Delete",
     more: (count: number) => `+${count} more`,
+    eventsCount: (count: number) => `${count} events`,
+    allUsers: "All",
+    selectUser: "Select a user",
+    clearFilter: "Clear Filter",
+    settings: "Calendar settings",
+    settingsAria: "Calendar settings",
+    useDotBadge: "Use dot badge",
+    use24Hour: "Use 24 hour format",
+    scrollHour: "Scroll hour",
+    agendaGroupBy: "Agenda view group by",
+    groupByDate: "Date",
+    groupByColor: "Color",
+    searchAgenda: "Type a command or search...",
+    formatError: "Error while formatting",
     weekdays: ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] as [
       string,
       string,
@@ -95,6 +121,15 @@ export const en = {
       string,
       string,
     ],
+    weekdaysSun: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"] as [
+      string,
+      string,
+      string,
+      string,
+      string,
+      string,
+      string,
+    ],
   },
   dataGrid: {
     search: "Search…",
@@ -163,6 +198,78 @@ export const en = {
   jqlInput: {
     placeholder: "project = TMS AND status = Open",
   },
-}
+  logViewer: {
+    title: "Logs",
+    search: "Search",
+    closeSearch: "Close search",
+    pauseScroll: "Pause auto-scroll",
+    resumeScroll: "Resume auto-scroll",
+    copyAll: "Copy all logs",
+    copied: "Copied",
+    download: "Download logs",
+    clear: "Clear logs",
+    filterPlaceholder: "Filter logs…",
+    clearSearch: "Clear search",
+    empty: "No log entries.",
+    emptySearch: "No matching log entries.",
+    newBelow: "New logs below",
+    scrollLatest: "Scroll to latest",
+    lines: (n: number) => `${n} lines`,
+    linesFiltered: (shown: number, total: number) =>
+      `${shown} / ${total} lines`,
+  },
+  envTable: {
+    empty: "No environment variables.",
+    hideAll: "Hide all",
+    revealAll: "Reveal all",
+    hideAllValues: "Hide all values",
+    revealAllValues: "Reveal all values",
+    copyEnv: "Copy .env",
+    copied: "Copied!",
+    hideKey: (key: string) => `Hide ${key}`,
+    revealKey: (key: string) => `Reveal ${key}`,
+    copyValue: (key: string) => `Copy ${key} value`,
+  },
+  commitGraph: {
+    empty: "No commits.",
+    parent: "Parent",
+    parents: "Parents",
+    justNow: "just now",
+    minutesAgo: (n: number) => `${n}m ago`,
+    hoursAgo: (n: number) => `${n}h ago`,
+    daysAgo: (n: number) => `${n}d ago`,
+  },
+  appError: {
+    title: "This mini-app hit an error",
+    renderHint:
+      "A component threw while rendering. Nothing else in the panel is affected.",
+    moduleHint: "The UI bundle did not load — it usually needs recompiling.",
+    uncaughtHint: "An unhandled error stopped this view.",
+    asyncHint: "A background task failed without being handled.",
+    retry: "Retry",
+    details: "Show details",
+    hideDetails: "Hide details",
+    reported: "Reported to the host",
+  },
+  listDetail: {
+    back: "Back to list",
+  },
+  formSheet: {
+    discardTitle: "Discard these changes?",
+    discardBody: "They have not been saved. Closing now throws them away.",
+    keepEditing: "Keep editing",
+    discard: "Discard",
+  },
+  wizardShell: {
+    back: "Back",
+    next: "Next",
+    finish: "Finish",
+    working: "Working…",
+    stepOf: (n: number, total: number) => `Step ${n} of ${total}`,
+  },
+  settingsSplit: {
+    nav: "Section navigation",
+  },
+};
 
-export type UiMessages = typeof en
+export type UiMessages = typeof en;

package/dist/src/i18n/zh.ts

@@ -1,4 +1,4 @@
-import type { UiMessages } from "./en"
+import type { UiMessages } from "./en";
 
 export const zh: UiMessages = {
   common: {
@@ -81,14 +81,41 @@ export const zh: UiMessages = {
     month: "月",
     week: "周",
     day: "日",
+    year: "年",
+    agenda: "议程",
+    noEvents: "这段时间没有事件",
+    happeningNow: "正在进行",
+    noAppointments: "此刻没有预约或日程",
     allDay: "全天",
     newEvent: "新建事件",
     editEvent: "编辑事件",
+    addEvent: "添加事件",
     eventTitle: "事件标题",
+    titlePlaceholder: "标题",
+    descriptionPlaceholder: "描述",
+    start: "开始",
+    end: "结束",
     save: "保存",
+    saveChanges: "保存更改",
+    createEvent: "创建事件",
     delete: "删除",
     more: (count: number) => `还有 ${count} 项`,
+    eventsCount: (count: number) => `${count} 个事件`,
+    allUsers: "全部",
+    selectUser: "选择用户",
+    clearFilter: "清除筛选",
+    settings: "日历设置",
+    settingsAria: "日历设置",
+    useDotBadge: "使用圆点标记",
+    use24Hour: "使用 24 小时制",
+    scrollHour: "起始小时",
+    agendaGroupBy: "议程分组方式",
+    groupByDate: "日期",
+    groupByColor: "颜色",
+    searchAgenda: "搜索事件…",
+    formatError: "日期格式化失败",
     weekdays: ["一", "二", "三", "四", "五", "六", "日"],
+    weekdaysSun: ["日", "一", "二", "三", "四", "五", "六"],
   },
   dataGrid: {
     search: "搜索…",
@@ -157,4 +184,74 @@ export const zh: UiMessages = {
   jqlInput: {
     placeholder: "project = TMS AND status = Open",
   },
-}
+  logViewer: {
+    title: "日志",
+    search: "搜索",
+    closeSearch: "关闭搜索",
+    pauseScroll: "暂停自动滚动",
+    resumeScroll: "恢复自动滚动",
+    copyAll: "复制全部日志",
+    copied: "已复制",
+    download: "下载日志",
+    clear: "清空日志",
+    filterPlaceholder: "过滤日志…",
+    clearSearch: "清除搜索",
+    empty: "暂无日志。",
+    emptySearch: "没有匹配的日志。",
+    newBelow: "下方有新日志",
+    scrollLatest: "滚到最新",
+    lines: (n: number) => `${n} 行`,
+    linesFiltered: (shown: number, total: number) => `${shown} / ${total} 行`,
+  },
+  envTable: {
+    empty: "没有环境变量。",
+    hideAll: "全部隐藏",
+    revealAll: "全部显示",
+    hideAllValues: "隐藏全部值",
+    revealAllValues: "显示全部值",
+    copyEnv: "复制 .env",
+    copied: "已复制！",
+    hideKey: (key: string) => `隐藏 ${key}`,
+    revealKey: (key: string) => `显示 ${key}`,
+    copyValue: (key: string) => `复制 ${key} 的值`,
+  },
+  commitGraph: {
+    empty: "没有提交。",
+    parent: "父提交",
+    parents: "父提交",
+    justNow: "刚刚",
+    minutesAgo: (n: number) => `${n} 分钟前`,
+    hoursAgo: (n: number) => `${n} 小时前`,
+    daysAgo: (n: number) => `${n} 天前`,
+  },
+  appError: {
+    title: "这个小程序出错了",
+    renderHint: "某个组件在渲染时抛出异常，面板其他部分不受影响。",
+    moduleHint: "UI 代码没有加载成功，通常需要重新编译。",
+    uncaughtHint: "一个未被捕获的错误中断了当前视图。",
+    asyncHint: "一个后台任务失败且未被处理。",
+    retry: "重试",
+    details: "查看详情",
+    hideDetails: "收起详情",
+    reported: "已上报宿主",
+  },
+  listDetail: {
+    back: "返回列表",
+  },
+  formSheet: {
+    discardTitle: "放弃这次修改？",
+    discardBody: "改动还没有保存，现在关闭就会丢掉。",
+    keepEditing: "继续编辑",
+    discard: "放弃",
+  },
+  wizardShell: {
+    back: "上一步",
+    next: "下一步",
+    finish: "完成",
+    working: "处理中…",
+    stepOf: (n: number, total: number) => `第 ${n} / ${total} 步`,
+  },
+  settingsSplit: {
+    nav: "章节导航",
+  },
+};